Embed an AI Chat

Target Audience: Developers

Goal

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

---

Prerequisites

• At least one connected and active database.

• A valid API key for token generation.

• (Recommended): Enriched metadata to improve the AI assistant's accuracy.

• (Recommended): Row-Level Security (RLS) configured for multi-tenant data isolation.

---

Steps

1. Prepare the data layer

• Execute an AI analysis on your datasets to generate semantic metadata.

• 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 RLS

• 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 token

• 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 code

• 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 test

• 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 SaaS

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

Step	Configuration
Attribute	customer_id defined in the token.
RLS Mapping	Token customer_id maps to database customer_id column.
User Query	"How many hires last quarter?".
Execution	The query is automatically filtered by customer_id before execution.
Result	The user only sees data belonging to their specific organization.

---

Conclusion

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.