Skip to main content
The MKA1 API provides a real-time voice interface through LiveKit. This guide covers how to obtain a room token, connect to a voice session, send audio and text input, and capture the agent’s responses.

Overview

The voice integration consists of three main components:
  1. Room Token: A JWT that grants access to a LiveKit room
  2. LiveKit Connection: WebRTC-based real-time communication
  3. Voice Agent: Processes audio/text input and generates spoken responses
The agent pipeline works as follows:
  • 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
Every request the voice agent sends to the Responses API automatically includes "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 accepts X-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.
For voice sessions, disable reasoning by setting "reasoning": { "effort": "none" }. Reasoning adds thinking time before the model responds, which increases latency and creates noticeable pauses in conversation. Disabling it keeps responses fast and natural.

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:
To continue an existing conversation:
When continuing a session, the API key and X-On-Behalf-Of header (if used) must match the original session. The voice agent encrypts both into the room token and passes them to all downstream MKA1 services. If they don’t match, the agent will not have access to the previous context.

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:
  1. Audio output: Synthesized speech via an audio track
  2. Transcription: Text of what the agent is saying (for captions)
  3. 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 the response_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 a response_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

Use previous_response_id to chain a new session to the last response, preserving conversation context:

Continuing from a conversation

Use conversation_id to continue an existing conversation created via the Conversations API:
When continuing a conversation, the API key and X-On-Behalf-Of header (if used) must match the original session. The context is scoped to the authenticated identity.

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:
The error payload structure:
Error codes:

Connection errors

Next steps