> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kyutai-labs/unmute/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Events

> Events sent from server to client via WebSocket

## Overview

Server events are messages sent from the Unmute backend to the client. These events stream audio responses, transcriptions, and status updates.

## session.updated

Confirms that the session configuration was successfully updated.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"session.updated"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="session" type="object" required>
  The updated session configuration (mirrors the `session.update` request)
</ResponseField>

### Example

```json theme={null}
{
  "type": "session.updated",
  "event_id": "event_DEF456uvw",
  "session": {
    "instructions": {
      "character": "You are a helpful AI assistant.",
      "scenario": "Casual conversation"
    },
    "voice": "default",
    "allow_recording": false
  }
}
```

***

## response.created

Indicates that the assistant has started generating a response.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"response.created"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="response" type="object" required>
  Response metadata

  <ResponseField name="response.object" type="string" required>
    Always `"realtime.response"`
  </ResponseField>

  <ResponseField name="response.status" type="string" required>
    Response status. One of: `"in_progress"`, `"completed"`, `"cancelled"`, `"failed"`, `"incomplete"`
  </ResponseField>

  <ResponseField name="response.voice" type="string" required>
    Voice identifier being used for this response
  </ResponseField>

  <ResponseField name="response.chat_history" type="array" default="[]">
    Conversation history (array of message objects)
  </ResponseField>
</ResponseField>

### Example

```json theme={null}
{
  "type": "response.created",
  "event_id": "event_GHI789rst",
  "response": {
    "object": "realtime.response",
    "status": "in_progress",
    "voice": "default",
    "chat_history": []
  }
}
```

***

## response.audio.delta

Streams generated speech audio to the client.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"response.audio.delta"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="delta" type="string" required>
  Base64-encoded Opus audio chunk

  **Audio Specifications:**

  * Codec: Opus
  * Sample Rate: 24 kHz
  * Channels: Mono
  * Encoding: Base64 string
</ResponseField>

### Example

```json theme={null}
{
  "type": "response.audio.delta",
  "event_id": "event_JKL012mno",
  "delta": "T2dnUwACAAAAAAAAAAAljMlAAAAABCmR7kBE09w..."
}
```

### Implementation Notes

* Audio chunks are sent as they become available from the text-to-speech system
* Due to Opus buffering, not every PCM chunk results in output
* Chunks should be decoded and played in sequence

### JavaScript Example

```javascript theme={null}
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.type === 'response.audio.delta') {
    // Decode base64 audio
    const audioData = atob(message.delta);
    const audioBytes = new Uint8Array(audioData.length);
    for (let i = 0; i < audioData.length; i++) {
      audioBytes[i] = audioData.charCodeAt(i);
    }
    
    // Play audio using Web Audio API or audio element
    playOpusAudio(audioBytes);
  }
};
```

***

## response.audio.done

Indicates that audio streaming for the current response has completed.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"response.audio.done"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

### Example

```json theme={null}
{
  "type": "response.audio.done",
  "event_id": "event_MNO345pqr"
}
```

***

## response.text.delta

Streams the text being generated (for display or debugging).

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"response.text.delta"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="delta" type="string" required>
  Text chunk being generated
</ResponseField>

### Example

```json theme={null}
{
  "type": "response.text.delta",
  "event_id": "event_PQR678stu",
  "delta": "Hello! How can I "
}
```

***

## response.text.done

Indicates that text generation is complete and provides the full text.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"response.text.done"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="text" type="string" required>
  Complete generated text
</ResponseField>

### Example

```json theme={null}
{
  "type": "response.text.done",
  "event_id": "event_STU901vwx",
  "text": "Hello! How can I help you today?"
}
```

***

## conversation.item.input\_audio\_transcription.delta

Streams real-time transcription of user speech.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"conversation.item.input_audio_transcription.delta"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="delta" type="string" required>
  Transcription text chunk
</ResponseField>

<ResponseField name="start_time" type="number" required>
  Timestamp when speech started (Unmute extension)
</ResponseField>

### Example

```json theme={null}
{
  "type": "conversation.item.input_audio_transcription.delta",
  "event_id": "event_VWX234yza",
  "delta": "Hello, can you",
  "start_time": 1234567890.123
}
```

