> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/getting-started/quick-start/embed-a-chat.md).

# Embed a chat

{% hint style="info" %}
**Target Audience**: Non technical users & Developers
{% endhint %}

### Goal

Configure and embed a self-service chat experience into your application, allowing users to explore data using natural language.

***

### Prerequisites

* A [Toucan AI account](/getting-started/quick-start/subscribe-to-toucan.md) and active organization.
* Credentials for a supported SQL database (e.g., PostgreSQL).
* A code editor or environment for testing HTML/web components (e.g., Codepen).

***

### Steps

#### 1: Create an API Key

* Navigate to your Account settings page by clicking on your profile icon in the bottom left corner, then go to the **API Keys** section.
* Create a new **API Key**. Copy it and store it securely.

This key will be used on your backend server to securely generate authentication tokens for your embedded application.

<figure><img src="/files/rjrsP8YNo3k5Lyeak5Ze" alt="API Key"><figcaption></figcaption></figure>

{% hint style="danger" %}
**Security Alert**: This is a secret key. Never expose it in client-side code (HTML, JavaScript). Use it only on your secure backend server.
{% endhint %}

#### 2: Implement a user attribute model

(Optional) Define the attributes that will contextually personalize the experience for your users.

{% hint style="danger" %}
The user model will define user access to data (see "Define Row-Level Security (RLS)").
{% endhint %}

**Register User Attributes**

* Navigate to **Settings > Embed & access**.
* In the **Token Attributes** section, click **Add an attribute**.
* Define the traits you need (e.g., name: `region`, type: `String`). These must match the keys you will send in your user tokens.

<figure><img src="/files/WDVsCHWupWBU7RmTtkAB" alt="Token Attributes"><figcaption></figcaption></figure>

#### 3: Connect to a database

* Navigate to the **Database** tab from the Home Page.
* Click **Add a Database** and select a connector.
* Input connection details including Host, Username, Password, and Database name.
* Click **Test Connection**, then click **Connect**.

{% hint style="info" %}
**Example:** Connect to your HR database containing employee data, including a **location** column with values like Tokyo, Paris, etc.
{% endhint %}

**How-To**: [Add a database](/build/data-connections/how-to/add-a-database.md)

<figure><img src="/files/NEvqa3sCYjdpnkTAd5go" alt=""><figcaption></figcaption></figure>

#### 4: Complete Metadata Information

* Review existing table and column descriptions for accuracy.
* **(Optional)**: Click the **Analyze** button to trigger an AI scan of the database.
  * The AI generates descriptions for tables and columns based on the scanned data.
  * AI identifies specific column types, such as location data, to prepare them for visualization.
  * Review and modify the AI-generated descriptions to ensure they provide correct context for the dashboard.
* Ensure all critical columns are described plainly to improve future AI prompt results.

**How-To**: [Analyze your database with AI](/build/analyze-your-database-with-ai/how-to/analyze-your-database-with-ai.md)

<figure><img src="/files/pchipWr66RkQE1pXwl7u" alt="Analyze Your Database"><figcaption></figcaption></figure>

#### 5: Define Row-Level Security (RLS)

Secure your data so users only see what they are authorized to access.

1. Go to the **Database** tab and select a table.
2. In the **Access rules** section, map a **User Attribute** to a specific **dataset field** (a column of the table).
   * *Example*: Map the `user.region` attribute to the `sales_region` column.

This ensures that the AI automatically applies a filter (e.g., `WHERE sales_region = "North"`) based on the user attribute.

**How-To**: [Apply RLS to your database](https://github.com/ToucanToco/toucan-ai/blob/main/docs/permissions-and-row-level-security/how-to/apply-rls-to-your-database.md)

#### 6: Configure a chat

In the menu, go to the [chat page](https://toucanai.cloud/chat), and click "Embed" in the top right corner, then copy the snippet provided.

When configuring your embed, you can choose between two experiences:

* **AI chat only:** embed only the conversational interface.
* **AI chat + dashboard**: embed the chat with a personal dashboard for each user. The dashboard is linked to the provided `auth-token` .

<figure><img src="/files/V226FBDinjoQVxv9T6Fo" alt=""><figcaption></figcaption></figure>

As you can see, there is a placeholder for the auth token in this snippet (`auth-token="your-auth-token"`).

You can also personalize the chat experience with attributes such as:

* `welcome-message`: the first message displayed to users when the chat opens.
* `prompt-placeholder`: the placeholder text shown in the input field before the user starts typing.
* `data-theme`: optional setting to switch between `light` and `dark`.

Below is an example of what an embedded chat looks like when displayed with its associated dashboard.

<figure><img src="/files/kSS0Cv9DUWVXBitfrrFj" alt=""><figcaption><p>AI chat + dashboard embed (dashboard hidden)<br>Click the button at the top of the chat to show the dashboard.</p></figcaption></figure>

<figure><img src="/files/Wtdj4DSG26Mqc8xSw2eX" alt=""><figcaption><p>AI chat + dashboard embed (dashboard visible)</p></figcaption></figure>

{% hint style="info" %}
The *AI chat + dashboard* option is available on the Grow pricing plan.
{% endhint %}

#### 7: Get an auth token

{% hint style="info" %}
You can customize the way the AI assistant will behave thanks to "AI context clues" within the token, where you can define the tone of voice, company context, etc.
{% endhint %}

For testing and configuration, you can generate a temporary token directly from the Toucan AI interface.

* Navigate to **Settings > Embed & access**.
* Scroll down to the **Token Generation Sandbox** section.
* Paste your **API Key**.
* Under **User Attributes**, configure the values for any custom attributes as well as the `aiContextClues` for this token.
* Click **Generate Token** and copy the resulting string.

<figure><img src="/files/BYOnZf5WPbVMZVuzYTXY" alt="Token generation sandbox"><figcaption></figcaption></figure>

{% hint style="info" %}
**Production Note**: For a live application, your backend server would generate these tokens dynamically via the API to securely authenticate your users and apply the correct security filters.
{% endhint %}

#### 8: Configure CORS and embed the chat

Before your embed can render, you must authorize the domain where it will be hosted.

* In the **Embed & access** settings, locate the **Authorized Origins** section.
* Add the URL of your application or development environment (e.g., `https://codepen.io`) and click Save.
* Go to your application's code and paste the snippet you retrieved in Step 6.
* Replace `your-auth-token` with the token you generated in the previous step.

Example result in codepen:

<figure><img src="/files/Ty7PrYs63dY8N4qacWtS" alt="Codepen embedded chat"><figcaption></figcaption></figure>

***

### Conclusion

You have successfully configured and embedded a self-service chat. Your users can now ask questions and receive data-driven answers secured by your RLS and CLS policies.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.toucanai.cloud/getting-started/quick-start/embed-a-chat.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.