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

# Settings

> Every realtime WebSocket session setting: audio, speech detection, speech to text, turn taking and text to speech, with ranges, defaults, and what config.update can change.

Send settings in the handshake's `config`. Every field is optional: a field you leave out keeps its default. The reply, `handshake_ack`, has every setting after defaults.

```json theme={null}
{
  "type": "handshake",
  "api_key": "YOUR_API_KEY",
  "config": {
    "audio": { "encoding": "pcm16", "sample_rate": 16000, "channels": 1 },
    "vad": { "threshold": 0.5, "min_speech_ms": 100, "min_silence_ms": 550, "prefix_padding_ms": 250, "max_buffered_speech_s": 30 },
    "stt": {
      "enabled": true,
      "model": "Hamsa-STT-S4",
      "language": "ar",
      "eos_enabled": true,
      "eos_threshold": 0.3,
      "gender_detection": false,
      "speaker_identification": false,
      "speaker_similarity_threshold": 0.2,
      "vad_events": true,
      "turn": {
        "mode": "enhanced",
        "final_settle_ms": 400,
        "max_timeout_ms": 700,
        "preflight_timeout_ms": 2000,
        "digits_interim_timeout_ms": 3000,
        "digits_preflight_min": 6,
        "backchannel": "while_tts"
      }
    },
    "tts": { "voice": "Amjad", "dialect": "pls", "language": "ar", "mulaw": false, "output": "binary", "dictionary": {} }
  }
}
```

A value out of range, or of the wrong type, refuses the handshake with `handshake_required`; `message` names the field. A field name Hamsa doesn't know is ignored, so check spelling against `handshake_ack`. The **Changes** column says whether `config.update` can change it.

## audio

The audio you send.

| Field | Values | Default | Changes | Meaning |
| - | - | - | - | - |
| `encoding` | `pcm16`, `mulaw` | `pcm16` | No | `pcm16`: signed 16-bit little-endian. `mulaw`: G.711 µ-law |
| `sample_rate` | `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000` | `16000` | No | In Hz. Other rates than 16000 are converted |
| `channels` | `1`, `2` | `1` | No | Stereo is interleaved and mixed down to mono |

## vad

