Server Events
All Lanson → client events pushed over WebSocket.
Events the server pushes over the WebSocket connection.
Overview
| type | Source | Description |
|---|---|---|
session.created | Gateway | Sent on connection establishment |
session.updated | Upstream | Confirms session parameter update |
input_audio_buffer.speech_started | Upstream | Speech segment detected |
input_audio_buffer.speech_stopped | Upstream | Speech segment ended |
conversation.item.input_audio_transcription.completed | Upstream | A speech segment has been transcribed (primary output) |
lanson.throttled | Gateway | Throttle notification (max once per second) |
error | Gateway / upstream | Error event |
session.created
Sent by the gateway immediately after connection.
{
"type": "session.created",
"request_id": "...",
"session_id": "sess_...",
"audio": { "format": "pcm_s16le", "sample_rate": 16000, "channels": 1 },
"turn_detection": { "type": "server_vad" },
"plan": "free",
"limits": {
"max_concurrent_utterances": 2,
"max_session_seconds": 900,
"idle_timeout_seconds": 60,
"remaining_audio_seconds": 3600
}
}
| Field | Type | Description |
|---|---|---|
session_id | string | Session identifier |
audio.format | string | Fixed: pcm_s16le |
audio.sample_rate | number | Fixed: 16000 |
audio.channels | number | Fixed: 1 |
turn_detection.type | string | Fixed: server_vad |
plan | string | Current plan |
limits.max_concurrent_utterances | number | Max concurrent utterances |
limits.max_session_seconds | number | Max session duration (seconds) |
limits.idle_timeout_seconds | number | Idle timeout (seconds) |
limits.remaining_audio_seconds | number | null | Remaining audio budget (null when unlimited) |
session.updated
Confirms that a session.update message has taken effect.
{
"type": "session.updated",
"request_id": "...",
"language": "zh",
"turn_detection": { "type": "server_vad" }
}
input_audio_buffer.speech_started
VAD detected the start of a speech segment.
{
"type": "input_audio_buffer.speech_started",
"request_id": "...",
"utterance_index": 0
}
input_audio_buffer.speech_stopped
VAD detected the end of a speech segment.
{
"type": "input_audio_buffer.speech_stopped",
"request_id": "...",
"utterance_index": 0,
"reason": "end_of_speech",
"audio_duration_ms": 3200,
"speech_duration_ms": 2800
}
| Field | Type | Description |
|---|---|---|
utterance_index | number | Speech segment number |
reason | string | Stop reason |
audio_duration_ms | number | Total audio duration |
speech_duration_ms | number? | Actual speech duration |
split_offset_ms | number? | Split offset |
split_rms | number? | Split RMS value |
conversation.item.input_audio_transcription.completed
Primary output event. A speech segment has been transcribed.
{
"type": "conversation.item.input_audio_transcription.completed",
"request_id": "...",
"utterance_index": 0,
"text": "The weather is nice today",
"language": "zh",
"audio_duration_ms": 3200,
"latency_ms": 480,
"segments": [],
"verbose": {}
}
| Field | Type | Description |
|---|---|---|
utterance_index | number | Speech segment number |
text | string | Transcribed text |
language | string | Detected language |
audio_duration_ms | number | Audio duration |
latency_ms | number | Processing latency |
segments | array | Segment details |
verbose | object | Upstream additional info |
lanson.throttled
Gateway throttle notification, sent at most once per second.
{
"type": "lanson.throttled",
"reason": "concurrent_utterance_limit",
"dropped_audio_frames": 3,
"in_flight_utterances": 2
}
reason value | Meaning |
|---|---|
concurrent_utterance_limit | Concurrent utterance limit exceeded |
upstream_backpressure | Upstream backpressure |
upstream_connecting | Upstream still connecting |
error
Error event. Can be sent at any time during the WebSocket connection.
{
"type": "error",
"code": "audio_frame_too_large",
"message": "Audio frame exceeds maximum size.",
"request_id": "..."
}
Error codes are listed in Errors.
Event ordering
session.created
→ [audio frames...]
→ input_audio_buffer.speech_started
→ [more audio...]
→ input_audio_buffer.speech_stopped
→ conversation.item.input_audio_transcription.completed
→ [repeat...]
→ session close
Related
- Client Messages — client-sent messages
- Errors — full error reference
- Transcript Lifecycle — state transitions