> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/events.md).

# Events

Read the bound device's event timeline and act on events: comment, resolve, archive and add notes. Every method returns a Promise and targets the widget's bound device.

### Event objects

```ts
type EventLogId = string;   // decimal form of a positive 64-bit integer — keep it a string

interface EventsPage {
  events: DeviceEvent[];
  offset: number;
  limit: number;
  nextOffset: number;       // offset + events.length
  hasMore: boolean;
}

interface DeviceEvent {
  id: EventLogId;           // pass this back as logEventId
  eventId: number;          // product event definition ID
  eventType: string;        // 'ONLINE' | 'OFFLINE' | 'INFORMATION' | 'WARNING' | 'CRITICAL'
                            // | 'CONTENT' | 'INACTIVE' | 'LIFECYCLE' | 'NOTE' | 'UNKNOWN' | …
  ts: number;               // Unix ms
  name: string | null;
  description: string | null;
  icon: string | null;
  color: string | null;
  resolved: boolean;
  resolvedAt: number | null;
  resolvedBy: string | null;
  resolvedComment: string | null;
  archivedAt: number | null;
  archivedBy: string | null;
  canResolve: boolean;      // host state at read time, not an authorization grant
  canArchive: boolean;
  commentsCount: number;    // comments are NOT embedded in the page
  content: null | { subtitle: string | null; actionTitle: string | null;
                    actionUrl: string | null; imageUrl: string | null };  // content events only
  note:    null | { title: string | null; description: string | null;
                    imageUrls: string[] };                                  // note events only
}

interface EventComment {
  id: EventLogId;
  logEventId: EventLogId;
  comment: string;
  email: string | null;
  userId: EventLogId;       // '0' for a system actor
  images: string[];
  createdAt: string | null; // ISO 8601 with time zone
}

interface EventMutation {
  id: EventLogId | null;    // null only for createDeviceEventNote
  acknowledged: true;       // resolves only after the server acknowledges
}
```

A mutation acknowledgement doesn't carry the updated event — re-read the page to show the committed state.

**Event IDs and text**

* `logEventId` is a **string** with the decimal form of a positive 64-bit integer, e.g. `'1234567890123'`, as returned in `DeviceEvent.id`. 64-bit IDs lose precision as JavaScript numbers, so a number rejects with `invalid_request`.
* Use IDs from a page loaded under the current widget binding. After a reload or a device switch, load the page again.
* Text is trimmed before it's sent and must not be empty afterwards. Length limits:

  | Text               | Web  | Mobile |
  | ------------------ | ---- | ------ |
  | `comment`          | 300  | 300    |
  | note `title`       | 300  | 300    |
  | note `description` | 2000 | 2000   |
  | `resolveComment`   | 2000 | 300    |

  Keep `resolveComment` within 300 characters if your widget must run on both. White-label apps can configure their own limits.

**Errors** — every events method fails with a `BlynkBridgeError`:

| Code                     | When                                                                   |
| ------------------------ | ---------------------------------------------------------------------- |
| `invalid_options`        | Options are invalid or out of range                                    |
| `invalid_request`        | Invalid `logEventId`, text or note, or a request over 64 KB            |
| `timeline_access_denied` | The user lacks timeline or device view/edit permission                 |
| `event_not_found`        | The event doesn't exist on the bound device, or not for this operation |
| `event_not_resolvable`   | Not an unresolved warning or critical event                            |
| `event_not_archivable`   | Can't be archived, or already archived                                 |
| `event_not_unarchivable` | Not archived                                                           |
| `comments_limit_reached` | The per-event comment cap (currently 50) is reached                    |
| `note_not_supported`     | The device's product doesn't support notes                             |
| `device_changed`         | The page, account or bound device changed before the call finished     |
| `request_timeout`        | No acknowledgement within 30 seconds — a write's outcome is unknown    |
| `response_too_large`     | The result exceeds 5 MiB — use smaller pages                           |
| `device_unavailable`     | The host has no events bridge, or no device is bound                   |
| `transport_disconnected` | The result couldn't be fetched                                         |
| `server_error`           | The platform failed without a specific code                            |
| `bridge_destroyed`       | Called after `destroy()`                                               |

The platform can also pass its own codes through `code`, `message` and `details`.

***

### Get events permissions

> Tells whether the user can view and edit the bound device's events.

```js
bridge.getDeviceEventsPermissions()  // → Promise<{ canView: boolean, canEdit: boolean }>
```

**Parameters:** none. Use it, or `isPermissionAllowed('VIEW_EVENTS' | 'EDIT_EVENTS')`, to hide controls the user can't use.

***

### Get device events

> Returns one page of the bound device's timeline, newest first.

