> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget channel

> Embed a chat widget on your website so visitors can talk to your conversation flow.

The **Widget** is the simplest channel to set up. No integrations to connect, no credentials to manage — just paste a snippet of code on your site and your flow has a fully working chat surface.

## When to use it

* Visitors should be able to chat without logging in.
* You want a branded chat bubble on your marketing site or in-app.
* You want voice support (optional) alongside text.

## 1. Add the Widget channel

Open the flow, click **Flow settings** in the bottom toolbar, then the **Channels** tab. Click **Add Channel** and pick **Widget**.

<Frame caption="Flow settings → Channels. The Sales Triage flow has one widget channel configured.">
  <img src="https://mintcdn.com/glorium/UHxshDRLTTq8MRPz/images/widget/widget-channels-list.png?fit=max&auto=format&n=UHxshDRLTTq8MRPz&q=85&s=dcfc5332746d1107a570c42184888ea8" alt="Widget in the Channels list" width="1440" height="1200" data-path="images/widget/widget-channels-list.png" />
</Frame>

Click the channel row to open its configuration drawer.

<Frame caption="Widget channel settings — name, TTS model, voice, Magic Window, and the two customization entry points.">
  <img src="https://mintcdn.com/glorium/UHxshDRLTTq8MRPz/images/widget/widget-channel-config.png?fit=max&auto=format&n=UHxshDRLTTq8MRPz&q=85&s=c5a01b7ca58e75f3fac942c71b2f8dc1" alt="Widget channel configuration drawer" width="1440" height="1200" data-path="images/widget/widget-channel-config.png" />
</Frame>

| Setting                 | What it controls                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| **Channel Name**        | Internal label (e.g. "Acme website widget"). Visitors never see it.                             |
| **TTS Model**           | The text-to-speech model used for voice replies. *Mini* is \~120ms; *Max* is highest quality.   |
| **Voice**               | Which voice the widget uses when speaking. Click to preview.                                    |
| **Enable Magic Window** | When on, the widget shows visual content (cards, images, structured panels) alongside the chat. |

Click **Save** to persist these. The two buttons below — **Customize Widget** and **Install Widget** — are covered next.

## 2. Customize the widget

Click **Customize Widget** to open the appearance dialog.

<Frame caption="Customize Widget — the text visitors see before they type, the suggestion chips, and the brand colors.">
  <img src="https://mintcdn.com/glorium/UHxshDRLTTq8MRPz/images/widget/widget-customize-dialog.png?fit=max&auto=format&n=UHxshDRLTTq8MRPz&q=85&s=b11fb71e7775d2fb7af14a13678d342d" alt="Customize Widget dialog" width="1440" height="1200" data-path="images/widget/widget-customize-dialog.png" />
</Frame>

| Field                 | What it does                                                                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| **Greeting headline** | The first thing a visitor sees when the widget opens. Short (max 80 chars).                               |
| **Main question**     | The big prompt under the greeting, e.g. *"How can I help you today?"* (max 120).                          |
| **Subtext**           | One line of supporting copy under the main question (max 300).                                            |
| **Inspirations**      | Up to **6** suggestion chips that pre-fill common prompts. Lowers the bar for visitors to start chatting. |
| **Primary color**     | Your brand color — used on the launcher button, send button, and accents.                                 |
| **Secondary color**   | Used for hover states, chip borders, and secondary UI.                                                    |

<Tip>
  Good inspiration chips read like real questions, not topics. *"How much does Acme Pro cost?"* converts better than *"Pricing"*.
</Tip>

Click **Save** when you're done.

## 3. Install on your site

Click **Install Widget** to get the embed snippet for your website.

<Frame caption="Install Widget — the snippet to paste before the closing </body> tag, plus a hosted test URL.">
  <img src="https://mintcdn.com/glorium/UHxshDRLTTq8MRPz/images/widget/widget-install-dialog.png?fit=max&auto=format&n=UHxshDRLTTq8MRPz&q=85&s=b835f409aa408cd2e1a60aace7d3987a" alt="Install Widget dialog with the embed script and the test link" width="1440" height="1200" data-path="images/widget/widget-install-dialog.png" />
</Frame>

Copy the snippet and paste it into your site's HTML, right before the closing `</body>` tag. It looks like this (the `data-flow-id` and `data-channel-id` are pre-filled for your flow):

