Settings

The Settings message is a JSON command that serves as an initialization step, setting up both the behavior of the voice agent.

Purpose

The Settings message is an initialization command that establishes both the behavior of the voice agent and the audio transmission formats before voice data is exchanged. The client should send a Settings message immediately after opening the websocket and before sending any audio.

Example Payloads

This example uses a very basic Settings to establish a connection. To send the Settings message, you need to send the following JSON message to the server:

1
{
2
"type": "Settings",
3
"tags": ["demo", "voice_agent"],
4
"audio": {
5
  "input": {
6
    "encoding": "linear16",
7
    "sample_rate": 24000
8
  },
9
  "output": {
10
    "encoding": "linear16",
11
    "sample_rate": 24000,
12
    "container": "none"
13
  }
14
},
15
"agent": {
16
  "language": "en",
17
  "listen": {
18
    "provider": {
19
      "type": "deepgram",
20
      "model": "nova-3",
21
      "smart_format": false
22
    }
23
  },
24
  "think": {
25
    "provider": {
26
      "type": "open_ai",
27
      "model": "gpt-4o-mini",
28
      "temperature": 0.7
29
    }
30
  },
31
  "speak": {
32
    "provider": {
33
      "type": "deepgram",
34
      "model": "aura-2-thalia-en"
35
    }
36
  }
37
}
38
}

Upon receiving the Settings message, the server will process all remaining audio data and return the following SettingsApplied message.

1
{
2
    "type": "SettingsApplied"
3
}

Next Steps

• Voice Agent Message Flow for the correct message flow when building a Voice Agent client.