Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jAtInn71/chatwoot-costom/llms.txt

Use this file to discover all available pages before exploring further.

Most voice agent issues fall into one of six categories: the button not appearing in the widget, calls connecting but immediately dropping, API key permission errors, transcripts not being recorded, browser-level WebRTC errors, and HTTP-only deployments that block microphone access. Work through the accordion for whichever symptom you are seeing.
The button is gated on three conditions all being true at the same time: the elevenlabs_voice feature flag must be set, the provider must be elevenlabs, and a non-empty agent ID must be resolved. If any one is missing the button renders nothing.Steps to resolve:
  1. In the Chatwoot dashboard go to Settings → Inboxes → <your inbox> → Configuration → Voice Agent.
  2. Toggle Enable Voice Agent OFF, then click Save Voice Agent Settings.
  3. Toggle it back ON, confirm the Agent ID field is filled with your agent_XXXXXXX value, and click Save Voice Agent Settings again.
  4. Close the chat bubble completely and reopen it. The widget re-fetches the inbox config on every open — no page reload is required.
If the button still does not appear, check the browser console for [VOICE-AGENT] Error fetching config errors, which would point to a network or token issue reaching GET /api/v1/widget/conversations/inbox_config.
A call that connects and then drops within a few seconds almost always means the ElevenLabs account has exhausted its Conversational AI quota.Steps to resolve:
  1. Open elevenlabs.io/app/usage and check your Conversational AI minutes used.
  2. The free tier provides approximately 15 minutes of Conversational AI per month. Once exhausted, new calls connect briefly but the ElevenLabs server closes the session immediately.
  3. Upgrade your ElevenLabs plan or wait for the monthly quota to reset.
If quota is not the issue, check whether the ElevenLabs agent itself has a voice assigned and a non-empty first message — a misconfigured agent can also cause immediate disconnection.
This error appears when an API key is stored on the inbox but it does not have the correct ElevenLabs permission scope.Steps to resolve:
  1. In the ElevenLabs dashboard, locate the API key you pasted into Chatwoot.
  2. Edit the key and enable the ElevenAgents → Write permission (convai_write).
  3. Save the key in ElevenLabs.
  4. Re-paste the key into the Chatwoot dashboard (Settings → Inboxes → <your inbox> → Configuration → Voice Agent → API Key) and click Save Voice Agent Settings.
For public ElevenLabs agents you do not need an API key at all. Leave the API Key field blank and set the agent’s Security tab to Allow public access in ElevenLabs. The convai_write permission error only occurs when a key is present but is missing the required scope.
If a call completes but no messages appear in the Chatwoot conversation, the POST to voice_transcript may be failing silently.Steps to resolve:
  1. Tail the Rails logs while making a test call: 
    docker compose logs rails | grep voice_transcript
  2. A successful transcript POST logs nothing at info level and returns HTTP 200. If you see a [VOICE-AGENT] voice_transcript failed: line, the error message that follows it identifies the root cause (most often a database constraint or a missing contact/inbox association).
  3. Check the browser console for [VOICE-AGENT] transcript post failed: warnings from the widget side. A 401 suggests the website_token is wrong or missing; a 422 suggests the source or content field was rejected.
  4. Confirm the ElevenLabs agent is actually firing turn events. Open browser DevTools, go to the Console tab, and look for custom events from the <elevenlabs-convai> element during an active call. If no events fire, the agent may be configured to suppress transcripts or the SDK version does not emit the expected event names.
This error was caused by a LiveKit protocol mismatch between the @elevenlabs/client npm package (which negotiates protocol=17) and ElevenLabs’ production LiveKit server (which is still on protocol 16). The current implementation already avoids this by using the <elevenlabs-convai> CDN embed, which ships its own older LiveKit build that speaks protocol 16.If you see this error:
  1. It likely means the widget bundle is stale. Rebuild with: 
    ./build.sh
  2. After the build completes, restart the stack: 
    docker compose up -d
  3. Hard-refresh the page that hosts the widget (Ctrl+Shift+R / Cmd+Shift+R) to clear any cached bundle.
If the error persists after a fresh build, check whether a dependency update has changed the CDN bundle URL (https://unpkg.com/@elevenlabs/convai-widget-embed) and verify it is still reachable from the visitor’s browser.
Browsers require a secure origin (HTTPS or localhost) before granting microphone access via getUserMedia. On a plain HTTP deployment the browser will silently deny mic permission and the call will fail with a NotAllowedError.Steps to resolve:
  • For local development: http://localhost:3000 is treated as a secure origin — no change needed.
  • For staging or production: deploy behind HTTPS. The easiest path for quick testing is a tunnel such as ngrok or cloudflared: 
    ngrok http 3000
    Use the https:// URL ngrok provides as your FRONTEND_URL in .env.
  • For permanent deployments: configure SSL on your reverse proxy (nginx, Caddy, etc.) or use a managed hosting service that terminates TLS for you.

Build docs developers (and LLMs) love

Get started for freeTalk to us