Configure

Use the Configure message to change settings on an open /v1/listen WebSocket stream. The stream keeps running whether the update succeeds or fails, so you don’t drop audio or rebuild state to change what Deepgram listens for.

Purpose

What a voice application needs from speech recognition changes during a call. A caller confirms their name, then reads out an order number, then asks about a specific product. With Configure, you can:

• Load the vocabulary for the current step. Add the caller’s name to keyterms right before you ask for it, or swap in product names when the conversation moves to a product inquiry. You don’t have to load every term you might need at the start of the call.
• Switch formatting per step. Turn on Numerals before you ask for a PIN or phone number, then turn it off for free-form speech.

Configurable Fields

Both fields are optional, and you can send them in the same message. A field you omit keeps its current value.

Example Payloads

{
  "type": "Configure",
  "keyterms": ["Deepgram", "Nova-3", "customer service"]
}

Behavior

Each Keyterms Array Replaces the List

Each keyterms array replaces the whole list, including any keyterms you set with the keyterm query parameter when you opened the stream. To add a term, send the existing terms plus the new one.

Timing

Deepgram processes Configure in order with your audio. The new settings apply to audio it hasn’t transcribed yet when it processes the message. That can include audio you sent shortly before the message, but transcripts it has already returned aren’t revised. Updates stay in effect until the stream ends or you send another Configure.

Same Behavior as Connection-Time Keyterms

Keyterms set with Configure behave exactly like keyterms set with the keyterm query parameter when you open the stream. This holds on every Nova-3 streaming model, monolingual or multilingual. How much keyterms improve recognition depends on the language and the terms, and that’s the same whichever way you set them.

Keyterm Syntax and Limits

Each array entry is a plain term or phrase. Pass a multi-word phrase as a single entry, for example ["customer service"]. Like the keyterm query parameter, entries don’t support the weight syntax from the legacy Keywords feature, so don’t append a weight such as "term:0.15".

The 500-token keyterm limit that applies to the keyterm query parameter also applies to each Configure message. Keep each list to the terms that matter for the current step of the conversation instead of sending everything you might need. An over-limit update returns a ConfigureFailure with code CONFIGURE_KEYTERM_LIMIT_EXCEEDED.

Responses

Deepgram answers every Configure with exactly one ConfigureSuccess or ConfigureFailure message. Both include the stream’s request_id.

ConfigureSuccess

ConfigureSuccess confirms that the update took effect. When the message replaced the keyterms, keyterms lists the keyterms now in effect. Fields the message didn’t change are omitted.

{
  "type": "ConfigureSuccess",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "keyterms": ["Deepgram", "Nova-3", "customer service"]
}

ConfigureFailure

ConfigureFailure means Deepgram rejected the whole message and applied none of it, including any features sent alongside keyterms. The stream stays open with its previous settings.

{
  "type": "ConfigureFailure",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "CONFIGURE_KEYTERMS_NOT_SUPPORTED",
  "description": "`keyterms` are not supported by this model."
}

One Update at a Time

Deepgram processes one Configure at a time. Wait for ConfigureSuccess or ConfigureFailure before sending the next one; a Configure sent while another is pending returns CONFIGURE_ALREADY_PENDING.

/v1/listen responses carry no sequence_id, unlike Flux STT responses.

Errors

Sending a field the message doesn’t support, for example keyterm instead of keyterms, returns an Error message. The stream stays open with its previous settings.

{
  "type": "Error",
  "variant": "SchemaError",
  "description": "Could not deserialize last text message: unknown field `keyterm`, expected one of `features`, `keyterms`",
  "message": "{\"type\": \"Configure\", \"keyterm\": [\"Deepgram\"]}"
}

Language-Specific Implementations

These examples open a Nova-3 stream, update its keyterms partway through, and handle the response.

import asyncio
import json
import os
import websockets
# Configure keyterms work on Nova-3 models only.
URL = "wss://api.deepgram.com/v1/listen?model=nova-3&encoding=linear16&sample_rate=16000"
HEADERS = {"Authorization": f"Token {os.environ['DEEPGRAM_API_KEY']}"}
async def receive(ws):
    # ConfigureSuccess and ConfigureFailure arrive interleaved with Results.
    async for raw in ws:
        message = json.loads(raw)
        # ConfigureSuccess echoes keyterms only when the Configure replaced them.
        if message["type"] == "ConfigureSuccess":
            print("Keyterms now in effect:", message.get("keyterms"))
        # ConfigureFailure applied nothing; the stream keeps its previous settings.
        elif message["type"] == "ConfigureFailure":
            print("Configure rejected:", message["code"], message["description"])
        elif message["type"] == "Results":
            print(message["channel"]["alternatives"][0]["transcript"])
async def main():
    async with websockets.connect(URL, additional_headers=HEADERS) as ws:
        # Read server messages on a background task so sending audio isn't blocked.
        receiver = asyncio.create_task(receive(ws))
        # Stream audio with ws.send(audio_bytes) ...
        # The caller is about to give their account manager's name.
        # Wait for this Configure's response before sending another, or
        # Deepgram returns CONFIGURE_ALREADY_PENDING.
        await ws.send(json.dumps({
            "type": "Configure",
            "keyterms": ["Zyphorra Quillbeck", "Xylofex Dynamics"],
        }))
        # Keep streaming; later transcripts use the new keyterms.
        await receiver
asyncio.run(main())

Related Resources

• Keyterm Prompting: choosing keyterms and setting them when you open a stream
• Numerals: converting spoken numbers to digits
• Flux STT Configure: the equivalent message for Flux STT (/v2/listen)
• Finalize and Close Stream: other streaming control messages