Settings

Send a Settings message to configure the voice agent’s behavior, audio formats, and provider configurations before starting the conversation.

Voice Agent

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.

For a detailed explanation of all the options available for the Settings message, see our documentation on how to Configure the Voice Agent.

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:

JSON
1{
2"type": "Settings",
3"audio": {
4  "input": {
5    "encoding": "linear16",
6    "sample_rate": 24000
7  },
8  "output": {
9    "encoding": "linear16",
10    "sample_rate": 24000,
11    "container": "none"
12    // ... additional output options: bitrate
13  }
14},
15"agent": {
16  "language": "en",
17  "listen": {
18    "provider": {
19      "type": "deepgram",
20      "model": "nova-3"
21      // ... additional provider options: keyterms (nova-3 'en' only)
22    }
23  },
24  "think": {
25    "provider": {
26      "type": "open_ai",
27      "model": "gpt-4o-mini",
28      "temperature": 0.7
29      // ... additional provider options: endpoint (for non-deepgram providers)
30    },
31    // ... additional think options: prompt, functions, endpoint
32  },
33  "speak": {
34    "provider": {
35      "type": "deepgram",
36      "model": "aura-2-thalia-en"
37      // ... additional provider options based on type:
38      // - eleven_labs: model_id, language_code
39      // - cartesia: model_id, voice (mode, id), language
40      // - open_ai: voice
41    }
42    // ... additional speak options: endpoint (for non-deepgram providers)
43  }
44  // ... additional agent options: greeting
45}
46// ... additional top-level options: experimental
47}

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

JSON
1{
2    "type": "SettingsApplied"
3}
Built with