> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common Callers Web SDK problems: domain and token errors, microphone access, bot protection, missing audio and avatars.

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](https://docs.callers.ai/sdk/authentication.md#server-generated-tokens) |
| `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 |

## The widget doesn't appear

> **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](https://docs.callers.ai/sdk/overview.md#requirements).

> **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](https://docs.callers.ai/sdk/authentication.md#server-generated-tokens) locally, or test in the [playground](https://docs.callers.ai/sdk/playground.md).

> **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](mailto: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).

## Related

> **[Playground](https://docs.callers.ai/sdk/playground.md)**
>
> Reproduce the problem; the playground explains failed calls in plain language.

> **[Authentication](https://docs.callers.ai/sdk/authentication.md)**
>
> Domain allowlists and token rules.

> **[Bot protection](https://docs.callers.ai/sdk/bot-protection.md)**
>
> Turnstile setup and the web-call config endpoint.

> **[Troubleshooting](https://docs.callers.ai/documentation/resources/troubleshooting.md)**
>
> Problems on the agent side: dialing, audio, webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.