> ## 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.

# Embedding the Omni Agent

> Integrate a whitelabeled version of the Omni Agent directly into your embedded application.

The [Omni Agent](https://docs.omni.co/ai/chat.md) can be embedded as a standalone page in your application, allowing your users to explore data outside of workbooks using the same AI-powered experience found in the native Omni app.

This is one of [two ways to add AI chat to your embedded application](https://docs.omni.co/embed/customization/ai-chat.md). If you want to use your own chat interface or agent instead, see [Bring your own agent](https://docs.omni.co/embed/customization/ai-chat/your-agent-mcp.md).

![](https://mintcdn.com/omni-e7402367/AHZMUT4Yf5W_XcXL/embed/images/full-page-chat.png?fit=max\&auto=format\&n=AHZMUT4Yf5W_XcXL\&q=85\&s=bda8ffff71179b9c22ea0d2a3c3564a0)

> [!NOTE]
>
> The [**Chat in navigation** setting](https://docs.omni.co/ai/settings/features.md#chat-in-navigation) allows you to control whether the Omni Agent appears in the main [sidebar](https://docs.omni.co/administration/settings/sidebar.md). For embedded scenarios, you can enable the **Chat** setting to allow workbook and dashboard AI functionality while disabling **Chat in navigation** to remove the standalone Omni Agent from the main sidebar.

## How it works

The embedded Omni Agent uses the same [pickers and scoping behavior](https://docs.omni.co/ai/chat.md#scoping-responses) as the native Omni app. When embedding, you can tailor the experience to include only the connections, models, and topics you specify.

> [!NOTE]
>
> When embedding content with [`mode=SINGLE_CONTENT`](https://docs.omni.co/embed/setup/url-parameters/mode), [the chat](https://docs.omni.co/ai/dashboard-assistant.md) uses an inline panel instead of the split-view interface. This prevents users from navigating away from the embedded content, keeping them scoped to the single-content frame.

## 1. Define connection access

The first step is to decide which connections you want your users to have access to when using the Omni Agent. These connections will display in the **Connections** picker below the chatbox.

Start by retrieving the connections' unique IDs. Later in this guide, you'll use the IDs to construct a `connectionRoles` parameter and configure the embed session. You can retrieve connection IDs using either of the following methods:

**Omni UI**

1. In Omni, navigate to **Settings > Connections**.
2. Click on the connection.
3. At the top of the **Settings** tab, locate the **Connection ID** field:

   ![Highlighted Connection ID field in a MotherDuck connection's details page](https://mintcdn.com/omni-e7402367/AHZMUT4Yf5W_XcXL/embed/images/connection-settings-id.png?fit=max\&auto=format\&n=AHZMUT4Yf5W_XcXL\&q=85\&s=41186e7bf9579c93b49a61d37c3a738a)

**API**

To programmatically retrieve connection IDs, use the [List connections API](https://docs.omni.co/api/connections/list-connections.md).

If you want to retrieve a specific connection - such as a connection specific to a client - use the endpoint's filtering functionality. In this example, the request will retrieve a connection named `Blobs R Us`:

```shell wrap title="GET /api/v1/connections" theme={null}
curl -X GET 'https://blobsrus.omniapp.co/api/v1/connections?name=Blobs+R+Us' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'
```

Valid requests to the API will return a `200 OK` status and a response body containing `connection` objects. Each object will contain the connection's unique `id`.

## 2. Curate the topic list

Next, you'll curate the list of topics you want users to have access to in the topic picker. This is accomplished with the [`ai_chat_topics`](https://docs.omni.co/modeling/models/ai-chat-topics) model parameter. This parameter accepts a list of topic names, which will limit access only to the specified topics.

In Omni, navigate to the models associated with the connections from step 1. Add the `ai_chat_topics` parameter and specify the topics that users should have access to:

```yaml title="Example model file" theme={null}
ai_chat_topics: [ Product Performance, Order Transactions]
```

Refer to [Scoping AI chat responses](https://docs.omni.co/ai/chat.md#scoping-responses) for details on how topic configuration affects the picker display and AI behavior.

> [!TIP]
>
> You can add [sample queries](https://docs.omni.co/modeling/develop/ai-optimization.md#add-example-queries-as-context) to accessible topics, which will display in the chat interface as clickable questions:
>
> ![](https://mintcdn.com/omni-e7402367/AHZMUT4Yf5W_XcXL/embed/images/ai-chat-prompts.png?fit=max\&auto=format\&n=AHZMUT4Yf5W_XcXL\&q=85\&s=6738dfd231a472b780a16797f9c87fc1)
>
> Refer to the [Optimizing models for AI guide](https://docs.omni.co/modeling/develop/ai-optimization.md) for more information about curating topics for AI.

## 3. Define embed parameters

The next step is to define the embed parameters to create the chat session for the user. Along with the [required parameters](https://docs.omni.co/embed/setup/url-parameters.md#all-parameters) - `externalId`, `name`, and `nonce` - set the following parameters:

* [`contentPath`](https://docs.omni.co/embed/setup/url-parameters/contentPath) - Set to `/chat`
* [`connectionRoles`](https://docs.omni.co/embed/setup/url-parameters/connectionRoles) - Use the connection IDs from step 1 of this guide to build an object that specifies the connection roles available to the embed users. For example:

  ```json wrap theme={null}
  {  
    "c0f12353-4817-4398-bcc0-d501e6dd2f64":"RESTRICTED_QUERIER"
  }
  ```

If you're using [standard SSO embed](https://docs.omni.co/embed/setup/standard-sso.md) to create embed sessions, the embed URL you build might look like the following:

```shell wrap theme={null}
https://omni.blobsrus.com/embed/login?&connectionRoles=%7B%22c0f12353-4817-4398-bcc0-d501e6dd2f64%22%3A%22RESTRICTED_QUERIER%22%7DcontentPath=%2Fchat&externalId=Blobs+R+Us&mode=SINGLE_CONTENT&name=Blobby&nonce=yRt9RbPRST1pKP0fv4hkZkOcyydnwmWX&signature=prfIqNKkUBYlXiAdXLe_E__w19QbM_-6o3CIi4kkV1s
```

> [!TIP]
>
> To enable voice mode, add the `microphone` permission to your iframe's `allow` attribute. Browsers will block microphone access by default without this permission.
>
> ```html theme={null}
> <iframe src="https://omni.blobsrus.com/embed/login?..." allow="microphone"></iframe>
> ```

## 4. Apply your branding

After you've successfully configured and created an embed session, the last step is to apply your branding styles. While this last step is **optional**, it allows you to make the Omni Agent your own and blend it seamlessly with your application.

Navigate to **AI Hub > General** and then click the [**Branding** tab](https://docs.omni.co/ai/settings/branding.md).

![](https://mintcdn.com/omni-e7402367/AHZMUT4Yf5W_XcXL/embed/images/ai-settings-chat.png?fit=max\&auto=format\&n=AHZMUT4Yf5W_XcXL\&q=85\&s=7d7e02ba2a11130cdbb515395a7314f5)

Use the settings to configure how you want the Omni Agent to look and then click **Save**.

## Next steps

* [Implement AI credit controls](https://docs.omni.co/ai/settings/usage.md) to manage your users' credit consumption
* Define AI credit limits for [embed entity groups](https://docs.omni.co/embed/admin/ai-credits.md) to manage credit usage for individual entities


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.