This page walks through enabling the voice agent for a specific web-widget inbox, filling in the required ElevenLabs credentials, and verifying that the agent itself is configured correctly in ElevenLabs. Complete all steps before testing the button in the widget.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.
Configure in the Chatwoot dashboard
Log in to the Chatwoot dashboard
Open your Chatwoot instance in a browser (for example
http://localhost:3000) and sign in with an admin account.Open the inbox Configuration tab
Go to Settings → Inboxes, find the web-widget inbox you want to enable voice for, and click Settings. Select the Configuration tab.
The Voice Agent section only appears for Web Widget inboxes. It is not shown for email, WhatsApp, or API inboxes.
Scroll to the Voice Agent section
Scroll past the Messenger Script and Allowed Domains sections until you reach the Voice Agent heading.
Toggle Enable Voice Agent ON
Click the toggle next to Enable Voice Agent. The section expands to show the provider, API key, and agent ID fields. A green Active badge appears to confirm the toggle state.
Set the Provider
The Provider field defaults to
elevenlabs. Leave it as-is unless you have a custom integration — ElevenLabs is the only provider wired up in the widget at this time.Paste the Agent ID
In the Agent ID field, paste your ElevenLabs agent ID. You can copy it directly from the ElevenLabs dashboard URL:Paste the full
agent_XXXXXXX string. This value is stored in both the elevenlabs_agent_id column and inside voice_agent_config_data.agent_id so both widget read paths resolve it correctly.Enter the API Key (public agents: leave blank)
For public agents (the recommended path), leave the API Key field empty.If your agent is set to private in ElevenLabs, paste an API key that has ElevenAgents → Write (
convai_write) permission. Without the correct permission, Rails will log missing_permissions: convai_write and calls will not connect.Click "Save Voice Agent Settings"
Click the Save Voice Agent Settings button at the bottom of the section. A success alert confirms the settings were persisted.The widget re-fetches the configuration on every bubble open — no page reload on the visitor’s side is required. The next time someone clicks the chat bubble the updated settings are used.
ElevenLabs agent requirements
Before the voice button can work, the ElevenLabs agent itself must be fully configured. Open elevenlabs.io/app/conversational-ai/agents, select your agent, and confirm:| Setting | Required value |
|---|---|
| Voice | Any voice assigned — the agent will be silent without one |
| First Message | A non-empty greeting, e.g. "Hi, how can I help?" |
| System Prompt | A non-empty system prompt |
| Public access | Security tab → Allow public access must be ON |
Public access is required because the
<elevenlabs-convai> web component connects using only the agent ID. There is no server-side signed-URL exchange in the current widget implementation.How the feature flag is stored
The enable/disable toggle maps to bit 5 (elevenlabs_voice) in the feature_flags integer column on channel_web_widgets. When you save the dashboard form, the Vue component adds or removes elevenlabs_voice from selected_feature_flags. The widget checks flags.includes('elevenlabs_voice') (and also accepts the legacy value voice_agent for backwards compatibility).
Config re-fetch behaviour
App.vue in the widget listens for the toggle-open postMessage that fires each time the visitor opens the chat panel. On every open it dispatches voiceAgentConfig/fetchVoiceAgentConfig, which hits GET /api/v1/widget/conversations/inbox_config. This means dashboard changes take effect on the very next bubble click — no full page reload, no cache to clear.