> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/embed/events/consume",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Consuming embed events sent by Omni

> Consume events emitted by Omni to trigger interactions in your application.

Using JavaScript events, you can trigger interactions in your application based on events in an Omni iframe.

## Event shape

Events emitted by Omni use the [`postMessage` protocol](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) and will have the following shape:

```typescript theme={null}
type EmbedEvent<Payload> = {
  payload: Payload
  description: string
  name: EmbedEventName
}
```

## Listening for events

Subscribe to events in the parent frame with the following:

```javascript expandable wrap theme={null}
const setFrameHeight = (height) => {
  // do the work to set the iframe element's height here
  // eg. `iframeElement.height = height`
}

const listener = (event) => {
  // Only accept messages from a known origin
  if (event.origin !== "https://example.embed-omniapp.co") return

  switch (event.data.name) {
    case 'size': {
      const { height } = event.data.payload
      height && setFrameHeight(height)
      break
    }
    case 'page:changed': {
      // Do something with the page:changed event, etc
    }
  }
}

// Must attach the event listener for messages.
window.addEventListener('message', listener)
```

## Supported events

Omni currently emits the following events:

| Event                                                                | Description                                                                                                     |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`ai:chat-start`](/embed/events/ai-chat-start)                       | Emitted by Omni when an AI chat session begins.                                                                 |
| [`dashboard:download`](/embed/events/dashboard-download)             | Emitted by Omni when a user downloads an embedded dashboard.                                                    |
| [`dashboard:filter-changed`](/embed/events/dashboard-filter-changed) | Emitted by Omni when a user adds, removes, or updates a filter on an embedded document.                         |
| [`dashboard:filters`](/embed/events/dashboard-filters)               | Emitted by Omni when a user applies a filter to an embedded document.                                           |
| [`dashboard:tile-download`](/embed/events/dashboard-tile-download)   | Emitted by Omni when a user downloads a given tile on a dashboard.                                              |
| [`dashboard:tile-drill`](/embed/events/dashboard-tile-drill)         | Emitted by Omni when a user performs a drill action on a dashboard tile.                                        |
| [`error`](/embed/events/error)                                       | Emitted by Omni when a detectable error occurs on an embedded page.                                             |
| [`navigation:home`](/embed/events/navigation-home)                   | Emitted by Omni when a user clicks the logo or home link in the navigation header.                              |
| [`page:changed`](/embed/events/page-changed)                         | Emitted by Omni when the URL of a page changes.                                                                 |
| [`sidebar:open`](/embed/events/sidebar-open)                         | Emitted by Omni when a user clicks the mobile menu button.                                                      |
| [`size`](/embed/events/size)                                         | Emitted by Omni on dashboard load to give the size of the frame, allowing users to dynamically size the iframe. |
| [`status`](/embed/events/status)                                     | Emitted by Omni to indicate the status of the dashboard to the parent frame.                                    |