Troubleshooting
Audio & media
| Symptom | Check |
|---|---|
| Connected but silent | HTTPS/localhost, microphone permission, browser autoplay, and reachable STUN/TURN. Go's default is silent media. Media setup. |
no_media | TS has mediaFactory: null; it cannot answer audio. Supply media or use an external phone. Control only. |
| Microphone error | mic_not_found, mic_permission_denied, or mic_in_use identifies absent, denied, or occupied hardware. Errors. |
Calls & ringing
| Symptom | Check |
|---|---|
| No browser ringing | Register, confirm WebRTC routing and agent availability. With WebRTC off, configure an external number. Routing. |
| Callback waits for Answer | Expected: callbacks never auto-answer, even when outbound auto-answer is enabled. Call model. |
| No calls in the UI | Inspect bc.view, connection errors, registration and routing; check config.calls.enabled for visibility. A late subscriber receives cached state and does not itself lose calls. |
display_as_forbidden or no caller ID | Select an allowed availableNumbers entry. An admin may need to assign a Display-As number. External conference invites can fail the same way. Error reference. |
agent_not_available | If lineBlocked, offer Reset; otherwise choose an available presence. Banner. |
| Busy after signing back in | The prebuilt app chooses busy on sign-out; that choice persists. Select Available. A standalone SDK close() does not set presence. Reset is for involuntary blocking only. |
| A command does nothing | Handle the send result and error callback; command outcomes arrive separately in state. Errors. |
Connection & lifecycle
| Symptom | Check |
|---|---|
| Audio lost on reconnect | Close releases media; standalone SDKs don't re-answer an in-progress call. Recovery limits. |
| Connection indicator looks healthy after a drop | An immediate cache callback or successful send doesn't prove stream health. Go has no disconnect callback; TS clean stream endings are silent. Indicators. |
onGap or stale state | Get a fresh snapshot; see the TS notification sequencing caveat. |
| Reconnect rejected | The token may have expired or been revoked. Renew/login. |
Setup & integration
| Symptom | Check |
|---|---|
| CORS failure | Add the app origin to the API allowlist. Empty is permissive. TS setup. |
| Go cannot reach an HTTPS origin | Current Addr constructs plain HTTP. Go limitations. |
require() fails | Use ESM or dynamic import(). TS installation. |
| Config/options/contacts missing | Registration loads these in separate updates and may encounter partial fetch failures. Handle absent fields. |
| Control-only client receives offers | Registration requests WebRTC reachability regardless of media/capabilities. Restore external routing. |
| Contact name says "recent" | That literal denotes a recent number, not a person's name. Contacts. |
| Embed is blank or silent | Check CSP framing, embed message origins and host microphone delegation separately. Embedding. |
| Embed event missing | Wait for agent.loaded; deployed app support and CTI feature flags govern events. Events. |
| Host theme partly ignored | Read theme_rejected; accepted sibling tokens still apply. Re-send after ready when using raw messages. Theme rules. |