AI Chatbot

Let your end-users ask questions of their data in natural language — and get back both text explanations and live charts, without ever leaving your product.

The AI Chatbot is a ready-made chat widget, <em-ai-chat>, that works in plain HTML, React, Vue, Angular, or any other framework. End users type a question; the AI queries their data, renders charts, and can even add, edit, resize, or reorder charts on their Custom Canvas on their behalf.

You can use it in two ways:

• Alongside a dashboard — render <em-ai-chat> next to your <em-beddable> dashboard. The AI can answer questions and manage the user's Custom Canvas conversationally.
• Standalone chat — render only the chat, with no visible dashboard. The AI still answers questions and previews charts in the conversation. See Standalone chat.

How it works

The AI Chatbot is made up of three pieces that work together:

• <em-ai-chat> — a web component you drop into your page. It connects to the AI orchestrator over a WebSocket and authenticates using the same security tokens you already generate for your users.
• AI Orchestrator — hosted by Embeddable. Receives messages from the chatbot, calls your LLM using the API key you've saved in the platform, queries your data models, and streams responses back.
• LLM config — a one-time API call (POST /api/v1/llm-config) where you save your LLM provider, API key and extra configuration. This is how you bring your own key (BYOK).

End user types a question
  │
  ▼
<em-ai-chat>  (WebSocket)
  │
  ▼
AI Orchestrator  (Embeddable-hosted)
  │  ├── calls your LLM with the key saved in the platform (encrypted at rest)
  │  ├── queries the datasets you've enabled for Custom Canvas
  │  └── enforces row-level security from the security token
  │
  ▼
Response streamed back → text + rendered charts

Prerequisites

The chatbot gets its data access and its chart vocabulary from Custom Canvas. Before adding it, you need a dashboard with:

1. Custom Canvas enabled — toggle it on beneath your main canvas in the builder.
2. At least one dataset enabled for Custom Canvas — these are the only datasets the AI can query. Without them, it can't answer data questions.
3. At least one chart template in the Template Library — these are the only chart types the AI can render. Without them, it can answer in text but can't show charts. The more templates you define (and the more open you leave their inputs), the more the AI can do.
4. The dashboard published — the chatbot reads the published configuration, not your draft.

Setup

curl -X POST https://api.<region>.embeddable.com/api/v1/llm-config \
  -H "Authorization: Bearer <your-embeddable-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "model": "claude-sonnet-4-5",
    "apiKey": "<your-llm-provider-api-key>",
    "systemPrompt": "You are a helpful analytics assistant."
  }'

curl -X POST https://api.<region>.embeddable.com/api/v1/security-token \
  -H "Authorization: Bearer <your-embeddable-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddableId": "<your-embeddable-id>",
    "user": "user-123",
    "securityContext": { "userId": "user-123" },
    "expiryInSeconds": 3600
  }'

<script type="module" src="https://unpkg.com/@embeddable.com/ai-chat@0.2.1/dist/ai-chat/ai-chat.esm.js"></script>

<div style="width: 420px; height: 600px;">
  <em-ai-chat
    mode="inline"
    orchestrator-url="wss://api.<region>.embeddable.com/ws"
    embeddable-tokens='["<security-token>"]'
  ></em-ai-chat>
</div>

<em-ai-chat
  mode="modal"
  placement="bottom-right"
  orchestrator-url="wss://api.<region>.embeddable.com/ws"
  embeddable-tokens='["<security-token>"]'
>
  <button slot="trigger">Open chat</button>
</em-ai-chat>

Standalone chat (no visible dashboard)

You can offer AI chat without rendering a dashboard at all — just the <em-ai-chat> component on its own. The Custom Canvas dashboard still does the work behind the scenes: it defines which datasets the AI can query and which chart templates it can render, so it must still be configured and published as described in Prerequisites.

In this setup, we recommend making the canvas read-only so the AI doesn't modify a canvas your users never see. Add customCanvasReadOnly: true when minting the security token:

{
  "embeddableId": "<your-embeddable-id>",
  "user": "user-123",
  "securityContext": { "userId": "user-123" },
  "customCanvasReadOnly": true
}

With a read-only token, the AI can still answer questions and preview charts in the conversation — it just can't add to or otherwise modify the Custom Canvas. Because the flag lives on the token, you can grant different users different levels of access with the same embedded widget.

The end-user experience

End users interact with the chatbot in plain language. The AI can:

• Answer data questions — retrieve and summarise data from any dataset enabled for Custom Canvas, presented as text or charts.
• Add charts to the canvas — place new charts based on what the user asks for.
• Edit existing charts — update a chart's dataset, measure, or filters on request.
• Resize, reorder, and delete charts — rearrange the canvas layout conversationally.
• Collect feedback — end users can rate each response with a thumbs up/down and leave a comment.

Canvas editing requires a token without customCanvasReadOnly — with a read-only token, the AI answers questions and previews charts but leaves the canvas untouched.

Component reference

Attributes

Customizing the UI text

All user-facing text — the welcome message, input placeholder, and feedback dialog copy — can be overridden via the labels property. It's a JavaScript object property, not an HTML attribute:

const chat = document.querySelector('em-ai-chat');
chat.labels = {
  welcomeMessage: 'Hi! Ask me anything about your data.',
  inputPlaceholder: 'Type a question…',
};

Provide any subset of the keys below; omitted keys fall back to the defaults.

Slots

Theming

The chat's visual styling is controlled by --em-ai-chat-* CSS custom properties. If an <em-beddable> is present on the page, the chat automatically inherits its design tokens from the Remarkable UI (opens in a new tab) design system, so it matches your dashboard out of the box.

To customize further (or when there's no <em-beddable> on the page), set the variables directly on em-ai-chat to match your own design:

em-ai-chat {
  /* Shell */
  --em-ai-chat-shell-background: #ffffff;
  --em-ai-chat-shell-border-color: #e4e4ea;
 
  /* Input composer */
  --em-ai-chat-composer-input-border-color: #e4e4ea;
  --em-ai-chat-composer-input-border-color--focus: #2d52cc;
 
  /* Primary icon button (send / cancel) */
  --em-ai-chat-icon-button-primary-background: #2d52cc;
  --em-ai-chat-icon-button-primary-color: #ffffff;
 
  /* Panel size (modal mode) */
  --em-ai-chat-panel-width: 23.75rem;
  --em-ai-chat-panel-height: 32.5rem;
}

The full list of variables ships with the package — see em-ai-chat.tokens.css in the published package (opens in a new tab).

Framework integration

In React, Vue, Angular, or any other bundled app, install the package and register the custom elements once at startup:

import { defineCustomElements } from '@embeddable.com/ai-chat/loader';
defineCustomElements();

Then use <em-ai-chat> like any other HTML element:

return (
  <em-ai-chat
    mode="modal"
    orchestrator-url="wss://api.<region>.embeddable.com/ws"
    embeddable-tokens={JSON.stringify([token])}
  >
    <button slot="trigger">Chat</button>
  </em-ai-chat>
);

export default defineConfig({
  optimizeDeps: {
    exclude: ['@embeddable.com/ai-chat'],
  },
});

Security

Related

• Custom Canvas — where you configure the datasets and chart templates the AI can use
• AI Endpoints — power your own chat UI instead of using the ready-made component
• Tokens API — how to generate the security tokens the chatbot relies on
• Row-level security — how per-user data access is enforced