Server Messages

The server replies to your Client Messages with JSON text frames interleaved with binary audio frames. This page documents every server-to-client message and the error/warning code reference.

Cadence at a glance: SpeechStarted marks the start of a turn and SpeechMetadata marks its end — every audio frame for a turn arrives between the two. Flush is your signal that all of the turn’s text has been sent; once it arrives, SpeechMetadata is our signal that all of the turn’s audio has been sent.

Connected

Sent immediately on a successful connection. Successor to v1/speak’s Metadata message.

1
{
2
  "type": "Connected",
3
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
4
  "model_name": "flux-haley-en",
5
  "model_version": "2026.06.01",
6
  "model_uuids": ["b3e47c20-9f81-4a2e-bd15-8d7c6e2a1f09"]
7
}

SpeechStarted

Emitted at the start of each new turn, before audio streaming begins. Carries the server-assigned speech_id. Fires once per turn.

1
{
2
  "type": "SpeechStarted",
3
  "speech_id": "dg_sp_a1b2c3d4e5f6"
4
}

The speech_id is a server-minted identifier of the form dg_sp_<12 hex digits>. It is informational — useful for correlating logs.

When a turn becomes active. A Speak received while idle (the first Speak, or the first after a SpeechMetadata) starts a new active turn, and we emit SpeechStarted. There is only ever one active turn: a Speak received after you’ve Flushed the active turn but before its SpeechMetadata starts a pending turn. The active turn stays active until its SpeechMetadata — if you haven’t received SpeechMetadata, the turn is still being synthesized — at which point the next pending turn becomes active and gets its own SpeechStarted.

SpeechMetadata

Emitted once per turn, after we’ve sent all of the turn’s audio — our signal that synthesis for the turn is complete and no more audio is coming for it. It follows your Flush, which tells us no more text is coming for the turn. Reports billing and timing for the completed turn.

1
{
2
  "type": "SpeechMetadata",
3
  "speech_id": "dg_sp_a1b2c3d4e5f6",
4
  "audio_duration_ms": 3200,
5
  "input_character_count": 47,
6
  "billable_character_count": 47,
7
  "controls_applied": {
8
    "pronunciations_applied": 0,
9
    "breaks_applied": 0,
10
    "pronunciation_warnings": 0
11
  }
12
}

SpeechInterrupted

Sent in response to an Interrupt. Reports exactly what the user heard and what they didn’t, plus a nested metadata block carrying the same shape as a standalone SpeechMetadata body.

1
{
2
  "type": "SpeechInterrupted",
3
  "audio_played_ms": 2340,
4
  "text_spoken": "Sure, I can help you cancel your subscription.",
5
  "text_remaining": " Let me pull up your account.",
6
  "metadata": {
7
    "speech_id": "dg_sp_a1b2c3d4e5f6",
8
    "audio_duration_ms": 2340,
9
    "input_character_count": 47,
10
    "billable_character_count": 47,
11
    "controls_applied": {
12
      "pronunciations_applied": 0,
13
      "breaks_applied": 0,
14
      "pronunciation_warnings": 0
15
    }
16
  }
17
}

Flushed

Emitted when the turn’s buffer has actually been flushed after a manual Flush — not on receipt of the Flush, and it can be held back behind earlier pending turns. The turn’s SpeechMetadata follows.

1
{
2
  "type": "Flushed",
3
  "speech_id": "dg_sp_a1b2c3d4e5f6"
4
}

SessionMetadata

Final server message before the WebSocket closes. Reports cumulative session totals — the sum across all turns.

1
{
2
  "type": "SessionMetadata",
3
  "total_audio_duration_ms": 184500,
4
  "total_input_character_count": 4280,
5
  "total_billable_character_count": 4280
6
}

An Interrupt rebases total_audio_duration_ms onto the audio the client actually played — audio generated past the interrupt point stops counting toward the session, so the total can decrease after a barge-in.

This is the one place cumulative totals are reported. Combined with the per-turn numbers in SpeechMetadata, you get clean reconciliation: per-turn for granular tracking, plus a final authoritative total.

ConfigureSuccess / ConfigureFailure

ConfigureSuccess

Sent when a Configure message is accepted. Echoes the applied configuration. Fires on receipt and validation, not on application — the change takes effect at the next segment boundary.

1
{
2
  "type": "ConfigureSuccess",
3
  "applied": {
4
    "speed": 1.15
5
  }
6
}

ConfigureFailure

Sent when a Configure message is rejected. The failing message has no effect — the prior configuration is retained and synthesis continues uninterrupted.

1
{
2
  "type": "ConfigureFailure",
3
  "code": "SPEED_OUT_OF_RANGE",
4
  "field": "speed",
5
  "value": 3.5,
6
  "description": "speed must be between 0.85 and 1.15 in 0.05 increments"
7
}

field and value identify the rejected field and the value you sent; they are present only when the failure is tied to a specific field/value. See the ConfigureFailure codes below.

Warning

Informational message; synthesis continues and the connection is unaffected. Every warning carries a code and a human-readable description.

1
{
2
  "type": "Warning",
3
  "code": "NO_ACTIVE_SPEECH",
4
  "description": "There is no active turn. The request will be ignored."
5
}

See the warning codes below. Warnings are not rate-limited — every occurrence is emitted.

Error

A fatal, server-originated error. Unlike a Warning, an Error is always followed by a WebSocket close.

1
{
2
  "type": "Error",
3
  "code": "MESSAGE-0000",
4
  "description": "The message could not be parsed."
5
}

See the error codes below.

Warning codes

All warning codes follow Deepgram’s SCREAMING_SNAKE_CASE convention; the session stays open in every case.

Turn-scoped:

Inline controls and markup (inline pause and pronunciation controls are coming soon; their codes take effect when they ship):

Interrupt-scoped (in every case the Interrupt is ignored and no SpeechInterrupted is sent):

ConfigureFailure codes

Connection rejection codes

An invalid expressivity value rejects the connection with an HTTP 400 before the WebSocket upgrade completes — no Connected message is sent. See Expressivity.

Error codes

Every error is fatal and is followed by a WebSocket close frame. Codes use Deepgram’s DOMAIN-NNNN convention.

Related resources

• Client Messages — the messages these respond to
• The Speech Lifecycle — how these events sequence across a turn
• Cross-Turn Context — voice consistency across turns