Conversational analytics (AI) in embedding

Introduction

Ask AI brings conversational analytics to your embedded application. Your embed users can ask questions in natural language to explore data, get insights, and dig deeper into charts.

To make the assistant feel like part of your product, you can give it your own icon, name, and welcome message with White-label Ask AI.

Prerequisites

To use Ask AI in your embed, make sure you have:

• AI enabled in your workspace. It powers the natural language query capabilities.
• Embedded Analytics enabled, with the AI feature turned on for embedding. Ask AI in embedding is available on select plans. If your team does not have access, please contact us.
• At least one dataset in your embed payload (see Dataset access below).

Enable Ask AI

To enable AI features for your embed users, set settings.ai.enabled parameters to true in your embed payload:

const payload = {
  objects: {
    dashboards: ['sales_dashboard'],
    datasets: ['ecom_dataset'],     // Ask AI answers questions from this dataset
  },
  embed_user_id: 'user_123',
  embed_org_id: 'org_123',
  settings: {
    ai: {
      enabled: true,  // Enable Ask AI feature
    }
  },
  exp: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
}

Configure data access & permissions

Ask AI can only query and return data the current embed user is permitted to see. It automatically enforces the data permissions in your embed.

Dataset access

Ask AI can query only the datasets included in your embed. Add them to objects.datasets in the payload:

const payload = {
  objects: {
    dashboards: ['sales_dashboard'],
    datasets: [
      'ecom_dataset',       // Ask AI can query this dataset
      'marketing_dataset',  // Ask AI can query this dataset
    ],
  },
  settings: { ai: { enabled: true } },
}

If you persist your setup as an Embed Portal, list the datasets in the portal's objects instead.

warning

Include at least one dataset, otherwise Ask AI won't be able to answer questions.

Row-level permissions (RLP)

Ask AI runs every query as the current embed user, so row-level permissions are applied automatically. Users only see rows they're permitted to access.

Set Ask AI as the default page (optional)

You can make the embed open directly to the Ask AI interface. There are two ways to do this:

Option 1: Using the Embed Portal definition

If you persist your setup as an Embed Portal, set initial_object in your .embed.aml file:

sales_portal.embed.aml

EmbedPortal sales_portal {
  objects: [
    sales_overview,
    revenue_trends,
  ],
  initial_object: 'ai'   // Open Ask AI as the default page
}

Option 2: Using URL path

Append /ai to your embed URL:

https://{region_domain}.holistics.io/embed/{embed_key_id}/ai?_token={generated_token}

Replace {region_domain} with secure, us, or eu. If you use a custom domain, replace the full {region_domain}.holistics.io host with your custom domain.

This works with or without an Embed Portal, and overrides any initial_object set in the portal. It lets you control which page users land on per link.

For more URL customization options, see the Embed payload reference.

White-label Ask AI

You can customize the Ask AI interface to match your brand by setting a custom icon, assistant name, welcome message, and prompt placeholders. See White-label Ask AI for the full reference, and Customization & Styling to match the rest of the embed to your brand.

Learn more

For more information about the underlying AI capabilities, see:

• Holistics AI Overview
• Ask AI in Natural Language