Chat widget

Embed Chanl agents on your site with a script tag, React hooks, or a custom UI — text chat and voice

Put a Chanl agent on any website or app so visitors can chat (or call) without leaving your product. The widget talks to the same agents you configure in the dashboard — tools, knowledge, memory, and prompts included.

Choose an integration path

Path	Package	Best for
Embed script	Hosted `v1.js` at `chat.channel.tel`	Marketing sites, docs, no build step
React hooks	`@chanl/widget-sdk/react`	Next.js, Vite, custom in-app chat UI
Headless client	`@chanl/widget-sdk`	Non-React apps, full UI control
Voice	`@chanl/widget-sdk/voice` or `useVoice`	Browser voice calls with your agent

The widget SDK (@chanl/widget-sdk) ships from the chanl-sdk monorepo alongside @chanl/sdk and @chanl/cli. Use public keys (pub_xxx) in browser code — never ship server API keys.

Quick start: embed script

Enable Public embed on the agent's chat-widget settings in the dashboard, then add:

<script src="https://chat.channel.tel/widget/v1.js"></script>
<script>
  ChanlChat.init({
    agentId: 'ag_xxx',
    apiKey:  'pub_xxx',
    theme:   'dark',
    position: 'bottom-right',
  });
</script>

The script injects a launcher button and loads the chat UI in an iframe. Visitors never see your API key or backend URL.

Open from your own button

<button id="help">Get help</button>
<script>
  document.getElementById('help').addEventListener('click', () => {
    ChanlChat.open();
  });
</script>

Identified users (logged-in visitors)

For Intercom-style identity, compute an HMAC on your server and pass user + userHash into React hooks or ChanlChat.setUser():

// Server Component (Next.js) — see @chanl/widget-sdk/next
import { computeUserHash } from '@chanl/widget-sdk/next';

const userHash = computeUserHash(user.id, process.env.CHANL_IDENTITY_SECRET!);

Chanl verifies the hash, upserts a customer record, and injects attributes into prompt variables ({{customer:email}}, etc.).

Surface	Who uses it	What it does
Widget	Your website visitors	Live chat/voice with one agent
MCP	Claude Desktop, Cursor, your dev tools	Tools, resources, and prompts for builders

The widget is for end-customer conversations. MCP is for equipping agents during development. Both hit the same Chanl backend.

Security checklist

Use pub_xxx keys in the browser — add your site origins to the key allowlist in the dashboard.
Keep CHANL_IDENTITY_SECRET server-only when using userHash.
Turn on Public embed only for agents you intend to expose on the public web.

Widget SDK reference — hooks, headless client, voice, Next.js helpers
MCP — tools, resources, and prompts for MCP clients
Agents & tools — configure the agent the widget connects to