Allowed domains
Add the hostnames where the widget runs on the agent’s Channels > Widget > Embed on Web tab, under Your Domains. Then use the agent ID alone:- The dashboard stores hostnames only, such as
www.example.com. A full URL you paste is reduced to its hostname. - Matching is exact.
example.comdoes not coverwww.example.comorapp.example.com; add each one. - Wildcards (
*.example.com) are rejected. - Because ports are dropped, a page on
http://localhost:3000does not matchlocalhost. Use a token for local development. - An empty list blocks every domain-based call with
No allowed origins configured. Add allowed domains or use token-based auth.
Server-generated tokens
A token is a short string your server signs with a secret. The browser only ever sees the token, never the secret.Which secret to use
Either secret works:- The agent’s web call secret, shown on the Channels > Widget > Custom tab under Authenticate. It is created when you turn on the widget.
- Any of your organization’s API keys.
Token format
The SDK reads the agent ID from the first part of the token, so you don’t need to pass
campaignId separately.
Generate a token
Express
Use the token
Token lifetime
You choose the lifetime when you setexpiry; the SDK helper uses one hour. The token is checked when the call starts and on later requests during the call: typed messages, form answers, page summaries and the transcript stream. So:
- Make the token live at least as long as your agent’s maximum call duration, plus the time a visitor may leave the page open before calling. One hour suits most sites.
- Mint a fresh token on each page load instead of caching one.
- An expired or wrongly signed token fails with
Invalid web call token(HTTP 401).
The SDK sends the token as a
token query parameter on the transcript stream, because browsers can’t add headers to EventSource requests. Keep lifetimes short for this reason.The secret and apiKey options
WebCall also accepts secret or apiKey and signs tokens in the browser. Use these only in local test pages (the playground does this). Never ship them in production code.
Related
Bot protection
Add a Turnstile check on top of either method.
Troubleshooting
Fix origin and token errors.