Speech detection. See [Speech detection](https://docs.tryhamsa.com/websocket/realtime/speech-to-text.md#speech-detection).

| Field | Range | Default | Changes | Meaning |
| - | - | - | - | - |
| `threshold` | 0.05 to 0.99 | `0.5` | Yes | Speech probability a 32 ms window needs. Higher ignores more noise |
| `min_speech_ms` | 32 to 2000 | `100` | Yes | Speech needed before `vad.speech_started` |
| `min_silence_ms` | 64 to 5000 | `550` | Yes | Silence that ends a speech segment. No transcript can come sooner after the caller stops |
| `prefix_padding_ms` | 0 to 2000 | `250` | Yes | Audio kept from before speech started |
| `max_buffered_speech_s` | 1 to 60 | `30` | No | Longest speech segment, in seconds. Values above 30 are treated as 30. Speech beyond it in the same segment isn't transcribed |

## stt

Speech to text. See [Speech to text](https://docs.tryhamsa.com/websocket/realtime/speech-to-text.md).

| Field | Values | Default | Changes | Meaning |
| - | - | - | - | - |
| `enabled` | `true`, `false` | `true` | No | `false`: a text to speech only session. Audio frames are refused |
| `model` | `Hamsa-STT-S4`, `Hamsa-STT-S3`, `Hamsa-STT-English` | `Hamsa-STT-S4` | Yes | See [Models and language](https://docs.tryhamsa.com/websocket/realtime/speech-to-text.md#models-and-language) |
| `language` | `ar`, `en`, `auto` | `ar` | Yes | `auto` lets the model detect it. `Hamsa-STT-S4` always detects it |
| `eos_enabled` | `true`, `false` | `true` | Yes | End of speech: is the caller done, or only pausing? |
| `eos_threshold` | 0.1 to 0.99 | `0.3` | Yes | End of speech probability above which the caller counts as done |
| `gender_detection` | `true`, `false` | `false` | Yes | Adds `gender` to transcripts of 0.7 seconds or more |
| `speaker_identification` | `true`, `false` | `false` | No | Adds `speaker` to transcripts |
| `speaker_similarity_threshold` | -1 to 1 | `0.2` | No | Voice similarity needed to match a known speaker. Lower gives fewer new speakers |
| `vad_events` | `true`, `false` | `true` | Yes | Send `vad.speech_started` and `vad.speech_stopped` |
| `turn` | object | | | See below |

### stt.turn

Turn taking. See [Turns](https://docs.tryhamsa.com/websocket/realtime/speech-to-text.md#turns).

| Field | Values | Default | Changes | Meaning |
| - | - | - | - | - |
| `mode` | `enhanced`, `segment` | `enhanced` | No | `enhanced`: segments are grouped into turns, and the whole turn is transcribed again with each segment. `segment`: one transcript per speech segment |
| `final_settle_ms` | 0 to 5000 | `400` | Yes | After end of speech says the caller is done, the silence to wait before the turn is final. `0`: final right away. At most `max_timeout_ms` |
| `max_timeout_ms` | 0 to 10000 | `700` | Yes | When the caller isn't done, the turn is final this long after the `interim`, if they don't talk again |
| `preflight_timeout_ms` | 0 to 10000 | `2000` | Yes | Wait after the `preflight` before a turn with a long number is final |
| `digits_interim_timeout_ms` | 0 to 10000 | `3000` | Yes | Wait used instead of `max_timeout_ms` when the caller stopped in the middle of a number |
| `digits_preflight_min` | 1 to 30 | `6` | Yes | Digits that make a number long |
| `backchannel` | `off`, `always`, `while_tts` | `while_tts` | Yes | When a short reply such as "mhm" or "تمام" doesn't end a turn. See [Backchannels](https://docs.tryhamsa.com/websocket/realtime/speech-to-text.md#backchannels) |
| `backchannel_phrases` | Up to 500 strings of up to 64 characters | Built-in Arabic and English list | No | Replaces the list. `handshake_ack` shows how many you sent, as `custom_backchannel_phrases` |

## tts

Text to speech. `voice`, `dialect`, `language` and `model` can also be set for one request. See [Text to speech](https://docs.tryhamsa.com/websocket/realtime/text-to-speech.md).

| Field | Values | Default | Changes | Meaning |
| - | - | - | - | - |
| `voice` | Voice name or cloned voice ID, up to 128 characters | `Ali` | Yes | A voice of the dialect (any letter case). Names: [Realtime voice names](https://docs.tryhamsa.com/text-to-speech/voices.md#realtime-voice-names). A voice ID must be one of your voices or a public voice. [Preload a cloned voice](https://docs.tryhamsa.com/api-reference/endpoint/preload-cloned-tts-voice.md) before you use it |
| `dialect` | `pls`, `egy`, `ksa`, `uae`, `jor`, `leb`, `syr`, `irq`, `kuw`, `qat`, `bah`, `oma`, `msa`, `ar-sa`, `en` | `pls` | Yes | The voice's dialect |
| `language` | `ar`, `en` | `ar` | Yes | `en` for English voices (16 or 24 kHz audio: read `sample_rate` from `tts.started`) |
| `expressiveness` | 0 to 2 | `1` | Yes | **Deprecated.** Still accepted, from flat and steady to very expressive; don't build on it |
| `model` | Up to 64 characters | | Yes | A custom voice model made for your account, if you have one |
| `mulaw` | `true`, `false` | `false` | Yes | `true`: 8 kHz µ-law audio |
| `output` | `binary`, `base64` | `binary` | Yes | `base64`: audio in `tts.audio` messages instead of binary frames |
| `dictionary` | `{"word": "replacement"}` | `{}` | Yes | Pronunciation fixes. See [Pronunciation fixes](https://docs.tryhamsa.com/websocket/realtime/text-to-speech.md#pronunciation-fixes) |

`Ali` exists in more than one dialect, so set `voice` and `dialect` together.

## Change settings during a session

```json theme={null}
{ "type": "config.update", "config": { "vad": { "min_silence_ms": 350 }, "tts": { "voice": "Mariam", "dialect": "egy" } } }
```

The reply is `config.updated`, with every setting:

```json theme={null}
{ "type": "config.updated", "config": { "audio": { ... }, "vad": { ... }, "stt": { ... }, "tts": { ... } } }
```

* Send only what changes; the rest stays.
* Speech detection and turn settings apply right away. Text to speech settings apply to requests that haven't started yet, except `output` and `dictionary`, which also apply to the request that is speaking: change those between requests.
* Fields that can't change (**No** above) are ignored, except `audio`, which gets an `invalid_message` error.
* If any value is out of range, nothing is changed and you get an `invalid_message` error that names the field.


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