Context ID

Murf’s WebSocket implementation is based on the concept of a Context ID — a unique identifier used to track a specific TTS request. Context ID ensures continuity in the conversation, especially when the input text is generated in real time (e.g., via an LLM), comes in parts, or when the interaction is interrupted. It serves as a proxy for a single turn in the interaction between a user and the agent.

Why Use a Context ID?

• Maintains Conversational Flow: Links input and output across split or partial messages.
• Handles Interruptions Gracefully: If a user interrupts the agent, the Context ID ensures that the current request can be cancelled or skipped.
• Supports Multi-Turn Interactions: Essential for structured flows like bookings, troubleshooting, or guided forms.
• Simplifies Handoff and Debugging: If support is needed, the Context ID allows you to trace exactly what happened in a specific interaction turn.

Working with Context IDs

Input Stream

• Assign a new context_id for each turn in the conversation.
• The end parameter should be set to true at the end of each turn. This clears the context and allows the next turn to start.
• Ensure input text includes proper punctuation for better prosody and consistent audio output.

Voice settings and Context IDs

A context_id does not change the values in voice_config. It scopes the configuration to one independent context:

• A voice_config with a context_id applies only to text sent with that same context_id.
• A voice_config without a context_id applies only to the default context (text that also omits context_id).
• Named contexts do not inherit the default context’s voice settings or the settings of another named context.
• Once configured, a context keeps its settings for its lifetime, even if the default context is configured differently later.

When using named contexts, initialize each one by sending voice_config and the same context_id before its first text frame. If text reaches a context without its own configuration, Murf uses the default voice and sends a NO_VOICE_CONFIG warning. A configuration without voiceId similarly falls back and sends NO_VOICE_ID. See Errors & Warnings.

Output Audio

• The response will include the same context_id, allowing you to match responses with their corresponding inputs.
• A final flag will indicate that all audio for that context has been sent.
• Output is streamed in the same order that input text was received.

Concurrency

Each simultaneously active context_id counts toward your streaming concurrency limit. Closing a turn with {"end": true} frees its slot. If you exceed the limit you receive an ACTIVE_CONTEXT_LIMIT_EXCEEDED error. See Rate Limits and Errors & Warnings.

Handling Interruptions

• If the user interrupts the agent mid-response, start a new context_id for the next turn.
• Murf’s WebSocket supports multiplexing, so multiple context_ids can run independently over the same connection.
• To cancel a pending or in-progress turn, use the clear parameter. If synthesis hasn’t started, the request is cancelled. If synthesis has started, the audio will still play to completion.

clear semantics

• {"clear": true} discards the context and any pending audio. This is what you use for barge-in.
• {"clear": false} means “do not clear” and is safely ignored, so it is fine to send a fully-populated payload with the key present.
• text sent in the same frame as clear is dropped, and you receive a TEXT_IGNORED_WITH_CLEAR warning. Send the clear and the new text as two separate frames.

Example for using Context ID in a Voice Agent

Let’s say you’re building a voice agent that helps users book flights.

{
  "voice_config": {
    "voiceId": "en-US-gordon",
    "locale": "en-US",
    "style": "Conversation"
  },
  "context_id": "turn_1"
}

{
  "context_id": "turn_1",
  "text": "Sure, when would you like to travel?",
  "end": true
}

{
  "voice_config": {
    "voiceId": "en-US-gordon",
    "locale": "en-US",
    "style": "Conversation"
  },
  "context_id": "turn_2"
}

{
  "context_id": "turn_2",
  "text": "Got it. Do you prefer morning or evening flights?",
  "end": true
}

{
  "context_id": "turn_2",
  "clear": true
}

{
  "voice_config": {
    "voiceId": "en-US-gordon",
    "locale": "en-US",
    "style": "Conversation"
  },
  "context_id": "turn_3"
}

{
  "context_id": "turn_3",
  "text": "Saturday works. Do you want to fly direct or stopover?",
  "end": true
}

Why This Matters

• Each context ID represents one agent turn in conversation.
• You maintain clean tracking of each response, even with interruptions.
• WebSocket handles all turns over a single connection, supporting real-time, fluid interaction.