Embedding AI Builder Chatflows

Enterprise

Once a chatflow is built and deployed in Calabi AI Builder, you can surface it in multiple channels: an HTML iframe, a floating widget on your web properties, a REST API endpoint, a Slack bot, or a Microsoft Teams app. This page covers every embedding option with complete code examples.

Embedding Overview

Method	Best For	Setup Complexity
iframe	Internal portals, intranet pages, Notion embeds	Low
JavaScript Widget	Public websites, customer-facing portals	Low
REST API	Backend integrations, mobile apps, custom UI	Medium
Slack Bot	Team-facing knowledge bots, HR bots	Medium
Microsoft Teams Bot	Enterprise Teams deployments	Medium

Getting Your Chatflow ID and API Key

Before embedding, you need:

Chatflow ID: Open the chatflow in AI Builder → copy the ID from the URL:
```
https://<your-calabi-domain>/ai-builder/canvas/<CHATFLOW_ID>
```
API Key: Go to AI Builder → Settings → API Keys → + Create API Key.

iframe Embed

The simplest embedding option. The full chat UI is rendered inside an <iframe> — no frontend code required.

<!-- Basic iframe embed -->
<iframe
  src="https://<your-calabi-domain>/chatbot/<CHATFLOW_ID>"
  style="
    width: 100%;
    height: 700px;
    border: none;
    border-radius: 8px;
    box-shadow: 0 4px 24px rgba(0,0,0,0.1);
  "
  allow="microphone"
  title="Calabi AI Assistant"
></iframe>

iframe with Pre-filled Context

Pass a ?overrideConfig query parameter to pre-populate the chatflow with user context:

<iframe
  src="https://<your-calabi-domain>/chatbot/<CHATFLOW_ID>?overrideConfig=%7B%22sessionId%22%3A%22user-123%22%7D"
  style="width: 100%; height: 700px; border: none;"
  title="Calabi AI Assistant"
></iframe>

The overrideConfig value is a URL-encoded JSON object:

{
  "sessionId": "user-123",
  "vars": {
    "user_department": "Engineering",
    "user_role": "Data Engineer"
  }
}

iframe Customization

The iframe URL accepts the following query parameters:

Parameter	Type	Description
`theme`	`light` / `dark`	Override the UI theme
`fullscreen`	`true`	Remove the chat panel border/shadow
`showTitle`	`false`	Hide the chatflow title from the header
`welcomeMessage`	URL-encoded string	Custom welcome message
`fontSize`	number (px)	Override the chat font size

The floating chat widget adds a chat bubble to your web page. When clicked, it opens a full chat panel.

Installation

Add the following script to your HTML <head>:

<script type="module">
  import Chatbot from 'https://<your-calabi-domain>/api/v1/chatbot-widget/bundle';

  Chatbot.init({
    chatflowid: '<CHATFLOW_ID>',
    apiHost: 'https://<your-calabi-domain>',
    chatflowConfig: {
      /* Optional: override chatflow variables */
    },
    theme: {
      button: {
        backgroundColor: '#1a56db',
        right: 20,
        bottom: 20,
        size: 56,
        iconColor: '#ffffff',
        customIconSrc: 'https://your-domain.com/icon.png', /* Optional custom icon */
      },
      chatWindow: {
        showTitle: true,
        title: 'Calabi Assistant',
        titleAvatarSrc: 'https://your-domain.com/avatar.png',
        welcomeMessage: 'Hello! How can I help you today?',
        backgroundColor: '#ffffff',
        height: 700,
        width: 400,
        fontSize: 16,
        poweredByTextColor: '#8e8ea0',
        botMessage: {
          backgroundColor: '#f7f8ff',
          textColor: '#303235',
          showAvatar: true,
          avatarSrc: 'https://your-domain.com/bot-avatar.png',
        },
        userMessage: {
          backgroundColor: '#1a56db',
          textColor: '#ffffff',
          showAvatar: true,
          avatarSrc: 'https://your-domain.com/user-avatar.png',
        },
        textInput: {
          placeholder: 'Ask me anything...',
          backgroundColor: '#ffffff',
          textColor: '#303235',
          sendButtonColor: '#1a56db',
        },
      },
    },
  });
</script>

To maintain per-user conversation history, pass a sessionId:

Chatbot.init({
  chatflowid: '<CHATFLOW_ID>',
  apiHost: 'https://<your-calabi-domain>',
  chatflowConfig: {
    sessionId: window.currentUser.id,  // Your app's user identifier
    vars: {
      user_name: window.currentUser.name,
      user_email: window.currentUser.email,
    },
  },
});

REST API Endpoint

For full control over the UI or for backend-to-backend integration, use the Calabi AI Builder REST API directly.

Sending a Message

curl -X POST \
  "https://<your-calabi-domain>/api/v1/prediction/<CHATFLOW_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the data retention policy for customer records?",
    "overrideConfig": {
      "sessionId": "session-abc123"
    }
  }'

Response:

{
  "text": "According to our data retention policy, customer records are retained for 7 years after the last transaction...",
  "question": "What is the data retention policy for customer records?",
  "chatId": "chat-xyz789",
  "chatMessageId": "msg-001",
  "sessionId": "session-abc123",
  "memoryType": "redis",
  "sourceDocuments": [
    {
      "pageContent": "Section 3.1 — Customer Data Retention...",
      "metadata": {
        "source": "data_retention_policy.pdf",
        "page": 5,
        "loc": { "lines": { "from": 142, "to": 167 } }
      }
    }
  ],
  "usedTools": []
}

Streaming Responses

For real-time token streaming in your frontend:

const response = await fetch(
  `https://<your-calabi-domain>/api/v1/prediction/<CHATFLOW_ID>`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <YOUR_API_KEY>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      question: 'Summarize the onboarding process for new employees.',
      streaming: true,
      overrideConfig: { sessionId: 'session-abc123' },
    }),
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  // Each chunk is a Server-Sent Event: "data: <token>  "
  const token = chunk.replace(/^data: /, '').trim();
  if (token !== '[DONE]') {
    process.stdout.write(token); // Or append to your UI
  }
}

Uploading Files with a Question

curl -X POST \
  "https://<your-calabi-domain>/api/v1/prediction/<CHATFLOW_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F "question=Summarize this document" \
  -F "files=@/path/to/document.pdf"

Slack Bot

The Slack Bot integration lets team members interact with a chatflow directly in Slack via direct messages or channel mentions.

Step 1: Create a Slack App

Go to api.slack.com/apps → Create New App → From Scratch.
Name: Calabi Assistant (or your preferred name).
Under OAuth & Permissions, add these Bot Token Scopes:
- app_mentions:read
- chat:write
- im:history
- im:write
Under Event Subscriptions:
- Enable Events.
- Request URL: https://<your-calabi-domain>/api/v1/slack/<CHATFLOW_ID>/events
- Subscribe to: app_mention, message.im
Install to workspace and copy the Bot Token (xoxb-...) and Signing Secret.

Step 2: Configure in AI Builder

Open the chatflow → Settings → Integrations → Slack.
Enter:
- Bot Token: xoxb-...
- Signing Secret: from the Slack app settings
Click Save Integration.

Step 3: Invite the Bot to Channels

/invite @CalabiAssistant

Team members can then mention the bot:

@CalabiAssistant what is the PTO policy for contractors?

The bot responds in a thread with the chatflow's answer, including source citations if RAG is configured.

Microsoft Teams Bot

Step 1: Register an Azure Bot

In the Azure Portal, go to Azure Bot Services → Create.
Bot handle: CalabiAssistant.
Messaging endpoint: https://<your-calabi-domain>/api/v1/teams/<CHATFLOW_ID>/messages.
Note the Microsoft App ID and App Password (client secret).

Step 2: Configure in AI Builder

Open the chatflow → Settings → Integrations → Microsoft Teams.
Enter:
- Microsoft App ID: from Azure Bot registration
- App Password: the client secret
Click Save Integration.

Step 3: Deploy to Teams

Download the Teams app manifest from AI Builder → Settings → Teams Manifest.
In Microsoft Teams → Apps → Manage your apps → Upload an app → select the manifest zip.

Users can now chat with the bot in Teams:

@CalabiAssistant show me the expense reimbursement process

Security for Embedded Chatflows

Security Control	Default	How to Configure
API Key required	Yes	Required for API and Slack/Teams integrations
CORS allowed origins	All origins	Restrict in AI Builder → Settings → CORS Origins
Rate limiting	100 req/min per API key	Adjust in Helm values: `aiBuilder.rateLimits`
Allowed iframe origins	All	Set `Content-Security-Policy` in your web server or Helm
Message logging	Enabled (audit only)	Disable message content logging in tenant settings

Building Chatflows — Create and configure the chatflow being embedded
RAG Agents — Build document Q&A agents for embedding
Managing Credentials — Securely store Slack and Teams tokens

Embedding Overview​

Getting Your Chatflow ID and API Key​

iframe Embed​

iframe with Pre-filled Context​

iframe Customization​

JavaScript Widget​

Installation​

Passing User Identity to the Widget​

REST API Endpoint​

Sending a Message​

Streaming Responses​

Uploading Files with a Question​

Slack Bot​

Step 1: Create a Slack App​

Step 2: Configure in AI Builder​

Step 3: Invite the Bot to Channels​

Microsoft Teams Bot​

Step 1: Register an Azure Bot​

Step 2: Configure in AI Builder​

Step 3: Deploy to Teams​

Security for Embedded Chatflows​

Related Pages​

Embedding Overview

Getting Your Chatflow ID and API Key

iframe Embed

iframe with Pre-filled Context

iframe Customization

JavaScript Widget

Installation

Passing User Identity to the Widget

REST API Endpoint

Sending a Message

Streaming Responses

Uploading Files with a Question

Slack Bot

Step 1: Create a Slack App

Step 2: Configure in AI Builder

Step 3: Invite the Bot to Channels

Microsoft Teams Bot

Step 1: Register an Azure Bot

Step 2: Configure in AI Builder

Step 3: Deploy to Teams

Security for Embedded Chatflows

Related Pages