```js
bridge.getDeviceEvents(options?)  // → Promise<EventsPage>
```

**Parameters**

| Name               | Type       | Required | Default      | Description                                                                                      |
| ------------------ | ---------- | -------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `options.from`     | `number`   | no       | `to` − 24 h  | Start, Unix ms. Must be **less than** `to`                                                       |
| `options.to`       | `number`   | no       | `Date.now()` | End, Unix ms                                                                                     |
| `options.limit`    | `number`   | no       | `100`        | Integer from 1 to 100                                                                            |
| `options.offset`   | `number`   | no       | `0`          | Non-negative integer; `offset + limit` must fit a signed 32-bit integer                          |
| `options.eventIds` | `number[]` | no       | `[]`         | Up to 100 **product event** IDs (`DeviceEvent.eventId`) to filter by                             |
| `options.search`   | `string`   | no       | —            | Up to 255 characters. `''` and `null` mean no filter. Trim it yourself if it comes from an input |

All numeric options must be integers. `options` must be a plain object; an unknown key rejects (`invalid_request` or `invalid_options`, depending on the host).

**Resolves with** an [`EventsPage`](#event-objects).

**Example**

```js
if (await bridge.isPermissionAllowed('VIEW_EVENTS').catch(() => false)) {
  const page = await bridge.getDeviceEvents({ limit: 20 });   // last 24 hours
  renderTimeline(page.events);
  if (page.hasMore) loadMoreAt(page.nextOffset);
}
```

***

### Get event comments

> Returns the comments of one event.

```js
bridge.getDeviceEventComments(logEventId)  // → Promise<EventComment[]>
```

| Name         | Type     | Required | Description                         |
| ------------ | -------- | -------- | ----------------------------------- |
| `logEventId` | `string` | yes      | `DeviceEvent.id` from a loaded page |

Resolves with `[]` when there are none. Comments aren't embedded in a page; `commentsCount` tells you whether to load them.

***

### Add an event comment

> Adds a text comment to an event.

```js
bridge.addDeviceEventComment(logEventId, comment)  // → Promise<EventComment>
```

| Name         | Type     | Required | Description                                    |
| ------------ | -------- | -------- | ---------------------------------------------- |
| `logEventId` | `string` | yes      | `DeviceEvent.id`                               |
| `comment`    | `string` | yes      | Non-empty after trimming, up to 300 characters |

Resolves with the created comment. Fails with `comments_limit_reached` once the event has 50 comments.

***

### Resolve an event

> Resolves an unresolved warning or critical event.

```js
bridge.resolveDeviceEvent(logEventId, resolveComment?)  // → Promise<EventMutation>
```

| Name             | Type     | Required | Description                                                                              |
| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------- |
| `logEventId`     | `string` | yes      | `DeviceEvent.id` of an event with `canResolve: true`                                     |
| `resolveComment` | `string` | no       | Optional note. `''`, `null` and `undefined` mean no comment. See the length limits above |

Fails with `event_not_resolvable` for other events.

***

### Archive and unarchive an event

> Moves an event to the archive, or back.

```js
bridge.archiveDeviceEvent(logEventId)    // → Promise<EventMutation>
bridge.unarchiveDeviceEvent(logEventId)  // → Promise<EventMutation>
```

| Name         | Type     | Required | Description                                                       |
| ------------ | -------- | -------- | ----------------------------------------------------------------- |
| `logEventId` | `string` | yes      | `DeviceEvent.id`; for archiving, an event with `canArchive: true` |

Fail with `event_not_archivable` / `event_not_unarchivable`.

***

### Create a timeline note

> Adds a note to the bound device's timeline.

```js
bridge.createDeviceEventNote({ title, description })  // → Promise<EventMutation>   id is null
```

| Name          | Type     | Required | Description                      |
| ------------- | -------- | -------- | -------------------------------- |
| `title`       | `string` | yes      | Non-empty, up to 300 characters  |
| `description` | `string` | yes      | Non-empty, up to 2000 characters |

The object takes only these two properties. Fails with `note_not_supported` when the product doesn't support notes.

**Example — acting on events**

```js
if (await bridge.isPermissionAllowed('EDIT_EVENTS').catch(() => false)) {
  const logEventId = '1234567890123';   // always a string, from DeviceEvent.id
  await bridge.addDeviceEventComment(logEventId, 'Technician on site');
  await bridge.resolveDeviceEvent(logEventId, 'Filter replaced');
  await bridge.createDeviceEventNote({ title: 'Maintenance', description: 'Quarterly check done' });
  const page = await bridge.getDeviceEvents({ limit: 20 });   // re-read the committed state
  renderTimeline(page.events);
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
