Embedding Omni's AI query helper

Omni's AI query helper 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 (aka Blobby) found in the native Omni app.

In this guide, you'll learn how to integrate a whitelabeled version of the query helper directly into your application.

How it works

The embedded chat experience can be tailored to include only the connections, models, and topics you specify:

Up to three pickers (shown in the above image) can display in the chat interface:

Connections - Lists the connections the user has access to. The picker only displays if more than one connection is available.
Models - Lists the available models in the selected connection. The picker only displays if:
- The connection has more than one model, AND
- At least one topic in the model has a defined ai_context parameter
Topics - Lists the available topics in the model. The picker only displays if at least two topics have defined ai_context parameters.

Scoping responses & selecting topics

To scope the AI's response to a specific dataset, users can use the pickers to select a specific topic. When creating your chat experience, keep the following in mind:

Picker menus won't display when a model only has one AI-accessible topic. If a connection has one model with a single AI-accessible topic - determined by the presence of a defined ai_context parameter - the query helper will be scoped only to that topic and the pickers will not display.
If a topic isn't selected and a prompt is provided, the AI will use the prompt to attempt to select the most relevant topic
The AI can't automatically switch topics in chat. To change topics, users will need to manually select a topic using the picker.

Step 1: Define connection access

The first step is to decide which connections you want your users to have access to when using the query helper. 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:

From connection settings

In Omni:

Navigate to Settings > Connections.
Click on the connection.
At the top of the Settings tab, locate the Connection ID field:

Using the API

To programatically retrieve connection IDs, use the List connections API.

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:

GET /api/v1/connections
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 the connection's unique id.

Step 2: Add context to topics

Next, you'll add context to the topics you want users to have access to in the query picker. You can include topics by defining an ai_context parameter in the topic, which will include it in the topic picker:

In Omni, navigate to the models associated with the connections from Step 1.

Next, add an ai_context parameter to the topic(s) you want users to have access to. For example:

Example topic file
base_view: products
label: Product Performance

joins:
  order_items: {}
  distribution_centers: {}
  inventory_items: {}

ai_context: |-
  This topic focuses on the performance of products. The main concepts are orders
  at the line item level in the order items table, 
  inventory in our inventory items table, products in the products table, and 
  the distribution centers that ship the products in the distribution centers table.

  Only respond with accurate answers based on the data that you're aware of.
  Don't pivot unless there is more than one dimension included in the query.

You can also add sample queries to the topic, which will display in the chat interface as clickable questions:

Refer to the Optimizing models for AI guide for more information about curating topics for AI.

Step 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 - externalId, name, and nonce - set the following parameters:

contentPath - Set to /chat
connectionRoles - Use the connection IDs from Step 1 to build an object that specifies the connection roles available to the embed users. For example:
```
{
  "c0f12353-4817-4398-bcc0-d501e6dd2f64":"RESTRICTED_QUERIER"
}
```

If you're using standard SSO embed to create embed sessions, the embed URL you build might look like the following:

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

Step 4: Apply your branding

Heads up!

Reach out to Omni support to enable the AI branding settings.

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 query helper your own and blend it seamlessly with your application.

Navigate to Settings > AI and then click the Branding tab.

Use the settings to configure how you want the query helper to look and then click Save.

How it works​

Scoping responses & selecting topics​

Step 1: Define connection access​

Step 2: Add context to topics​

Step 3: Define embed parameters​

Step 4: Apply your branding​