```html theme={null}
<script type="text/javascript">
(function() {
  try {
    const chatDiv = document.createElement('div');
    chatDiv.id = 'glorium-chat';
    chatDiv.setAttribute('data-flow-id', 'YOUR_FLOW_ID');
    chatDiv.setAttribute('data-channel-id', 'YOUR_CHANNEL_ID');
    document.body.appendChild(chatDiv);

    const script = document.createElement('script');
    script.src = 'https://embed.cogniagent.ai/embed.js';
    script.type = 'text/javascript';
    script.onload = () => console.log('CogniAgent loaded successfully');
    script.onerror = (err) => console.error('Failed to load CogniAgent:', err);
    document.body.appendChild(script);
  } catch (err) {
    console.error('Error initializing CogniAgent:', err);
  }
})();
</script>
```

### Hide under a query parameter

The **Hide widget under query parameter** checkbox restricts the widget to URLs containing `?chatbot=1`. Useful while you're previewing the widget on a live site without exposing it to everyone yet.

### Test before installing

The Install dialog also shows a **hosted test URL** — `https://embed.cogniagent.ai/?flow_id=…&channel_id=…`. Click the link to open the widget standalone, exactly as your visitors would see it once embedded.

<Frame caption="The hosted test page — the widget opens full-bleed so you can verify branding and conversation flow before going live.">
  <img src="https://mintcdn.com/glorium/UHxshDRLTTq8MRPz/images/widget/widget-live-open.png?fit=max&auto=format&n=UHxshDRLTTq8MRPz&q=85&s=28d5ff4bdc9f3f3469c92db13b3324ca" alt="Live widget on the test page" width="1471" height="1277" data-path="images/widget/widget-live-open.png" />
</Frame>

Send a message and watch the routing in real time:

<Frame caption="A live conversation in the widget — the Triage actor handed off to the Pricing Specialist.">
  <img src="https://mintcdn.com/glorium/UHxshDRLTTq8MRPz/images/widget/widget-live-conversation.png?fit=max&auto=format&n=UHxshDRLTTq8MRPz&q=85&s=fe0a0c1ba376d61907ec41b8b249cd28" alt="Widget conversation showing routing to the Pricing Specialist" width="1471" height="1277" data-path="images/widget/widget-live-conversation.png" />
</Frame>

## 4. Deploy

The widget only accepts traffic when the flow is **deployed**. Click **Deploy** in the bottom toolbar after the channel is configured. The flow card flips from `draft` to `deployed`, and the embed script starts working on every page where it loads.

## What visitors see

1. A circular **launcher button** appears in the corner of every page where the script is loaded.
2. Clicking it opens a panel showing the **greeting**, **main question**, **subtext**, and **inspiration chips** you authored.
3. The visitor types — or taps a chip — and the conversation runs. Routing picks the right actor, replies come back in the same panel.
4. Closing and reopening the widget within the same session preserves history. After session expiry (a few hours of inactivity) the visitor starts fresh.

## Inbound only

The Widget is **inbound-only**. You can't proactively start a conversation with an anonymous web visitor — they have to open the widget first. For outbound proactive messages, use the [Email](/conversation-flows/channels/email) or [Messaging](/conversation-flows/channels/messaging) channels instead.

## Hand-off to a human

For escalation, the typical pattern:

1. Add a "Human Escalation" actor to the flow.
2. Give it a [capability](/conversation-flows/build/capabilities) that posts to Slack or Teams (e.g. Slack `send-message`).
3. When routing picks it, the actor posts the transcript and a link to the live session to your support channel.
4. Your team picks up the conversation from the [Conversations history](/conversation-flows/operate/conversations-history) view.

## Next

<CardGroup cols={2}>
  <Card title="Deploy a flow" icon="rocket" href="/conversation-flows/operate/deploy">
    Take the widget live so real visitors can chat with it.
  </Card>

  <Card title="Email" icon="envelope" href="/conversation-flows/channels/email">
    Add Gmail or Outlook alongside the widget for follow-ups.
  </Card>

  <Card title="Capabilities" icon="puzzle-piece" href="/conversation-flows/build/capabilities">
    Give actors tools so the widget can actually do things — book meetings, look up orders, post to Slack.
  </Card>

  <Card title="Conversations history" icon="comments" href="/conversation-flows/operate/conversations-history">
    Review every widget conversation, routing decisions, and tool calls after the fact.
  </Card>
</CardGroup>