Embed an AI Chat

GoalCopy Anchor Link

Embed a self-service AI chat from Toucan AI into a host application to enable conversational analytics.

PrerequisitesCopy Anchor Link

• At least one connected and active database.
• A valid API key for token generation.
• (Recommended): Metadata confirmed after AI analysis review to improve the AI assistant's accuracy.
• (Recommended): Row-Level Security (RLS) configured for multi-tenant data isolation.

StepsCopy Anchor Link

1. Prepare the data layerCopy Anchor Link

• Execute an AI analysis on your datasets, then review and confirm proposals so semantic metadata is applied.
• Review column descriptions and metric definitions to ensure the AI assistant has sufficient context.
• High-quality metadata directly improves the relevance of natural language answers.

2. Configure security and RLSCopy Anchor Link

• Define required token attributes (e.g., customer_id or region).
• Map these attributes to specific dataset columns using the RLS interface.
• Validate the configuration with different attribute values to confirm data isolation.

3. Generate an authentication tokenCopy Anchor Link

• Generate a token including all necessary user attributes.
• Set an appropriate expiration time for the session.
• Ensure the token scope includes permission for the AI assistant capability.

4. Retrieve the embed codeCopy Anchor Link

• Locate the embed snippet in your admin panel or use the following standard web component format:

<script type="module" src="https://toucanai.cloud/embed/embed.js"></script>
<link rel="stylesheet" href="https://toucanai.cloud/embed/embed.css" />

<tc-ai-assistant
  auth-token="YOUR_AUTH_TOKEN"
  server-url="https://toucanai.cloud/api"
  data-theme="light"
></tc-ai-assistant>

5. Integrate and testCopy Anchor Link

• Paste the embed code into your application's HTML.
• Replace YOUR_AUTH_TOKEN with a dynamic variable from your backend.
• Load your application and submit a test prompt (e.g., "How many hires last quarter?") to verify the connection.

Multi-tenant Example: HR SaaSCopy Anchor Link

In a multi-tenant environment, the integration follows this logic to ensure data privacy:

ConclusionCopy Anchor Link

The AI assistant is now embedded and respects the security boundaries defined by your authentication tokens. Users can perform ad-hoc analysis through natural language while Toucan AI handles the underlying query generation and data visualization.