***

## input\_audio\_buffer.speech\_started

Indicates that speech was detected in the user's audio input.

**Note**: Based on speech-to-text detection, not voice activity detection (VAD). This ensures the event is only sent when actual speech is transcribed.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"input_audio_buffer.speech_started"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

### Example

```json theme={null}
{
  "type": "input_audio_buffer.speech_started",
  "event_id": "event_YZA567bcd"
}
```

***

## input\_audio\_buffer.speech\_stopped

Indicates that a pause was detected in the user's audio input.

**Note**: Based on voice activity detection (VAD).

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"input_audio_buffer.speech_stopped"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

### Example

```json theme={null}
{
  "type": "input_audio_buffer.speech_stopped",
  "event_id": "event_BCD890efg"
}
```

***

## unmute.interrupted\_by\_vad

Indicates that the voice activity detector interrupted the assistant's response generation because the user started speaking.

**Unmute Extension**: This event is specific to Unmute.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"unmute.interrupted_by_vad"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

### Example

```json theme={null}
{
  "type": "unmute.interrupted_by_vad",
  "event_id": "event_EFG123hij"
}
```

***

## unmute.response.text.delta.ready

Indicates that a text delta is ready for processing.

**Unmute Extension**: This event is specific to Unmute.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"unmute.response.text.delta.ready"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="delta" type="string" required>
  Text chunk that is ready
</ResponseField>

### Example

```json theme={null}
{
  "type": "unmute.response.text.delta.ready",
  "event_id": "event_HIJ456klm",
  "delta": "help you today?"
}
```

***

## unmute.response.audio.delta.ready

Indicates that an audio delta is ready with sample count information.

**Unmute Extension**: This event is specific to Unmute.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"unmute.response.audio.delta.ready"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="number_of_samples" type="integer" required>
  Number of audio samples in this chunk
</ResponseField>

### Example

```json theme={null}
{
  "type": "unmute.response.audio.delta.ready",
  "event_id": "event_KLM789nop",
  "number_of_samples": 480
}
```

***

## unmute.additional\_outputs

Provides additional debug or metadata outputs from the system.

**Unmute Extension**: This event is specific to Unmute and used for debugging.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"unmute.additional_outputs"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="args" type="any" required>
  Additional output data (structure varies)
</ResponseField>

### Example

```json theme={null}
{
  "type": "unmute.additional_outputs",
  "event_id": "event_NOP012qrs",
  "args": {
    "debug_info": "Processing latency: 45ms"
  }
}
```

***

## error

Reports errors during the WebSocket session.

### Response Fields

<ResponseField name="type" type="string" required>
  Always `"error"`
</ResponseField>

<ResponseField name="event_id" type="string" required>
  Unique event identifier
</ResponseField>

<ResponseField name="error" type="object" required>
  Error details

  <ResponseField name="error.type" type="string" required>
    Error type (e.g., `"invalid_request_error"`, `"fatal"`)
  </ResponseField>

  <ResponseField name="error.code" type="string">
    Error code (optional)
  </ResponseField>

  <ResponseField name="error.message" type="string" required>
    Human-readable error message
  </ResponseField>

  <ResponseField name="error.param" type="string">
    Parameter that caused the error (optional)
  </ResponseField>

  <ResponseField name="error.details" type="any">
    Additional error details (Unmute extension, optional)
  </ResponseField>
</ResponseField>

### Example: Invalid JSON

```json theme={null}
{
  "type": "error",
  "event_id": "event_QRS345tuv",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid JSON: Expecting value: line 1 column 1 (char 0)"
  }
}
```

### Example: Fatal Error

```json theme={null}
{
  "type": "error",
  "event_id": "event_TUV678wxy",
  "error": {
    "type": "fatal",
    "message": "Too many people are connected to service 'tts'. Please try again later."
  }
}
```

**Note**: Fatal errors typically result in the WebSocket connection being closed by the server.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Client Events" icon="arrow-up" href="/api/client-events">
    Events sent from client to server
  </Card>

  <Card title="Session Management" icon="gear" href="/api/session-management">
    Configure voice and conversation settings
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.