# Listening events

## Overview

An *event* fires at dashboard load time or when a specific dashboard action occurs. Register a handler with `ubidots.on()` — the callback receives the event argument when the event fires.

## Registering for an event

```javascript
ubidots.on('<event>', function(payload) {
    // your logic here
});
```

## Available events

| Event                             | Triggered when                                                                         | Argument                            |
| --------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
| `v2:auth:token`                   | At dashboard load time, when the user's API token is retrieved.                        | `string`                            |
| `v2:auth:jwt`                     | At dashboard load time, when the user's JWT token is retrieved.                        | `string`                            |
| `v2:auth:*`                       | At dashboard load time, when either the API token or JWT is retrieved.                 | `string`                            |
| `v2:dashboard:settings:daterange` | The dashboard's date range is changed via the GUI or programmatically.                 | [Timeframe](#timeframe-object)      |
| `v2:dashboard:settings:rt`        | The dashboard's real-time setting is toggled via the GUI or programmatically.          | `boolean`                           |
| `v2:dashboard:settings:refreshed` | A user clicks the refresh button in the dashboard.                                     | —                                   |
| `v2:dashboard:settings:filters`   | The dashboard's filters configuration is changed.                                      | [Filters](#filters-array)           |
| `v2:dashboard:devices:self`       | At dashboard load time, with all devices associated with the dashboard.                | [Device\[\]](#device-object)        |
| `v2:dashboard:devices:selected`   | The selected device in a dynamic dashboard is changed via the GUI or programmatically. | [Device\[\]](#device-object)        |
| `v2:dashboard:self`               | At dashboard load time, when the dashboard metadata is retrieved.                      | [Dashboard](#dashboard-object)      |
| `v2:dashboard:*`                  | Any of the above dashboard events fire (catch-all).                                    | varies (same as the specific event) |
| `v2:widget:ready`                 | At dashboard load time, after all other events have been triggered.                    | —                                   |

{% hint style="warning" %}
`v2:auth:*` and `v2:dashboard:*` are the only supported wildcards. Patterns like `v2:dashboard:settings:*` are **not valid** — the callback is silently discarded and never fires.
{% endhint %}

## Payload reference

### Device object

Delivered by `v2:dashboard:devices:self` (all dashboard devices) and `v2:dashboard:devices:selected` (currently selected devices). Both events always deliver an **array**, even for a single selection.

```json
{
    "url": "https://industrial.ubidots.com/api/v2.0/devices/<device-id>",
    "id": "<device-id>",
    "label": "<device-label>",
    "name": "<device-name>",
    "description": "",
    "createdAt": "<ISO-timestamp>",
    "lastActivity": <unix-timestamp-ms>
}
```

### Timeframe object

Delivered by `v2:dashboard:settings:daterange`. Both values are Unix timestamps in **milliseconds**.

```json
{
    "start": 1710000000000,
    "end": 1710086400000
}
```

### Filters array

Delivered by `v2:dashboard:settings:filters`. Each outer array is a filter group (OR logic between groups); each inner array contains the conditions for that group (AND logic within a group).

```json
[
    [
        { "type": "value", "value": "60", "variables": "~temperature", "lookup": "lte", "negate": false },
        { "type": "value", "value": "30", "variables": "~temperature", "lookup": "gte", "negate": false }
    ],
    [
        { "type": "value", "value": "60", "variables": "~humidity", "lookup": "lte", "negate": false }
    ]
]
```

### Dashboard object

Delivered by `v2:dashboard:self`.

```json
{
    "id": "<dashboard-id>",
    "label": "<dashboard-label>",
    "name": "<dashboard-name>",
    "context": { "dashboardType": "<type>" },
    "widgetsNumber": 4,
    "isEditable": true,
    "timeframe": {}
}
```

## Class properties

Each event also populates a property on the `ubidots` instance. After `v2:widget:ready` fires, all properties are set and can be read synchronously — no handler needed.

| Property                     | Populated by                      |
| ---------------------------- | --------------------------------- |
| `ubidots.token`              | `v2:auth:token`                   |
| `ubidots.jwtToken`           | `v2:auth:jwt`                     |
| `ubidots.dashboardDateRange` | `v2:dashboard:settings:daterange` |
| `ubidots.realTime`           | `v2:dashboard:settings:rt`        |
| `ubidots.selectedFilters`    | `v2:dashboard:settings:filters`   |
| `ubidots.dashboardDevices`   | `v2:dashboard:devices:self`       |
| `ubidots.selectedDevices`    | `v2:dashboard:devices:selected`   |
| `ubidots.dashboardObject`    | `v2:dashboard:self`               |

## Examples

### Fetch device data whenever the selection changes

```javascript
ubidots.on('v2:dashboard:devices:selected', function(devices) {
    const device = devices[0];
    fetch('https://industrial.api.ubidots.com/api/v1.6/devices/' + device.label + '/', {
        headers: ubidots.getHeaders()
    })
    .then(res => res.json())
    .then(data => renderWidget(data));
});
```

### Sync a custom date picker with the dashboard

```javascript
ubidots.on('v2:dashboard:settings:daterange', function(timeframe) {
    myDatePicker.setRange(
        new Date(timeframe.start),
        new Date(timeframe.end)
    );
});
```

### Gate rendering on ready, then use token for API calls

```javascript
ubidots.on('v2:widget:ready', function() {
    // All load-time events have fired — safe to read any property
    const headers = ubidots.getHeaders();
    const device  = ubidots.selectedDevices[0];
    loadChartData(device, headers);
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ubidots.com/dashboards-and-widgets/html-canvas/built-in-library/listening-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.