Overview
The voice integration consists of three main components:- Room Token: A JWT that grants access to a LiveKit room
- LiveKit Connection: WebRTC-based real-time communication
- Voice Agent: Processes audio/text input and generates spoken responses
- STT (Speech-to-Text): Audio is streamed via WebSocket at 16kHz and transcribed
- LLM: Transcribed text is processed by the MKA1 Responses API
- TTS (Text-to-Speech): LLM output is synthesized to audio at 24kHz
"voice_mode": "true" in the request metadata. This lets you distinguish voice-originated responses from text-based ones when reviewing usage or response history.
Getting a room token
To start a voice session, first request a room token from the MKA1 API. The token endpoint requires an API key and optionally acceptsX-On-Behalf-Of to identify end users. See Authentication for details.
Parameters
The request body has two top-level objects:llm — LLM configuration (required)
The llm object accepts the same fields as the Responses API request body, minus fields managed by the voice agent (input, stream, store, background).
You cannot specify both
previous_response_id and conversation.
The token metadata is embedded in a JWT, which is passed as an HTTP header. Keep the total
llm payload under ~8 KB — large tools arrays may need to be trimmed.stt — Speech-to-text configuration (optional)
Controls server-side voice activity detection (VAD) and endpointing behavior.
Advanced configuration
You can pass tools, custom instructions, and STT tuning in a single token request:Response
The token includes metadata that the voice agent uses to configure the session.
Continuing a session
To continue from a previous response:Connecting to a room
Once you have a token, use the LiveKit SDK to connect to the room.Sending audio input
The agent accepts audio input via the LiveKit room’s audio track. The audio is processed at 16kHz sample rate.Audio behavior
- Voice Activity Detection (VAD): VAD is handled server-side by the MKA1 agent, not locally. The agent automatically detects when you stop speaking and begins processing.
- Sample rate: Audio is streamed at 16kHz to the STT service.
- Endpointing: The agent uses server-side endpointing to determine when speech ends. There is no local endpointing delay.
Sending text input
You can also send text messages directly to the agent without speaking.Receiving agent responses
The agent responds in three ways:- Audio output: Synthesized speech via an audio track
- Transcription: Text of what the agent is saying (for captions)
- Response metadata: Response ID and conversation ID via data channel
Subscribing to audio output
Receiving transcriptions
The agent publishes transcriptions of its speech. You can use these for captions or logging.Receiving response metadata
The agent publishes theresponse_id and conversation_id (if applicable) when it starts generating a response. Save the response_id to chain future sessions using previous_response_id.
Conversation continuity
The agent supports multi-turn conversations with persistent memory. Every response is automatically assigned aresponse_id, while conversations must be explicitly created and managed through the Conversations API.
There are two ways to continue a conversation:
llm.previous_response_id chains a new session to a specific response. The agent receives the context from that response and all prior responses in the chain. Use this when:
- You want to continue from a specific point in a conversation
- You’re building a linear conversation flow
- You want to branch from a specific response
llm.conversation references a conversation created via the Conversations API. Use this when:
- You need to manage conversation metadata (titles, tags, etc.)
- You want to list or search past conversations
- You’re building a chat interface with persistent conversation history
- Multiple clients need to access the same conversation
Starting a new session
Continuing from a previous response
Useprevious_response_id to chain a new session to the last response, preserving conversation context:
Continuing from a conversation
Useconversation_id to continue an existing conversation created via the Conversations API:
Handling disconnection
Tokens expire after 5 minutes. If you need longer sessions, implement reconnection logic:Complete example
Here’s a complete example putting it all together:Error handling
Token endpoint errors
These are returned as HTTP responses when requesting a room token:In-session errors
During an active voice session, the agent publishes errors via the LiveKit data channel. Listen for them alongside response metadata:
Error codes:
Connection errors
Next steps
- Explore the LiveKit token endpoint in the API reference
- Learn about the Responses API that powers the voice agent
- Review TTS and STT endpoints for non-realtime use cases