Voice

Voice lets an agent handle live spoken conversations while keeping the rest of the Kravos.ai workflow intact.

The important idea is that a voice session is not separate from conversations. A session creates or attaches to a normal conversation, then stores provider-specific voice metadata beside it. That makes transcripts, tool calls, usage, and review workflows show up in the same places as text conversations.

How Voice Fits Together

Session Lifecycle

1. A voice client or Voice Lab calls the voice start endpoint.
2. Kravos.ai checks voice entitlement and voice configuration.
3. If needed, Kravos.ai creates a WEB_VOICE conversation with source VOICE.
4. Kravos.ai creates or updates a voice session for that conversation.
5. Kravos.ai asks ElevenLabs for a signed conversation URL.
6. The browser connects to ElevenLabs using that signed URL.
7. When the session ends, Kravos.ai marks the conversation closed and the voice session ENDED.
8. Webhooks or fallback jobs persist the transcript and call metadata.

If a request supplies an existing conversation ID, that conversation must already belong to the same agent and must use the WEB_VOICE channel.

Tools Available During Voice Calls

Voice sync wires ElevenLabs tools back to Kravos.ai:

• search_knowledge_base calls retrieval before answering factual questions.
• share_media searches media records when the voice agent needs to send or reference media.
• fetch_skill is added only when active skills exist for the agent.

These tools use a managed retrieve API key. User-created dashboard API keys do not need to be shared with ElevenLabs for normal voice sync.

Transcripts And Audio

Transcripts can arrive through ElevenLabs webhooks or be fetched later by a fallback job. Transcript events are mapped into conversation messages with these sender types:

• user speech becomes END_USER
• agent speech becomes AI
• unknown speakers become SYSTEM

Voice session records also keep the raw redacted transcript payload for debugging. Audio is fetched server-side from ElevenLabs only when the stored transcript says audio is available. The browser never receives the ElevenLabs API key.

What To Use Where

• Use Agent Settings to enable voice and save defaults.
• Use Voice Lab to test microphones, speakers, transcripts, tool calls, and sync state.
• Use Conversations to review the final transcript and follow-up work.
• Use ElevenLabs Voice Setup when the provider-side agent is missing or out of sync.

Troubleshooting

Voice will not start

• confirm voice is enabled for the agent
• confirm the plan allows voice minutes
• confirm the ElevenLabs agent is configured or can be synced
• confirm ELEVENLABS_API_KEY is set on the server

Session starts but no transcript appears

• confirm ELEVENLABS_WEBHOOK_SECRET is configured
• confirm the worker is running so webhook and fallback jobs can process
• end the session cleanly so the fallback job can fetch post-call data

Audio playback is unavailable

• confirm the session has a provider session ID
• confirm the transcript payload reports audio availability
• confirm ELEVENLABS_API_KEY is still valid

Related Docs

ElevenLabs Voice Setup

Set up, import, sync, and troubleshoot the ElevenLabs voice agent.

Voice Lab

Test voice sessions, debug tool calls, and manage ElevenLabs sync.

Conversations

Review chats, voice transcripts, and human takeover activity.