Skip to main content
Every web call must prove it is allowed to reach your agent. The SDK supports two methods: an allowed-domain list for public sites, and server-generated tokens for apps where you control who can start a call. Bot protection, if you turn it on, applies on top of either method.

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:
Matching rules (verified against the API):
  • The dashboard stores hostnames only, such as www.example.com. A full URL you paste is reduced to its hostname.
  • Matching is exact. example.com does not cover www.example.com or app.example.com; add each one.
  • Wildcards (*.example.com) are rejected.
  • Because ports are dropped, a page on http://localhost:3000 does not match localhost. 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.
Never put the web call secret or an API key in browser code, in a script tag, or in a mobile app bundle. Anyone who reads it can start calls on your account. Only your server should sign tokens.

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

Expose it from an endpoint your frontend can call, ideally one that requires the visitor to be signed in:
Express

Use the token

Token lifetime

You choose the lifetime when you set expiry; 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.

Bot protection

Add a Turnstile check on top of either method.

Troubleshooting

Fix origin and token errors.