Troubleshooting

Most problems show up in two places: the browser console, and the error passed to your onError callback. The call window itself shows a generic message, such as Unable to start the call. Please try again., so always check the console or onError for the real cause. A refused call start looks like this:

Failed to get call credentials (401): {"message":"Origin 'https://shop.example.com' is not allowed for this campaign", ...}

The number in parentheses is the HTTP status; the text after it is the API’s message. Messages say “campaign” because agents used to be called campaigns.

Error messages

Message	Cause	Fix
`No allowed origins configured. Add allowed domains or use token-based auth.`	The agent’s domain list is empty and no token was sent	Add your hostnames under Your Domains, or use a token
`Origin '…' is not allowed for this campaign`	The page’s hostname isn’t on the list	Add that exact hostname, including `www.` or other subdomains
`Origin header is required`	The page was opened from a `file://` path	Serve the page over `http://localhost` or `https://`
`Invalid web call token`	The token is expired, malformed, for another agent, or signed with the wrong secret	Mint a fresh token on your server with the agent’s web call secret or an API key; check the expiry is in seconds
`Web call secret not configured for campaign: …`	Token auth was used but the agent has no secret and your organization has no API keys	Turn on the widget for the agent (this creates the secret) or create an API key
`Web calls not enabled for campaign: …`	The widget is off for this agent	Switch on Enable widget in Channels > Widget
`Campaign not found: …`	Wrong agent ID, or the wrong API endpoint	Check the ID; leave `apiEndpoint` / `data-api` unset
`Web calls are only available during working hours`	The agent only accepts web calls inside its availability schedule	Try during the schedule, or ask support to change the setting
`Bot verification is required`	Bot protection is on and no Turnstile token was sent	Let the built-in widget handle it, or pass a token to `call()`
`Bot verification failed`	The Turnstile token was invalid, reused, expired, created for another action, or the secret key is wrong	Check both keys; mint a fresh token with action `web-call-start` for each call
`WebCall: unable to resolve campaign ID. Provide campaignId or a valid token (campaignId.expiry.signature).`	`new WebCall()` got neither `campaignId` nor a token	Pass one of them
`sendInput requires an active call`	`sendInput()` was called before the call connected or after it ended	Wait for `onCallStarted`
`Failed to send input: …`	The API refused a typed message, for example over 2,000 characters	Shorten the message; check the token is still valid
`Page context is too large: at most 16000 characters`	A Page Guide summary was too large	Lower `pageGuide.maxElements`; the SDK normally keeps summaries under 8,000 characters

Nothing renders and the console is silent

The script tag needs data-agent (or the legacy data-campaign) or data-token. Without one, it doesn’t create a widget and logs nothing. Check the attribute name and that the value isn’t empty.

The console shows an Invalid JSON error

[CallerWebSDK] Invalid JSON in data-vars attribute. or ... data-theme attribute. means the attribute isn’t valid JSON. Wrap the attribute in single quotes and use double quotes inside: data-vars='{"name":"Jane"}'.

The script is blocked

Check the Network tab. Ad blockers or a Content Security Policy can block https://cdn.callers.ai. See the CSP list in the overview.

I set showFab: false and see nothing

That’s expected: the launcher is hidden until you call call(). With hidden: true, nothing is shown at all until you call show().

The call doesn’t connect or has no audio

Microphone access was denied

If the visitor blocks the microphone, the call can’t connect and ends immediately (onCallEnded fires). Ask them to allow the microphone from the site settings icon in the address bar and try again. Make sure the page is served over HTTPS, and inside an <iframe> add allow="microphone".

Connected, but the visitor hears nothing

Browsers block audio that doesn’t start from a user action. Call call() from a click or tap handler, not on page load or after an await that runs long after the click. Also check the visitor hasn’t turned off the speaker (isDeafened()).

The agent can't hear the visitor

Check isMuted(). Text conversations start with the microphone muted; turning it on switches to voice. Some corporate networks block WebRTC traffic; try another network to confirm.

The call ends after about 30 seconds without connecting

The SDK hangs up if the call isn’t answered within 30 seconds. Check that the agent answers a test call from the dashboard.

Echo or background noise

AI noise suppression is on by default. If you pass your own noiseSuppression object, leave browserEchoCancellation on. Headphones help on laptops.

Local development

It works in production but not on localhost

Allowed domains are stored without ports, so http://localhost:3000 never matches. Use token authentication locally, or test in the playground.

The agent greets visitors with {{ name }}

The data-vars snippet from the dashboard contains placeholders. Replace them with real values from your page or template before the HTML reaches the browser.

Bot protection

The challenge never finishes

Make sure your page’s hostname is listed on the Turnstile widget in Cloudflare, and that https://challenges.cloudflare.com isn’t blocked. Errors from the in-browser check are Captcha verification failed, Captcha verification expired or Captcha verification timed out.

Visitors can't start a second call from the review screen

Intended: with bot protection on, visitors close and reopen the widget so each conversation gets a fresh check.

Avatars

The avatar doesn't show

Avatars only appear on voice calls. Look for console warnings starting with Avatar or WebCall: invalid avatar name. If the model can’t load (blocked by CSP or a content blocker), the call continues without the avatar.

WebGPU isn't available

The avatar falls back to the CPU automatically. It still works, but may be less smooth on older devices. webCall.avatarStats.backend shows webgpu or wasm.

Still stuck?

Send support@callers.ai the agent ID, the page URL, the full onError message, and the session ID from webCall.getUsername() (read it during the call).

Playground

Reproduce the problem; the playground explains failed calls in plain language.

Authentication

Domain allowlists and token rules.

Bot protection

Turnstile setup and the web-call config endpoint.