Once the live chat code is on your site, your page can talk to it: open and close it, tell your team who the visitor is and where they are, listen to what happens, and let agents act on the page. Developers who want their own design can skip the widget and use the headless SDK or the React hooks. This page is the map; the panel shows ready-to-copy code with your real keys.
Where to find it
Meta → Channel, open your live chat, card Add chat to your site: tabs Website (the script) and Build your own (the SDK).
Try it on a test page opens a test console. Its Install tab has every snippet below, filled in with your site key.
You need the Manage Channels permission to open the channel.
Lets an agent, bot or AI agent ask your page to do something. Validate every detail: they come from a bot or a model
registerActions(list)
Declares what your page can do, so agents pick from a list
send(body) / sendAttachment(file)
Sends a message as the visitor
destroy()
Removes the chat from the page
The widget collects page, device, language, campaign (UTM), the last ten pages and visit count by itself. It does not collect the IP address, precise location, form contents or anything else on your page. Turn blocks off with collectContext.
Logged-in visitors
When a visitor is signed in to your site, your server opens the chat session and vouches for who they are, so your team sees the same customer every time.
Your server calls the gateway's /v1/visitor/session with your connect token and the X-Channel-Id of the chat, sending external_user_id and an optional profile.
It passes the answer (access_token, refresh_token, expires_in, conversation_id, visitor_id) back to your page.
On the page, use sessionEndpoint: '/api/chat-session' and configSiteKey instead of siteKey.
The connect token must never reach a browser. A first-time visitor has conversation_id 0; that is normal. The contact is created on the visitor's first real message, not on a page view.
Session links: your server can also ask /v1/visitor/session/link for a short-lived link (default 24 hours, 60 seconds to 7 days) that opens a web chat as a customer you already know, for example from a WhatsApp button.
The connect token is an API token: create one in Settings → Integration → API Tokens (see API tokens and developer keys) and keep it on your server. It acts with the full access of the staff member who made it, so if it leaks, revoke it there and make a new one.
Build your own chat screen
Headless SDK (@connect/chat-core): no UI. It handles the connection, reconnects with backoff, an offline queue, message history, uploads and read state. You draw the messages. Create a ChatClient with anonymousSession (site key) or handoffSession (your server's session endpoint).
React (@connect/chat-react): a ChatProvider plus hooks such as useMessages, useConnection, useChat, useOnAction, useClientContext, useTrack and useRegisterActions.
Limits and plans
Live chat needs a plan with room for it (channels.web).
Registered actions: the panel shows the limits (number of actions, total size, description length, details per action) on the Install tab. A list over any limit is refused whole.
Context frames are capped at 4 KB and sent at most every 2 seconds.
Good to know
An action only runs if your page registered a handler for it, and its category (navigation, ui, data, commerce) is switched on under the chat's Features.
The built-in point action needs no handler: it draws a ring over part of the page for about four seconds.
Errors are emitted on error, never thrown.
Troubleshooting
What you see
Why
What to do
"Live chat is not switched on for this workspace yet…"