> ## 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.

# Message reference

> Every message of the realtime WebSocket, with its fields and examples: what you send and what Hamsa sends back.

Every message is JSON with a `type`, except audio, which goes in binary frames both ways. Start with a `handshake`; see [Realtime WebSocket](https://docs.tryhamsa.com/websocket/realtime/overview.md) for the flow, errors and limits. To try the session with your microphone and hear the voices, use the [Playground](https://docs.tryhamsa.com/websocket/realtime/playground.md).

> [!TIP]
>
> To try messages here, fill in the **Handshake** first (your key in `api_key`), then click **Connect** and send it: the server waits 5 seconds for it.


## AsyncAPI

````yaml websocket/asyncapi-realtime.json realtime
id: realtime
title: Realtime session
description: >-
  Send a `handshake` first, then audio (binary frames) and JSON messages. Speech
  audio comes back in binary frames.
servers:
  - id: production
    protocol: wss
    host: realtime.tryhamsa.com
    bindings: []
    variables: []
address: /v1
parameters: []
bindings: []
operations:
  - &ref_13
    id: sendToHamsa
    title: Send
    description: Messages your app sends
    type: receive
    messages:
      - &ref_15
        id: handshake
        contentType: application/json
        payload:
          - name: handshake
            description: >-
              Authenticate and configure the session. Must be the first message,
              within 5 seconds.
            type: object
            properties:
              - name: type
                type: string
                description: '`"handshake"`'
                required: true
              - name: api_key
                type: string
                description: >-
                  A secret key (`sk_...`) or an older (legacy) key. A public key
                  (`pk_...`) is refused. Without it, the key is read from the
                  `x-api-key` header or the `api_key` query parameter.
                required: false
              - name: config
                type: object
                description: >-
                  Every field is optional; a field you leave out keeps its
                  default.
                required: false
                properties:
                  - name: audio
                    type: object
                    description: The audio you send. Fixed for the session.
                    required: false
                    properties:
                      - name: encoding
                        type: string
                        description: >-
                          `pcm16`: signed 16-bit little-endian. `mulaw`: G.711
                          µ-law (phone audio).
                        enumValues:
                          - pcm16
                          - mulaw
                        required: false
                      - name: sample_rate
                        type: integer
                        description: >-
                          Sample rate in Hz. 16000 is used as is; other rates
                          are converted to 16000.
                        enumValues:
                          - 8000
                          - 16000
                          - 22050
                          - 24000
                          - 32000
                          - 44100
                          - 48000
                        required: false
                      - name: channels
                        type: integer
                        description: '`2`: interleaved stereo, mixed down to mono.'
                        enumValues:
                          - 1
                          - 2
                        required: false
                  - name: vad
                    type: object
                    description: >-
                      Voice activity detection: decides where speech starts and
                      stops.
                    required: false
                    properties:
                      - name: threshold
                        type: number
                        description: >-
                          Speech probability a 32 ms window needs to count as
                          speech. Higher ignores more noise.
                        required: false
                      - name: min_speech_ms
                        type: integer
                        description: Speech needed before `vad.speech_started`.
                        required: false
                      - name: min_silence_ms
                        type: integer
                        description: >-
                          Silence that ends a speech segment. No transcript can
                          arrive sooner than this after the caller stops.
                        required: false
                      - name: prefix_padding_ms
                        type: integer
                        description: >-
                          Audio kept from before speech started, so the first
                          syllable isn't cut.
                        required: false
                      - name: max_buffered_speech_s
                        type: number
                        description: >-
                          Longest speech segment, in seconds. Values above 30
                          are treated as 30. Speech beyond it in the same
                          segment isn't transcribed. Fixed for the session.
                        required: false
                  - name: stt
                    type: object
                    description: Speech to text.
                    required: false
                    properties:
                      - name: enabled
                        type: boolean
                        description: >-
                          `false` makes a text to speech only session: audio
                          frames are refused. Fixed for the session.
                        required: false
                      - name: model
                        type: string
                        description: >-
                          Speech to text model: `Hamsa-STT-S4` (default; detects
                          the language itself), `Hamsa-STT-S3` or
                          `Hamsa-STT-English`. `Hamsa-STT-S2` and
                          `Hamsa-STT-S2-deprecated` are still accepted as
                          deprecated names for `Hamsa-STT-S4`.
                        enumValues:
                          - Hamsa-STT-S4
                          - Hamsa-STT-S3
                          - Hamsa-STT-English
                        required: false
                      - name: language
                        type: string
                        description: >-
                          `auto` lets the model detect the language.
                          `Hamsa-STT-S4` always detects it.
                        enumValues:
                          - ar
                          - en
                          - auto
                        required: false
                      - name: eos_enabled
                        type: boolean
                        description: >-
                          End of speech detection: is the caller done, or only
                          pausing?
                        required: false
                      - name: eos_threshold
                        type: number
                        description: >-
                          End of speech probability above which the caller
                          counts as done.
                        required: false
                      - name: gender_detection
                        type: boolean
                        description: >-
                          Adds `gender` to transcripts of 0.7 seconds of audio
                          or more.
                        required: false
                      - name: speaker_identification
                        type: boolean
                        description: >-
                          Adds `speaker` (`Speaker1`, `Speaker2`, ...), matched
                          within the session. Fixed for the session.
                        required: false
                      - name: speaker_similarity_threshold
                        type: number
                        description: >-
                          Voice similarity needed to match a known speaker.
                          Lower gives fewer new speakers. Fixed for the session.
                        required: false
                      - name: vad_events
                        type: boolean
                        description: Send `vad.speech_started` and `vad.speech_stopped`.
                        required: false
                      - name: turn
                        type: object
                        description: Turn taking.
                        required: false
                        properties:
                          - name: mode
                            type: string
                            description: >-
                              `enhanced`: segments are grouped into turns and
                              the whole turn is transcribed again with each new
                              segment. `segment`: one result per speech segment.
                              Fixed for the session.
                            enumValues:
                              - enhanced
                              - segment
                            required: false
                          - name: final_settle_ms
                            type: integer
                            description: >-
                              After end of speech says the caller is done, the
                              silence to wait for before the turn is final. `0`
                              makes it final right away. Capped by
                              `max_timeout_ms`.
                            required: false
                          - name: max_timeout_ms
                            type: integer
                            description: >-
                              When end of speech says the caller isn't done, the
                              turn is made final this long after the `interim`,
                              if the caller doesn't talk again.
                            required: false
                          - name: preflight_timeout_ms
                            type: integer
                            description: >-
                              Wait after the `preflight` before a turn with a
                              long spoken number (at least
                              `digits_preflight_min` digits 0-9 separated by
                              spaces) is made final.
                            required: false
                          - name: digits_interim_timeout_ms
                            type: integer
                            description: >-
                              Wait used instead of `max_timeout_ms` when the
                              caller stopped in the middle of saying a number.
                            required: false
                          - name: digits_preflight_min
                            type: integer
                            description: Digits that make a number "long".
                            required: false
                          - name: backchannel
                            type: string
                            description: >-
                              Short replies such as "mhm", "تمام" or "نعم" are
                              sent with `backchannel: true` and don't end a
                              turn. `while_tts`: only while speech is being
                              generated, or while your client reports `playback:
                              playing`.
                            enumValues:
                              - 'off'
                              - always
                              - while_tts
                            required: false
                          - name: backchannel_phrases
                            type: array
                            description: >-
                              Replaces the built-in Arabic and English list.
                              Fixed for the session.
                            required: false
                            properties:
                              - name: item
                                type: string
                                required: false
                  - name: tts
                    type: object
                    description: >-
                      Text to speech defaults. Each `tts` request can override
                      `voice`, `dialect`, `language` and `model`.
                    required: false
                    properties:
                      - name: voice
                        type: string
                        description: >-
                          A voice name of the dialect (any letter case), or a
                          voice ID: one of your cloned voices or a public voice.
                          A voice ID uses its own language and dialect unless
                          the request sets them. Preload a cloned voice before
                          you use it.
                        required: false
                      - name: dialect
                        type: string
                        description: The voice's dialect code.
                        enumValues:
                          - pls
                          - egy
                          - ksa
                          - uae
                          - jor
                          - leb
                          - syr
                          - irq
                          - kuw
                          - qat
                          - bah
                          - oma
                          - msa
                          - ar-sa
                          - en
                        required: false
                      - name: language
                        type: string
                        description: >-
                          `en` for English voices (16 or 24 kHz audio: read
                          `sample_rate` from `tts.started`).
                        enumValues:
                          - ar
                          - en
                        required: false
                      - name: expressiveness
                        type: number
                        description: >-
                          Deprecated. Still accepted (0 to 2, default 1); don't
                          build on it.
                        deprecated: true
                        required: false
                      - name: model
                        type: string
                        description: >-
                          A custom voice model made for your account, if you
                          have one.
                        required: false
                      - name: mulaw
                        type: boolean
                        description: '`true`: 8 kHz µ-law audio (phone audio).'
                        required: false
                      - name: output
                        type: string
                        description: >-
                          `binary`: audio in binary frames. `base64`: audio in
                          `tts.audio` messages.
                        enumValues:
                          - binary
                          - base64
                        required: false
                      - name: dictionary
                        type: object
                        description: >-
                          Pronunciation fixes: `{"word or phrase":
                          "replacement"}`. Whole words only, Arabic diacritics
                          ignored, longest phrase first. Keys up to 200
                          characters.
                        required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: handshake
              description: '`"handshake"`'
              x-parser-schema-id: <anonymous-schema-2>
            api_key:
              type: string
              minLength: 1
              maxLength: 256
              description: >-
                A secret key (`sk_...`) or an older (legacy) key. A public key
                (`pk_...`) is refused. Without it, the key is read from the
                `x-api-key` header or the `api_key` query parameter.
              x-parser-schema-id: <anonymous-schema-3>
            config:
              type: object
              description: >-
                Every field is optional; a field you leave out keeps its
                default.
              properties:
                audio:
                  type: object
                  description: The audio you send. Fixed for the session.
                  properties:
                    encoding:
                      type: string
                      enum:
                        - pcm16
                        - mulaw
                      description: >-
                        `pcm16`: signed 16-bit little-endian. `mulaw`: G.711
                        µ-law (phone audio).
                      default: pcm16
                      x-parser-schema-id: <anonymous-schema-6>
                    sample_rate:
                      type: integer
                      enum:
                        - 8000
                        - 16000
                        - 22050
                        - 24000
                        - 32000
                        - 44100
                        - 48000
                      description: >-
                        Sample rate in Hz. 16000 is used as is; other rates are
                        converted to 16000.
                      default: 16000
                      x-parser-schema-id: <anonymous-schema-7>
                    channels:
                      type: integer
                      enum:
                        - 1
                        - 2
                      description: '`2`: interleaved stereo, mixed down to mono.'
                      default: 1
                      x-parser-schema-id: <anonymous-schema-8>
                  x-parser-schema-id: <anonymous-schema-5>
                vad:
                  type: object
                  description: >-
                    Voice activity detection: decides where speech starts and
                    stops.
                  properties:
                    threshold:
                      type: number
                      minimum: 0.05
                      maximum: 0.99
                      default: 0.5
                      description: >-
                        Speech probability a 32 ms window needs to count as
                        speech. Higher ignores more noise.
                      x-parser-schema-id: <anonymous-schema-10>
                    min_speech_ms:
                      type: integer
                      minimum: 32
                      maximum: 2000
                      default: 100
                      description: Speech needed before `vad.speech_started`.
                      x-parser-schema-id: <anonymous-schema-11>
                    min_silence_ms:
                      type: integer
                      minimum: 64
                      maximum: 5000
                      default: 550
                      description: >-
                        Silence that ends a speech segment. No transcript can
                        arrive sooner than this after the caller stops.
                      x-parser-schema-id: <anonymous-schema-12>
                    prefix_padding_ms:
                      type: integer
                      minimum: 0
                      maximum: 2000
                      default: 250
                      description: >-
                        Audio kept from before speech started, so the first
                        syllable isn't cut.
                      x-parser-schema-id: <anonymous-schema-13>
                    max_buffered_speech_s:
                      type: number
                      minimum: 1
                      maximum: 60
                      default: 30
                      description: >-
                        Longest speech segment, in seconds. Values above 30 are
                        treated as 30. Speech beyond it in the same segment
                        isn't transcribed. Fixed for the session.
                      x-parser-schema-id: <anonymous-schema-14>
                  x-parser-schema-id: <anonymous-schema-9>
                stt:
                  type: object
                  description: Speech to text.
                  properties:
                    enabled:
                      type: boolean
                      default: true
                      description: >-
                        `false` makes a text to speech only session: audio
                        frames are refused. Fixed for the session.
                      x-parser-schema-id: <anonymous-schema-16>
                    model:
                      type: string
                      enum:
                        - Hamsa-STT-S4
                        - Hamsa-STT-S3
                        - Hamsa-STT-English
                      description: >-
                        Speech to text model: `Hamsa-STT-S4` (default; detects
                        the language itself), `Hamsa-STT-S3` or
                        `Hamsa-STT-English`. `Hamsa-STT-S2` and
                        `Hamsa-STT-S2-deprecated` are still accepted as
                        deprecated names for `Hamsa-STT-S4`.
                      default: Hamsa-STT-S4
                      x-parser-schema-id: <anonymous-schema-17>
                    language:
                      type: string
                      enum:
                        - ar
                        - en
                        - auto
                      description: >-
                        `auto` lets the model detect the language.
                        `Hamsa-STT-S4` always detects it.
                      default: ar
                      x-parser-schema-id: <anonymous-schema-18>
                    eos_enabled:
                      type: boolean
                      default: true
                      description: >-
                        End of speech detection: is the caller done, or only
                        pausing?
                      x-parser-schema-id: <anonymous-schema-19>
                    eos_threshold:
                      type: number
                      minimum: 0.1
                      maximum: 0.99
                      default: 0.3
                      description: >-
                        End of speech probability above which the caller counts
                        as done.
                      x-parser-schema-id: <anonymous-schema-20>
                    gender_detection:
                      type: boolean
                      default: false
                      description: >-
                        Adds `gender` to transcripts of 0.7 seconds of audio or
                        more.
                      x-parser-schema-id: <anonymous-schema-21>
                    speaker_identification:
                      type: boolean
                      default: false
                      description: >-
                        Adds `speaker` (`Speaker1`, `Speaker2`, ...), matched
                        within the session. Fixed for the session.
                      x-parser-schema-id: <anonymous-schema-22>
                    speaker_similarity_threshold:
                      type: number
                      minimum: -1
                      maximum: 1
                      default: 0.2
                      description: >-
                        Voice similarity needed to match a known speaker. Lower
                        gives fewer new speakers. Fixed for the session.
                      x-parser-schema-id: <anonymous-schema-23>
                    vad_events:
                      type: boolean
                      default: true
                      description: Send `vad.speech_started` and `vad.speech_stopped`.
                      x-parser-schema-id: <anonymous-schema-24>
                    turn:
                      type: object
                      description: Turn taking.
                      properties:
                        mode:
                          type: string
                          enum:
                            - enhanced
                            - segment
                          description: >-
                            `enhanced`: segments are grouped into turns and the
                            whole turn is transcribed again with each new
                            segment. `segment`: one result per speech segment.
                            Fixed for the session.
                          default: enhanced
                          x-parser-schema-id: <anonymous-schema-26>
                        final_settle_ms:
                          type: integer
                          minimum: 0
                          maximum: 5000
                          default: 400
                          description: >-
                            After end of speech says the caller is done, the
                            silence to wait for before the turn is final. `0`
                            makes it final right away. Capped by
                            `max_timeout_ms`.
                          x-parser-schema-id: <anonymous-schema-27>
                        max_timeout_ms:
                          type: integer
                          minimum: 0
                          maximum: 10000
                          default: 700
                          description: >-
                            When end of speech says the caller isn't done, the
                            turn is made final this long after the `interim`, if
                            the caller doesn't talk again.
                          x-parser-schema-id: <anonymous-schema-28>
                        preflight_timeout_ms:
                          type: integer
                          minimum: 0
                          maximum: 10000
                          default: 2000
                          description: >-
                            Wait after the `preflight` before a turn with a long
                            spoken number (at least `digits_preflight_min`
                            digits 0-9 separated by spaces) is made final.
                          x-parser-schema-id: <anonymous-schema-29>
                        digits_interim_timeout_ms:
                          type: integer
                          minimum: 0
                          maximum: 10000
                          default: 3000
                          description: >-
                            Wait used instead of `max_timeout_ms` when the
                            caller stopped in the middle of saying a number.
                          x-parser-schema-id: <anonymous-schema-30>
                        digits_preflight_min:
                          type: integer
                          minimum: 1
                          maximum: 30
                          default: 6
                          description: Digits that make a number "long".
                          x-parser-schema-id: <anonymous-schema-31>
                        backchannel:
                          type: string
                          enum:
                            - 'off'
                            - always
                            - while_tts
                          description: >-
                            Short replies such as "mhm", "تمام" or "نعم" are
                            sent with `backchannel: true` and don't end a turn.
                            `while_tts`: only while speech is being generated,
                            or while your client reports `playback: playing`.
                          default: while_tts
                          x-parser-schema-id: <anonymous-schema-32>
                        backchannel_phrases:
                          type: array
                          maxItems: 500
                          items:
                            type: string
                            maxLength: 64
                            x-parser-schema-id: <anonymous-schema-34>
                          description: >-
                            Replaces the built-in Arabic and English list. Fixed
                            for the session.
                          x-parser-schema-id: <anonymous-schema-33>
                      x-parser-schema-id: <anonymous-schema-25>
                  x-parser-schema-id: <anonymous-schema-15>
                tts:
                  type: object
                  description: >-
                    Text to speech defaults. Each `tts` request can override
                    `voice`, `dialect`, `language` and `model`.
                  properties:
                    voice:
                      type: string
                      minLength: 1
                      maxLength: 128
                      default: Ali
                      description: >-
                        A voice name of the dialect (any letter case), or a
                        voice ID: one of your cloned voices or a public voice. A
                        voice ID uses its own language and dialect unless the
                        request sets them. Preload a cloned voice before you use
                        it.
                      x-parser-schema-id: <anonymous-schema-36>
                    dialect:
                      type: string
                      enum:
                        - pls
                        - egy
                        - ksa
                        - uae
                        - jor
                        - leb
                        - syr
                        - irq
                        - kuw
                        - qat
                        - bah
                        - oma
                        - msa
                        - ar-sa
                        - en
                      default: pls
                      description: The voice's dialect code.
                      x-parser-schema-id: <anonymous-schema-37>
                    language:
                      type: string
                      enum:
                        - ar
                        - en
                      description: >-
                        `en` for English voices (16 or 24 kHz audio: read
                        `sample_rate` from `tts.started`).
                      default: ar
                      x-parser-schema-id: <anonymous-schema-38>
                    expressiveness:
                      type: number
                      minimum: 0
                      maximum: 2
                      default: 1
                      description: >-
                        Deprecated. Still accepted (0 to 2, default 1); don't
                        build on it.
                      deprecated: true
                      x-parser-schema-id: <anonymous-schema-39>
                    model:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: >-
                        A custom voice model made for your account, if you have
                        one.
                      x-parser-schema-id: <anonymous-schema-40>
                    mulaw:
                      type: boolean
                      default: false
                      description: '`true`: 8 kHz µ-law audio (phone audio).'
                      x-parser-schema-id: <anonymous-schema-41>
                    output:
                      type: string
                      enum:
                        - binary
                        - base64
                      description: >-
                        `binary`: audio in binary frames. `base64`: audio in
                        `tts.audio` messages.
                      default: binary
                      x-parser-schema-id: <anonymous-schema-42>
                    dictionary:
                      type: object
                      additionalProperties:
                        type: string
                        maxLength: 500
                        x-parser-schema-id: <anonymous-schema-44>
                      description: >-
                        Pronunciation fixes: `{"word or phrase":
                        "replacement"}`. Whole words only, Arabic diacritics
                        ignored, longest phrase first. Keys up to 200
                        characters.
                      x-parser-schema-id: <anonymous-schema-43>
                  x-parser-schema-id: <anonymous-schema-35>
              x-parser-schema-id: <anonymous-schema-4>
          required:
            - type
          x-parser-schema-id: <anonymous-schema-1>
        title: Handshake
        description: >-
          Authenticate and configure the session. Must be the first message,
          within 5 seconds.
        example: |-
          {
            "type": "handshake",
            "api_key": "YOUR_API_KEY",
            "config": {
              "audio": {
                "encoding": "pcm16",
                "sample_rate": 16000
              },
              "stt": {
                "model": "Hamsa-STT-S4",
                "language": "ar",
                "gender_detection": true
              },
              "tts": {
                "voice": "Amjad",
                "dialect": "pls"
              }
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: handshake
      - &ref_16
        id: inputAudio
        contentType: application/octet-stream
        payload:
          - type: string
            format: binary
            description: Your audio, as binary frames in the handshake's `audio` format.
            x-parser-schema-id: <anonymous-schema-45>
            name: Audio (binary)
        headers: []
        jsonPayloadSchema:
          type: string
          format: binary
          description: >-
            Raw audio in binary frames, any size up to 1 MB (20 to 100 ms each
            works best). Send it as it is captured, silence included. Refused
            when `stt.enabled` is `false`.
          x-parser-schema-id: <anonymous-schema-45>
        title: Audio (binary)
        description: Your audio, as binary frames in the handshake's `audio` format.
        example: '{}'
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: inputAudio
      - &ref_17
        id: configUpdate
        contentType: application/json
        payload:
          - name: config.update
            description: Change settings during the session.
            type: object
            properties:
              - name: type
                type: string
                description: '`"config.update"`'
                required: true
              - name: config
                type: object
                description: >-
                  Fields you can change during a session. Other fields are fixed
                  by the handshake.
                required: true
                properties:
                  - name: vad
                    type: object
                    description: >-
                      Voice activity detection: decides where speech starts and
                      stops.
                    required: false
                    properties:
                      - name: threshold
                        type: number
                        description: >-
                          Speech probability a 32 ms window needs to count as
                          speech. Higher ignores more noise.
                        required: false
                      - name: min_speech_ms
                        type: integer
                        description: Speech needed before `vad.speech_started`.
                        required: false
                      - name: min_silence_ms
                        type: integer
                        description: >-
                          Silence that ends a speech segment. No transcript can
                          arrive sooner than this after the caller stops.
                        required: false
                      - name: prefix_padding_ms
                        type: integer
                        description: >-
                          Audio kept from before speech started, so the first
                          syllable isn't cut.
                        required: false
                  - name: stt
                    type: object
                    description: Speech to text.
                    required: false
                    properties:
                      - name: model
                        type: string
                        description: >-
                          Speech to text model: `Hamsa-STT-S4` (default; detects
                          the language itself), `Hamsa-STT-S3` or
                          `Hamsa-STT-English`. `Hamsa-STT-S2` and
                          `Hamsa-STT-S2-deprecated` are still accepted as
                          deprecated names for `Hamsa-STT-S4`.
                        enumValues:
                          - Hamsa-STT-S4
                          - Hamsa-STT-S3
                          - Hamsa-STT-English
                        required: false
                      - name: language
                        type: string
                        description: >-
                          `auto` lets the model detect the language.
                          `Hamsa-STT-S4` always detects it.
                        enumValues:
                          - ar
                          - en
                          - auto
                        required: false
                      - name: eos_enabled
                        type: boolean
                        description: >-
                          End of speech detection: is the caller done, or only
                          pausing?
                        required: false
                      - name: eos_threshold
                        type: number
                        description: >-
                          End of speech probability above which the caller
                          counts as done.
                        required: false
                      - name: gender_detection
                        type: boolean
                        description: >-
                          Adds `gender` to transcripts of 0.7 seconds of audio
                          or more.
                        required: false
                      - name: vad_events
                        type: boolean
                        description: Send `vad.speech_started` and `vad.speech_stopped`.
                        required: false
                      - name: turn
                        type: object
                        description: Turn taking.
                        required: false
                        properties:
                          - name: final_settle_ms
                            type: integer
                            description: >-
                              After end of speech says the caller is done, the
                              silence to wait for before the turn is final. `0`
                              makes it final right away. Capped by
                              `max_timeout_ms`.
                            required: false
                          - name: max_timeout_ms
                            type: integer
                            description: >-
                              When end of speech says the caller isn't done, the
                              turn is made final this long after the `interim`,
                              if the caller doesn't talk again.
                            required: false
                          - name: preflight_timeout_ms
                            type: integer
                            description: >-
                              Wait after the `preflight` before a turn with a
                              long spoken number (at least
                              `digits_preflight_min` digits 0-9 separated by
                              spaces) is made final.
                            required: false
                          - name: digits_interim_timeout_ms
                            type: integer
                            description: >-
                              Wait used instead of `max_timeout_ms` when the
                              caller stopped in the middle of saying a number.
                            required: false
                          - name: digits_preflight_min
                            type: integer
                            description: Digits that make a number "long".
                            required: false
                          - name: backchannel
                            type: string
                            description: >-
                              Short replies such as "mhm", "تمام" or "نعم" are
                              sent with `backchannel: true` and don't end a
                              turn. `while_tts`: only while speech is being
                              generated, or while your client reports `playback:
                              playing`.
                            enumValues:
                              - 'off'
                              - always
                              - while_tts
                            required: false
                  - name: tts
                    type: object
                    description: >-
                      Text to speech defaults. Each `tts` request can override
                      `voice`, `dialect`, `language` and `model`.
                    required: false
                    properties:
                      - name: voice
                        type: string
                        description: >-
                          A voice name of the dialect (any letter case), or a
                          voice ID: one of your cloned voices or a public voice.
                          A voice ID uses its own language and dialect unless
                          the request sets them. Preload a cloned voice before
                          you use it.
                        required: false
                      - name: dialect
                        type: string
                        description: The voice's dialect code.
                        enumValues:
                          - pls
                          - egy
                          - ksa
                          - uae
                          - jor
                          - leb
                          - syr
                          - irq
                          - kuw
                          - qat
                          - bah
                          - oma
                          - msa
                          - ar-sa
                          - en
                        required: false
                      - name: language
                        type: string
                        description: >-
                          `en` for English voices (16 or 24 kHz audio: read
                          `sample_rate` from `tts.started`).
                        enumValues:
                          - ar
                          - en
                        required: false
                      - name: expressiveness
                        type: number
                        description: >-
                          Deprecated. Still accepted (0 to 2, default 1); don't
                          build on it.
                        deprecated: true
                        required: false
                      - name: model
                        type: string
                        description: >-
                          A custom voice model made for your account, if you
                          have one.
                        required: false
                      - name: mulaw
                        type: boolean
                        description: '`true`: 8 kHz µ-law audio (phone audio).'
                        required: false
                      - name: output
                        type: string
                        description: >-
                          `binary`: audio in binary frames. `base64`: audio in
                          `tts.audio` messages.
                        enumValues:
                          - binary
                          - base64
                        required: false
                      - name: dictionary
                        type: object
                        description: >-
                          Pronunciation fixes: `{"word or phrase":
                          "replacement"}`. Whole words only, Arabic diacritics
                          ignored, longest phrase first. Keys up to 200
                          characters.
                        required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: config.update
              description: '`"config.update"`'
              x-parser-schema-id: <anonymous-schema-47>
            config:
              type: object
              description: >-
                Fields you can change during a session. Other fields are fixed
                by the handshake.
              properties:
                vad:
                  type: object
                  description: >-
                    Voice activity detection: decides where speech starts and
                    stops.
                  properties:
                    threshold:
                      type: number
                      minimum: 0.05
                      maximum: 0.99
                      default: 0.5
                      description: >-
                        Speech probability a 32 ms window needs to count as
                        speech. Higher ignores more noise.
                      x-parser-schema-id: <anonymous-schema-50>
                    min_speech_ms:
                      type: integer
                      minimum: 32
                      maximum: 2000
                      default: 100
                      description: Speech needed before `vad.speech_started`.
                      x-parser-schema-id: <anonymous-schema-51>
                    min_silence_ms:
                      type: integer
                      minimum: 64
                      maximum: 5000
                      default: 550
                      description: >-
                        Silence that ends a speech segment. No transcript can
                        arrive sooner than this after the caller stops.
                      x-parser-schema-id: <anonymous-schema-52>
                    prefix_padding_ms:
                      type: integer
                      minimum: 0
                      maximum: 2000
                      default: 250
                      description: >-
                        Audio kept from before speech started, so the first
                        syllable isn't cut.
                      x-parser-schema-id: <anonymous-schema-53>
                  x-parser-schema-id: <anonymous-schema-49>
                stt:
                  type: object
                  description: Speech to text.
                  properties:
                    model:
                      type: string
                      enum:
                        - Hamsa-STT-S4
                        - Hamsa-STT-S3
                        - Hamsa-STT-English
                      description: >-
                        Speech to text model: `Hamsa-STT-S4` (default; detects
                        the language itself), `Hamsa-STT-S3` or
                        `Hamsa-STT-English`. `Hamsa-STT-S2` and
                        `Hamsa-STT-S2-deprecated` are still accepted as
                        deprecated names for `Hamsa-STT-S4`.
                      default: Hamsa-STT-S4
                      x-parser-schema-id: <anonymous-schema-55>
                    language:
                      type: string
                      enum:
                        - ar
                        - en
                        - auto
                      description: >-
                        `auto` lets the model detect the language.
                        `Hamsa-STT-S4` always detects it.
                      default: ar
                      x-parser-schema-id: <anonymous-schema-56>
                    eos_enabled:
                      type: boolean
                      default: true
                      description: >-
                        End of speech detection: is the caller done, or only
                        pausing?
                      x-parser-schema-id: <anonymous-schema-57>
                    eos_threshold:
                      type: number
                      minimum: 0.1
                      maximum: 0.99
                      default: 0.3
                      description: >-
                        End of speech probability above which the caller counts
                        as done.
                      x-parser-schema-id: <anonymous-schema-58>
                    gender_detection:
                      type: boolean
                      default: false
                      description: >-
                        Adds `gender` to transcripts of 0.7 seconds of audio or
                        more.
                      x-parser-schema-id: <anonymous-schema-59>
                    vad_events:
                      type: boolean
                      default: true
                      description: Send `vad.speech_started` and `vad.speech_stopped`.
                      x-parser-schema-id: <anonymous-schema-60>
                    turn:
                      type: object
                      description: Turn taking.
                      properties:
                        final_settle_ms:
                          type: integer
                          minimum: 0
                          maximum: 5000
                          default: 400
                          description: >-
                            After end of speech says the caller is done, the
                            silence to wait for before the turn is final. `0`
                            makes it final right away. Capped by
                            `max_timeout_ms`.
                          x-parser-schema-id: <anonymous-schema-62>
                        max_timeout_ms:
                          type: integer
                          minimum: 0
                          maximum: 10000
                          default: 700
                          description: >-
                            When end of speech says the caller isn't done, the
                            turn is made final this long after the `interim`, if
                            the caller doesn't talk again.
                          x-parser-schema-id: <anonymous-schema-63>
                        preflight_timeout_ms:
                          type: integer
                          minimum: 0
                          maximum: 10000
                          default: 2000
                          description: >-
                            Wait after the `preflight` before a turn with a long
                            spoken number (at least `digits_preflight_min`
                            digits 0-9 separated by spaces) is made final.
                          x-parser-schema-id: <anonymous-schema-64>
                        digits_interim_timeout_ms:
                          type: integer
                          minimum: 0
                          maximum: 10000
                          default: 3000
                          description: >-
                            Wait used instead of `max_timeout_ms` when the
                            caller stopped in the middle of saying a number.
                          x-parser-schema-id: <anonymous-schema-65>
                        digits_preflight_min:
                          type: integer
                          minimum: 1
                          maximum: 30
                          default: 6
                          description: Digits that make a number "long".
                          x-parser-schema-id: <anonymous-schema-66>
                        backchannel:
                          type: string
                          enum:
                            - 'off'
                            - always
                            - while_tts
                          description: >-
                            Short replies such as "mhm", "تمام" or "نعم" are
                            sent with `backchannel: true` and don't end a turn.
                            `while_tts`: only while speech is being generated,
                            or while your client reports `playback: playing`.
                          default: while_tts
                          x-parser-schema-id: <anonymous-schema-67>
                      x-parser-schema-id: <anonymous-schema-61>
                  x-parser-schema-id: <anonymous-schema-54>
                tts:
                  type: object
                  description: >-
                    Text to speech defaults. Each `tts` request can override
                    `voice`, `dialect`, `language` and `model`.
                  properties:
                    voice:
                      type: string
                      minLength: 1
                      maxLength: 128
                      default: Ali
                      description: >-
                        A voice name of the dialect (any letter case), or a
                        voice ID: one of your cloned voices or a public voice. A
                        voice ID uses its own language and dialect unless the
                        request sets them. Preload a cloned voice before you use
                        it.
                      x-parser-schema-id: <anonymous-schema-69>
                    dialect:
                      type: string
                      enum:
                        - pls
                        - egy
                        - ksa
                        - uae
                        - jor
                        - leb
                        - syr
                        - irq
                        - kuw
                        - qat
                        - bah
                        - oma
                        - msa
                        - ar-sa
                        - en
                      default: pls
                      description: The voice's dialect code.
                      x-parser-schema-id: <anonymous-schema-70>
                    language:
                      type: string
                      enum:
                        - ar
                        - en
                      description: >-
                        `en` for English voices (16 or 24 kHz audio: read
                        `sample_rate` from `tts.started`).
                      default: ar
                      x-parser-schema-id: <anonymous-schema-71>
                    expressiveness:
                      type: number
                      minimum: 0
                      maximum: 2
                      default: 1
                      description: >-
                        Deprecated. Still accepted (0 to 2, default 1); don't
                        build on it.
                      deprecated: true
                      x-parser-schema-id: <anonymous-schema-72>
                    model:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: >-
                        A custom voice model made for your account, if you have
                        one.
                      x-parser-schema-id: <anonymous-schema-73>
                    mulaw:
                      type: boolean
                      default: false
                      description: '`true`: 8 kHz µ-law audio (phone audio).'
                      x-parser-schema-id: <anonymous-schema-74>
                    output:
                      type: string
                      enum:
                        - binary
                        - base64
                      description: >-
                        `binary`: audio in binary frames. `base64`: audio in
                        `tts.audio` messages.
                      default: binary
                      x-parser-schema-id: <anonymous-schema-75>
                    dictionary:
                      type: object
                      additionalProperties:
                        type: string
                        maxLength: 500
                        x-parser-schema-id: <anonymous-schema-77>
                      description: >-
                        Pronunciation fixes: `{"word or phrase":
                        "replacement"}`. Whole words only, Arabic diacritics
                        ignored, longest phrase first. Keys up to 200
                        characters.
                      x-parser-schema-id: <anonymous-schema-76>
                  x-parser-schema-id: <anonymous-schema-68>
              x-parser-schema-id: <anonymous-schema-48>
          required:
            - type
            - config
          x-parser-schema-id: <anonymous-schema-46>
        title: config.update
        description: Change settings during the session.
        example: |-
          {
            "type": "config.update",
            "config": {
              "vad": {
                "min_silence_ms": 350
              },
              "stt": {
                "turn": {
                  "final_settle_ms": 200
                }
              }
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: configUpdate
      - &ref_18
        id: tts
        contentType: application/json
        payload:
          - name: tts
            description: Speak a complete text.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts"`'
                required: true
              - name: id
                type: string
                description: >-
                  Your ID for the request, echoed in its replies. Default:
                  `tts_1`, `tts_2`, ...
                required: false
              - name: text
                type: string
                description: The text to speak.
                required: true
              - name: voice
                type: string
                description: >-
                  A voice name of the dialect (any letter case), or a voice ID:
                  one of your cloned voices or a public voice. A voice ID uses
                  its own language and dialect unless the request sets them.
                  Preload a cloned voice before you use it.
                required: false
              - name: dialect
                type: string
                description: The voice's dialect code.
                enumValues:
                  - pls
                  - egy
                  - ksa
                  - uae
                  - jor
                  - leb
                  - syr
                  - irq
                  - kuw
                  - qat
                  - bah
                  - oma
                  - msa
                  - ar-sa
                  - en
                required: false
              - name: language
                type: string
                description: >-
                  `en` for English voices (16 or 24 kHz audio: read
                  `sample_rate` from `tts.started`).
                enumValues:
                  - ar
                  - en
                required: false
              - name: expressiveness
                type: number
                description: >-
                  Deprecated. Still accepted (0 to 2, default 1); don't build on
                  it.
                deprecated: true
                required: false
              - name: model
                type: string
                description: A custom voice model made for your account, if you have one.
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts
              description: '`"tts"`'
              x-parser-schema-id: <anonymous-schema-79>
            id:
              type: string
              minLength: 1
              maxLength: 64
              description: >-
                Your ID for the request, echoed in its replies. Default:
                `tts_1`, `tts_2`, ...
              x-parser-schema-id: <anonymous-schema-80>
            text:
              type: string
              minLength: 1
              maxLength: 5000
              description: The text to speak.
              x-parser-schema-id: <anonymous-schema-81>
            voice:
              type: string
              minLength: 1
              maxLength: 128
              default: Ali
              description: >-
                A voice name of the dialect (any letter case), or a voice ID:
                one of your cloned voices or a public voice. A voice ID uses its
                own language and dialect unless the request sets them. Preload a
                cloned voice before you use it.
              x-parser-schema-id: <anonymous-schema-82>
            dialect:
              type: string
              enum:
                - pls
                - egy
                - ksa
                - uae
                - jor
                - leb
                - syr
                - irq
                - kuw
                - qat
                - bah
                - oma
                - msa
                - ar-sa
                - en
              default: pls
              description: The voice's dialect code.
              x-parser-schema-id: <anonymous-schema-83>
            language:
              type: string
              enum:
                - ar
                - en
              description: >-
                `en` for English voices (16 or 24 kHz audio: read `sample_rate`
                from `tts.started`).
              default: ar
              x-parser-schema-id: <anonymous-schema-84>
            expressiveness:
              type: number
              minimum: 0
              maximum: 2
              default: 1
              description: >-
                Deprecated. Still accepted (0 to 2, default 1); don't build on
                it.
              deprecated: true
              x-parser-schema-id: <anonymous-schema-85>
            model:
              type: string
              minLength: 1
              maxLength: 64
              description: A custom voice model made for your account, if you have one.
              x-parser-schema-id: <anonymous-schema-86>
          required:
            - type
            - text
          x-parser-schema-id: <anonymous-schema-78>
        title: Tts
        description: Speak a complete text.
        example: |-
          {
            "type": "tts",
            "id": "greeting",
            "text": "أهلا وسهلا، كيف يمكنني مساعدتك؟"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: tts
      - &ref_19
        id: ttsAppend
        contentType: application/json
        payload:
          - name: tts.append
            description: >-
              Add text to a streamed request, for example as an LLM writes it.
              The first `tts.append` with an `id` starts the request.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.append"`'
                required: true
              - name: id
                type: string
                description: The streamed request's ID.
                required: true
              - name: text
                type: string
                description: >-
                  The next piece of text. Words are spoken once they are
                  complete.
                required: true
              - name: voice
                type: string
                description: >-
                  A voice name of the dialect (any letter case), or a voice ID:
                  one of your cloned voices or a public voice. A voice ID uses
                  its own language and dialect unless the request sets them.
                  Preload a cloned voice before you use it.
                required: false
              - name: dialect
                type: string
                description: The voice's dialect code.
                enumValues:
                  - pls
                  - egy
                  - ksa
                  - uae
                  - jor
                  - leb
                  - syr
                  - irq
                  - kuw
                  - qat
                  - bah
                  - oma
                  - msa
                  - ar-sa
                  - en
                required: false
              - name: language
                type: string
                description: >-
                  `en` for English voices (16 or 24 kHz audio: read
                  `sample_rate` from `tts.started`).
                enumValues:
                  - ar
                  - en
                required: false
              - name: expressiveness
                type: number
                description: >-
                  Deprecated. Still accepted (0 to 2, default 1); don't build on
                  it.
                deprecated: true
                required: false
              - name: model
                type: string
                description: A custom voice model made for your account, if you have one.
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.append
              description: '`"tts.append"`'
              x-parser-schema-id: <anonymous-schema-88>
            id:
              type: string
              minLength: 1
              maxLength: 64
              description: The streamed request's ID.
              x-parser-schema-id: <anonymous-schema-89>
            text:
              type: string
              maxLength: 5000
              description: The next piece of text. Words are spoken once they are complete.
              x-parser-schema-id: <anonymous-schema-90>
            voice:
              type: string
              minLength: 1
              maxLength: 128
              default: Ali
              description: >-
                A voice name of the dialect (any letter case), or a voice ID:
                one of your cloned voices or a public voice. A voice ID uses its
                own language and dialect unless the request sets them. Preload a
                cloned voice before you use it.
              x-parser-schema-id: <anonymous-schema-91>
            dialect:
              type: string
              enum:
                - pls
                - egy
                - ksa
                - uae
                - jor
                - leb
                - syr
                - irq
                - kuw
                - qat
                - bah
                - oma
                - msa
                - ar-sa
                - en
              default: pls
              description: The voice's dialect code.
              x-parser-schema-id: <anonymous-schema-92>
            language:
              type: string
              enum:
                - ar
                - en
              description: >-
                `en` for English voices (16 or 24 kHz audio: read `sample_rate`
                from `tts.started`).
              default: ar
              x-parser-schema-id: <anonymous-schema-93>
            expressiveness:
              type: number
              minimum: 0
              maximum: 2
              default: 1
              description: >-
                Deprecated. Still accepted (0 to 2, default 1); don't build on
                it.
              deprecated: true
              x-parser-schema-id: <anonymous-schema-94>
            model:
              type: string
              minLength: 1
              maxLength: 64
              description: A custom voice model made for your account, if you have one.
              x-parser-schema-id: <anonymous-schema-95>
          required:
            - type
            - id
            - text
          description: >-
            Voice settings are read from the first `tts.append` of a request.
            After a request has finished or been stopped, the same `id` starts a
            new request: use a new `id` for each reply.
          x-parser-schema-id: <anonymous-schema-87>
        title: tts.append
        description: >-
          Add text to a streamed request, for example as an LLM writes it. The
          first `tts.append` with an `id` starts the request.
        example: |-
          {
            "type": "tts.append",
            "id": "reply-1",
            "text": "أهلا وسهلا، "
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsAppend
      - &ref_20
        id: ttsEnd
        contentType: application/json
        payload:
          - name: tts.end
            description: 'No more text for a streamed request: speak what is left.'
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.end"`'
                required: true
              - name: id
                type: string
                description: The streamed request's ID.
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.end
              description: '`"tts.end"`'
              x-parser-schema-id: <anonymous-schema-97>
            id:
              type: string
              minLength: 1
              maxLength: 64
              description: The streamed request's ID.
              x-parser-schema-id: <anonymous-schema-98>
          required:
            - type
            - id
          x-parser-schema-id: <anonymous-schema-96>
        title: tts.end
        description: 'No more text for a streamed request: speak what is left.'
        example: |-
          {
            "type": "tts.end",
            "id": "reply-1"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsEnd
      - &ref_21
        id: ttsCancel
        contentType: application/json
        payload:
          - name: tts.cancel
            description: >-
              Stop a request. Without `id`, stops the current request and every
              waiting one.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.cancel"`'
                required: true
              - name: id
                type: string
                description: The request to stop.
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.cancel
              description: '`"tts.cancel"`'
              x-parser-schema-id: <anonymous-schema-100>
            id:
              type: string
              minLength: 1
              maxLength: 64
              description: The request to stop.
              x-parser-schema-id: <anonymous-schema-101>
          required:
            - type
          x-parser-schema-id: <anonymous-schema-99>
        title: tts.cancel
        description: >-
          Stop a request. Without `id`, stops the current request and every
          waiting one.
        example: |-
          {
            "type": "tts.cancel",
            "id": "reply-1"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsCancel
      - &ref_22
        id: sttFlush
        contentType: application/json
        payload:
          - name: stt.flush
            description: >-
              End the caller's turn now (for example when a push-to-talk button
              is released): the current speech is transcribed, then the turn is
              made `final` with reason `flush`.
            type: object
            properties:
              - name: type
                type: string
                description: '`"stt.flush"`'
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: stt.flush
              description: '`"stt.flush"`'
              x-parser-schema-id: <anonymous-schema-103>
          required:
            - type
          x-parser-schema-id: <anonymous-schema-102>
        title: stt.flush
        description: >-
          End the caller's turn now (for example when a push-to-talk button is
          released): the current speech is transcribed, then the turn is made
          `final` with reason `flush`.
        example: |-
          {
            "type": "stt.flush"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: sttFlush
      - &ref_23
        id: playback
        contentType: application/json
        payload:
          - name: playback
            description: >-
              Tell the server whether your app is still playing speech, so short
              replies are treated as backchannels while it plays.
            type: object
            properties:
              - name: type
                type: string
                description: '`"playback"`'
                required: true
              - name: state
                type: string
                enumValues:
                  - playing
                  - idle
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: playback
              description: '`"playback"`'
              x-parser-schema-id: <anonymous-schema-105>
            state:
              type: string
              enum:
                - playing
                - idle
              x-parser-schema-id: <anonymous-schema-106>
          required:
            - type
            - state
          x-parser-schema-id: <anonymous-schema-104>
        title: Playback
        description: >-
          Tell the server whether your app is still playing speech, so short
          replies are treated as backchannels while it plays.
        example: |-
          {
            "type": "playback",
            "state": "playing"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: playback
      - &ref_24
        id: ping
        contentType: application/json
        payload:
          - name: ping
            description: >-
              Check the connection, or keep a quiet session open. The reply is a
              `pong` with your `ts`, or the server time if you sent none.
            type: object
            properties:
              - name: type
                type: string
                description: '`"ping"`'
                required: true
              - name: ts
                type: number
                description: Any number, echoed back.
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: ping
              description: '`"ping"`'
              x-parser-schema-id: <anonymous-schema-108>
            ts:
              type: number
              description: Any number, echoed back.
              x-parser-schema-id: <anonymous-schema-109>
          required:
            - type
          x-parser-schema-id: <anonymous-schema-107>
        title: Ping
        description: >-
          Check the connection, or keep a quiet session open. The reply is a
          `pong` with your `ts`, or the server time if you sent none.
        example: |-
          {
            "type": "ping",
            "ts": 1760000000000
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ping
      - &ref_25
        id: close
        contentType: application/json
        payload:
          - name: close
            description: End the session. The server closes the socket with code 1000.
            type: object
            properties:
              - name: type
                type: string
                description: '`"close"`'
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: close
              description: '`"close"`'
              x-parser-schema-id: <anonymous-schema-111>
          required:
            - type
          x-parser-schema-id: <anonymous-schema-110>
        title: Close
        description: End the session. The server closes the socket with code 1000.
        example: |-
          {
            "type": "close"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: close
    bindings: []
    extensions: &ref_12
      - id: x-parser-unique-object-id
        value: realtime
  - &ref_14
    id: receiveFromHamsa
    title: Receive
    description: Messages Hamsa sends
    type: send
    messages:
      - &ref_26
        id: handshakeAck
        contentType: application/json
        payload:
          - name: handshake_ack
            description: The session is open. Start sending audio and requests.
            type: object
            properties:
              - name: type
                type: string
                description: '`"handshake_ack"`'
                required: true
              - name: session_id
                type: string
                required: true
              - name: config
                type: object
                description: >-
                  The session's settings after defaults are applied.
                  `turn.custom_backchannel_phrases` and `tts.dictionary_entries`
                  are counts.
                required: true
                properties:
                  - name: audio
                    type: object
                    required: false
                  - name: vad
                    type: object
                    required: false
                  - name: stt
                    type: object
                    required: false
                  - name: tts
                    type: object
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: handshake_ack
              description: '`"handshake_ack"`'
              x-parser-schema-id: <anonymous-schema-113>
            session_id:
              type: string
              format: uuid
              x-parser-schema-id: <anonymous-schema-114>
            config:
              type: object
              description: >-
                The session's settings after defaults are applied.
                `turn.custom_backchannel_phrases` and `tts.dictionary_entries`
                are counts.
              properties:
                audio:
                  type: object
                  x-parser-schema-id: <anonymous-schema-116>
                vad:
                  type: object
                  x-parser-schema-id: <anonymous-schema-117>
                stt:
                  type: object
                  x-parser-schema-id: <anonymous-schema-118>
                tts:
                  type: object
                  x-parser-schema-id: <anonymous-schema-119>
              x-parser-schema-id: <anonymous-schema-115>
          required:
            - type
            - session_id
            - config
          x-parser-schema-id: <anonymous-schema-112>
        title: handshake_ack
        description: The session is open. Start sending audio and requests.
        example: |-
          {
            "type": "handshake_ack",
            "session_id": "6f1c2b8e-3a4d-4f0e-9b7a-1c2d3e4f5a6b",
            "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": true,
                "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",
                  "custom_backchannel_phrases": 0
                }
              },
              "tts": {
                "voice": "Amjad",
                "dialect": "pls",
                "language": "ar",
                "model": null,
                "mulaw": false,
                "output": "binary",
                "dictionary_entries": 0
              }
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: handshakeAck
      - &ref_27
        id: configUpdated
        contentType: application/json
        payload:
          - name: config.updated
            description: The settings after a `config.update`.
            type: object
            properties:
              - name: type
                type: string
                description: '`"config.updated"`'
                required: true
              - name: config
                type: object
                description: >-
                  The session's settings after defaults are applied.
                  `turn.custom_backchannel_phrases` and `tts.dictionary_entries`
                  are counts.
                required: true
                properties:
                  - name: audio
                    type: object
                    required: false
                  - name: vad
                    type: object
                    required: false
                  - name: stt
                    type: object
                    required: false
                  - name: tts
                    type: object
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: config.updated
              description: '`"config.updated"`'
              x-parser-schema-id: <anonymous-schema-121>
            config:
              type: object
              description: >-
                The session's settings after defaults are applied.
                `turn.custom_backchannel_phrases` and `tts.dictionary_entries`
                are counts.
              properties:
                audio:
                  type: object
                  x-parser-schema-id: <anonymous-schema-123>
                vad:
                  type: object
                  x-parser-schema-id: <anonymous-schema-124>
                stt:
                  type: object
                  x-parser-schema-id: <anonymous-schema-125>
                tts:
                  type: object
                  x-parser-schema-id: <anonymous-schema-126>
              x-parser-schema-id: <anonymous-schema-122>
          required:
            - type
            - config
          x-parser-schema-id: <anonymous-schema-120>
        title: config.updated
        description: The settings after a `config.update`.
        example: |-
          {
            "type": "config.updated",
            "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": true,
                "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",
                  "custom_backchannel_phrases": 0
                }
              },
              "tts": {
                "voice": "Amjad",
                "dialect": "pls",
                "language": "ar",
                "model": null,
                "mulaw": false,
                "output": "binary",
                "dictionary_entries": 0
              }
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: configUpdated
      - &ref_28
        id: speechStarted
        contentType: application/json
        payload:
          - name: vad.speech_started
            description: >-
              The caller started speaking. Use it to stop your agent talking
              (barge-in).
            type: object
            properties:
              - name: type
                type: string
                description: '`"vad.speech_started"`'
                required: true
              - name: ts
                type: integer
                description: Server time (Unix milliseconds).
                required: false
              - name: offset_ms
                type: integer
                description: >-
                  Where speech started or stopped, in the audio you sent this
                  session.
                required: false
              - name: detect_ms
                type: integer
                description: >-
                  Audio the detector needed after that point to decide
                  (`min_speech_ms` or `min_silence_ms`, rounded up to 32 ms).
                required: false
              - name: server_lag_ms
                type: integer
                description: >-
                  Time between the deciding audio arriving and the event being
                  sent. Usually 0 to 2.
                required: false
              - name: backlog_ms
                type: integer
                description: Audio received but not yet analysed. Usually under 32.
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: vad.speech_started
              description: '`"vad.speech_started"`'
              x-parser-schema-id: <anonymous-schema-128>
            ts:
              type: integer
              description: Server time (Unix milliseconds).
              x-parser-schema-id: <anonymous-schema-129>
            offset_ms:
              type: integer
              description: >-
                Where speech started or stopped, in the audio you sent this
                session.
              x-parser-schema-id: <anonymous-schema-130>
            detect_ms:
              type: integer
              description: >-
                Audio the detector needed after that point to decide
                (`min_speech_ms` or `min_silence_ms`, rounded up to 32 ms).
              x-parser-schema-id: <anonymous-schema-131>
            server_lag_ms:
              type: integer
              description: >-
                Time between the deciding audio arriving and the event being
                sent. Usually 0 to 2.
              x-parser-schema-id: <anonymous-schema-132>
            backlog_ms:
              type: integer
              description: Audio received but not yet analysed. Usually under 32.
              x-parser-schema-id: <anonymous-schema-133>
          required:
            - type
          x-parser-schema-id: <anonymous-schema-127>
        title: vad.speech_started
        description: >-
          The caller started speaking. Use it to stop your agent talking
          (barge-in).
        example: |-
          {
            "type": "vad.speech_started",
            "ts": 1760000000000,
            "offset_ms": 768,
            "detect_ms": 128,
            "server_lag_ms": 1,
            "backlog_ms": 0
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: speechStarted
      - &ref_29
        id: speechStopped
        contentType: application/json
        payload:
          - name: vad.speech_stopped
            description: The caller stopped speaking; the segment is being transcribed.
            type: object
            properties:
              - name: type
                type: string
                description: '`"vad.speech_stopped"`'
                required: true
              - name: ts
                type: integer
                description: Server time (Unix milliseconds).
                required: false
              - name: offset_ms
                type: integer
                description: >-
                  Where speech started or stopped, in the audio you sent this
                  session.
                required: false
              - name: detect_ms
                type: integer
                description: >-
                  Audio the detector needed after that point to decide
                  (`min_speech_ms` or `min_silence_ms`, rounded up to 32 ms).
                required: false
              - name: server_lag_ms
                type: integer
                description: >-
                  Time between the deciding audio arriving and the event being
                  sent. Usually 0 to 2.
                required: false
              - name: backlog_ms
                type: integer
                description: Audio received but not yet analysed. Usually under 32.
                required: false
              - name: audio_ms
                type: integer
                description: >-
                  Length of the segment sent for transcription, including
                  `prefix_padding_ms` before the speech and the `min_silence_ms`
                  after it.
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: vad.speech_stopped
              description: '`"vad.speech_stopped"`'
              x-parser-schema-id: <anonymous-schema-135>
            ts:
              type: integer
              description: Server time (Unix milliseconds).
              x-parser-schema-id: <anonymous-schema-136>
            offset_ms:
              type: integer
              description: >-
                Where speech started or stopped, in the audio you sent this
                session.
              x-parser-schema-id: <anonymous-schema-137>
            detect_ms:
              type: integer
              description: >-
                Audio the detector needed after that point to decide
                (`min_speech_ms` or `min_silence_ms`, rounded up to 32 ms).
              x-parser-schema-id: <anonymous-schema-138>
            server_lag_ms:
              type: integer
              description: >-
                Time between the deciding audio arriving and the event being
                sent. Usually 0 to 2.
              x-parser-schema-id: <anonymous-schema-139>
            backlog_ms:
              type: integer
              description: Audio received but not yet analysed. Usually under 32.
              x-parser-schema-id: <anonymous-schema-140>
            audio_ms:
              type: integer
              description: >-
                Length of the segment sent for transcription, including
                `prefix_padding_ms` before the speech and the `min_silence_ms`
                after it.
              x-parser-schema-id: <anonymous-schema-141>
          required:
            - type
          x-parser-schema-id: <anonymous-schema-134>
        title: vad.speech_stopped
        description: The caller stopped speaking; the segment is being transcribed.
        example: |-
          {
            "type": "vad.speech_stopped",
            "ts": 1760000002080,
            "audio_ms": 2458,
            "offset_ms": 2400,
            "detect_ms": 576,
            "server_lag_ms": 1,
            "backlog_ms": 0
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: speechStopped
      - &ref_30
        id: transcript
        contentType: application/json
        payload:
          - name: transcript
            description: >-
              What the caller said. `interim` and `preflight` can still change;
              `final` ends the turn.
            type: object
            properties:
              - name: type
                type: string
                description: '`"transcript"`'
                required: true
              - name: turn_id
                type: integer
                description: >-
                  The turn this text belongs to, from 1. Goes up by one after
                  each `final`.
                required: true
              - name: kind
                type: string
                description: >-
                  `interim`: the caller isn't done. `preflight`: the caller
                  looks done; this becomes `final` unless they keep talking.
                  `final`: the turn is over.
                enumValues:
                  - interim
                  - preflight
                  - final
                required: true
              - name: is_final
                type: boolean
                description: '`true` for `final`.'
                required: true
              - name: text
                type: string
                required: true
              - name: language
                type: string
                description: The `stt.language` setting.
                required: false
              - name: eos
                type: &ref_0
                  - object
                  - 'null'
                description: End of speech result; `null` when it is off.
                required: false
                properties:
                  - name: prediction
                    type: boolean
                    required: false
                  - name: probability
                    type: &ref_1
                      - number
                      - 'null'
                    required: false
              - name: gender
                type: &ref_2
                  - string
                  - 'null'
                description: >-
                  `null` when gender detection is off or the audio is under 0.7
                  seconds.
                enumValues:
                  - Male
                  - Female
                required: false
              - name: speaker
                type: &ref_3
                  - object
                  - 'null'
                description: >-
                  `null` when speaker identification is off, or no voice sample
                  could be taken.
                required: false
                properties:
                  - name: id
                    type: string
                    description: '`Speaker1`, `Speaker2`, ...'
                    required: false
                  - name: confidence
                    type: number
                    required: false
                  - name: is_new
                    type: boolean
                    description: First time this speaker is heard.
                    required: false
              - name: backchannel
                type: boolean
                description: '`true` for a short reply that didn''t end the turn.'
                required: false
              - name: audio_ms
                type: integer
                description: Audio transcribed (in `enhanced` mode, the whole turn so far).
                required: false
              - name: stt_ms
                type: integer
                description: Time the transcription took.
                required: false
              - name: commit
                type: object
                description: '`final` only, in `enhanced` mode: why the turn ended.'
                required: false
                properties:
                  - name: reason
                    type: string
                    enumValues:
                      - final_settle
                      - eos
                      - interim_timeout
                      - preflight_timeout
                      - flush
                      - max_audio
                    required: false
                  - name: wait_ms
                    type: integer
                    description: Time waited after the transcription before the turn ended.
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: transcript
              description: '`"transcript"`'
              x-parser-schema-id: <anonymous-schema-143>
            turn_id:
              type: integer
              description: >-
                The turn this text belongs to, from 1. Goes up by one after each
                `final`.
              x-parser-schema-id: <anonymous-schema-144>
            kind:
              type: string
              enum:
                - interim
                - preflight
                - final
              description: >-
                `interim`: the caller isn't done. `preflight`: the caller looks
                done; this becomes `final` unless they keep talking. `final`:
                the turn is over.
              x-parser-schema-id: <anonymous-schema-145>
            is_final:
              type: boolean
              description: '`true` for `final`.'
              x-parser-schema-id: <anonymous-schema-146>
            text:
              type: string
              x-parser-schema-id: <anonymous-schema-147>
            language:
              type: string
              description: The `stt.language` setting.
              x-parser-schema-id: <anonymous-schema-148>
            eos:
              type: *ref_0
              description: End of speech result; `null` when it is off.
              properties:
                prediction:
                  type: boolean
                  x-parser-schema-id: <anonymous-schema-150>
                probability:
                  type: *ref_1
                  x-parser-schema-id: <anonymous-schema-151>
              x-parser-schema-id: <anonymous-schema-149>
            gender:
              type: *ref_2
              enum:
                - Male
                - Female
                - null
              description: >-
                `null` when gender detection is off or the audio is under 0.7
                seconds.
              x-parser-schema-id: <anonymous-schema-152>
            speaker:
              type: *ref_3
              description: >-
                `null` when speaker identification is off, or no voice sample
                could be taken.
              properties:
                id:
                  type: string
                  description: '`Speaker1`, `Speaker2`, ...'
                  x-parser-schema-id: <anonymous-schema-154>
                confidence:
                  type: number
                  x-parser-schema-id: <anonymous-schema-155>
                is_new:
                  type: boolean
                  description: First time this speaker is heard.
                  x-parser-schema-id: <anonymous-schema-156>
              x-parser-schema-id: <anonymous-schema-153>
            backchannel:
              type: boolean
              description: '`true` for a short reply that didn''t end the turn.'
              x-parser-schema-id: <anonymous-schema-157>
            audio_ms:
              type: integer
              description: Audio transcribed (in `enhanced` mode, the whole turn so far).
              x-parser-schema-id: <anonymous-schema-158>
            stt_ms:
              type: integer
              description: Time the transcription took.
              x-parser-schema-id: <anonymous-schema-159>
            commit:
              type: object
              description: '`final` only, in `enhanced` mode: why the turn ended.'
              properties:
                reason:
                  type: string
                  enum:
                    - final_settle
                    - eos
                    - interim_timeout
                    - preflight_timeout
                    - flush
                    - max_audio
                  x-parser-schema-id: <anonymous-schema-161>
                wait_ms:
                  type: integer
                  description: Time waited after the transcription before the turn ended.
                  x-parser-schema-id: <anonymous-schema-162>
              x-parser-schema-id: <anonymous-schema-160>
          required:
            - type
            - turn_id
            - kind
            - is_final
            - text
          x-parser-schema-id: <anonymous-schema-142>
        title: Transcript
        description: >-
          What the caller said. `interim` and `preflight` can still change;
          `final` ends the turn.
        example: |-
          {
            "type": "transcript",
            "turn_id": 3,
            "kind": "interim",
            "is_final": false,
            "text": "رقم حسابي هو",
            "language": "ar",
            "eos": {
              "prediction": false,
              "probability": 0.12
            },
            "gender": "Male",
            "speaker": null,
            "backchannel": false,
            "audio_ms": 1450,
            "stt_ms": 131
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: transcript
      - &ref_31
        id: ttsStarted
        contentType: application/json
        payload:
          - name: tts.started
            description: A request started. Its audio follows, in this format.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.started"`'
                required: true
              - name: id
                type: string
                required: true
              - name: encoding
                type: string
                enumValues:
                  - pcm16
                  - mulaw
                required: true
              - name: sample_rate
                type: integer
                description: >-
                  16000 for Arabic, 16000 or 24000 for English, 8000 with
                  `mulaw`. Always play at this rate.
                enumValues:
                  - 8000
                  - 16000
                  - 24000
                required: true
              - name: channels
                type: integer
                description: 1
                required: true
              - name: output
                type: string
                enumValues:
                  - binary
                  - base64
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.started
              description: '`"tts.started"`'
              x-parser-schema-id: <anonymous-schema-164>
            id:
              type: string
              x-parser-schema-id: <anonymous-schema-165>
            encoding:
              type: string
              enum:
                - pcm16
                - mulaw
              x-parser-schema-id: <anonymous-schema-166>
            sample_rate:
              type: integer
              enum:
                - 8000
                - 16000
                - 24000
              description: >-
                16000 for Arabic, 16000 or 24000 for English, 8000 with `mulaw`.
                Always play at this rate.
              x-parser-schema-id: <anonymous-schema-167>
            channels:
              type: integer
              const: 1
              x-parser-schema-id: <anonymous-schema-168>
            output:
              type: string
              enum:
                - binary
                - base64
              x-parser-schema-id: <anonymous-schema-169>
          required:
            - type
            - id
            - encoding
            - sample_rate
            - channels
            - output
          x-parser-schema-id: <anonymous-schema-163>
        title: tts.started
        description: A request started. Its audio follows, in this format.
        example: |-
          {
            "type": "tts.started",
            "id": "greeting",
            "encoding": "pcm16",
            "sample_rate": 16000,
            "channels": 1,
            "output": "binary"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsStarted
      - &ref_32
        id: outputAudio
        contentType: application/octet-stream
        payload:
          - type: string
            format: binary
            description: Speech audio for the request announced by the last `tts.started`.
            x-parser-schema-id: <anonymous-schema-170>
            name: Audio (binary)
        headers: []
        jsonPayloadSchema:
          type: string
          format: binary
          description: >-
            Raw audio in the `tts.started` format: PCM16 little-endian mono, or
            8-bit µ-law.
          x-parser-schema-id: <anonymous-schema-170>
        title: Audio (binary)
        description: Speech audio for the request announced by the last `tts.started`.
        example: '{}'
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: outputAudio
      - &ref_33
        id: ttsAudio
        contentType: application/json
        payload:
          - name: tts.audio
            description: Speech audio as base64, when `tts.output` is `base64`.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.audio"`'
                required: true
              - name: id
                type: string
                required: true
              - name: seq
                type: integer
                description: Order of the piece, from 0.
                required: true
              - name: data
                type: string
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.audio
              description: '`"tts.audio"`'
              x-parser-schema-id: <anonymous-schema-172>
            id:
              type: string
              x-parser-schema-id: <anonymous-schema-173>
            seq:
              type: integer
              description: Order of the piece, from 0.
              x-parser-schema-id: <anonymous-schema-174>
            data:
              type: string
              contentEncoding: base64
              x-parser-schema-id: <anonymous-schema-175>
          required:
            - type
            - id
            - seq
            - data
          x-parser-schema-id: <anonymous-schema-171>
        title: tts.audio
        description: Speech audio as base64, when `tts.output` is `base64`.
        example: |-
          {
            "type": "tts.audio",
            "id": "greeting",
            "seq": 0,
            "data": "AAABAAIAAwA="
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsAudio
      - &ref_34
        id: ttsDone
        contentType: application/json
        payload:
          - name: tts.done
            description: All of a request's audio was sent.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.done"`'
                required: true
              - name: id
                type: string
                required: true
              - name: audio_ms
                type: integer
                description: Length of the audio.
                required: true
              - name: characters
                type: integer
                description: Length of your text.
                required: true
              - name: timing
                type: object
                description: >-
                  Server-side timing in milliseconds. `null` when it doesn't
                  apply.
                required: true
                properties:
                  - name: queue_ms
                    type: &ref_4
                      - integer
                      - 'null'
                    description: >-
                      From the request arriving to it starting: waiting behind
                      earlier requests of this session.
                    required: false
                  - name: text_wait_ms
                    type: &ref_5
                      - integer
                      - 'null'
                    description: >-
                      Streamed text: from the request starting to its first
                      piece of text being ready.
                    required: false
                  - name: upstream_ttfb_ms
                    type: &ref_6
                      - integer
                      - 'null'
                    description: >-
                      From the first piece being ready to its first audio: the
                      voice model's time.
                    required: false
                  - name: first_audio_ms
                    type: &ref_7
                      - integer
                      - 'null'
                    description: >-
                      Request received to first audio sent. Your own time to
                      first audio minus this is network time.
                    required: false
                  - name: total_ms
                    type: integer
                    description: Request received to last audio sent.
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.done
              description: '`"tts.done"`'
              x-parser-schema-id: <anonymous-schema-177>
            id:
              type: string
              x-parser-schema-id: <anonymous-schema-178>
            audio_ms:
              type: integer
              description: Length of the audio.
              x-parser-schema-id: <anonymous-schema-179>
            characters:
              type: integer
              description: Length of your text.
              x-parser-schema-id: <anonymous-schema-180>
            timing:
              type: object
              description: >-
                Server-side timing in milliseconds. `null` when it doesn't
                apply.
              properties:
                queue_ms:
                  type: *ref_4
                  description: >-
                    From the request arriving to it starting: waiting behind
                    earlier requests of this session.
                  x-parser-schema-id: <anonymous-schema-182>
                text_wait_ms:
                  type: *ref_5
                  description: >-
                    Streamed text: from the request starting to its first piece
                    of text being ready.
                  x-parser-schema-id: <anonymous-schema-183>
                upstream_ttfb_ms:
                  type: *ref_6
                  description: >-
                    From the first piece being ready to its first audio: the
                    voice model's time.
                  x-parser-schema-id: <anonymous-schema-184>
                first_audio_ms:
                  type: *ref_7
                  description: >-
                    Request received to first audio sent. Your own time to first
                    audio minus this is network time.
                  x-parser-schema-id: <anonymous-schema-185>
                total_ms:
                  type: integer
                  description: Request received to last audio sent.
                  x-parser-schema-id: <anonymous-schema-186>
              additionalProperties: true
              x-parser-schema-id: <anonymous-schema-181>
          required:
            - type
            - id
            - audio_ms
            - characters
            - timing
          x-parser-schema-id: <anonymous-schema-176>
        title: tts.done
        description: All of a request's audio was sent.
        example: |-
          {
            "type": "tts.done",
            "id": "greeting",
            "audio_ms": 2840,
            "characters": 31,
            "timing": {
              "queue_ms": 0,
              "text_wait_ms": 0,
              "upstream_ttfb_ms": 171,
              "first_audio_ms": 172,
              "total_ms": 1050
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsDone
      - &ref_35
        id: ttsCancelled
        contentType: application/json
        payload:
          - name: tts.cancelled
            description: >-
              A request was stopped. A request stopped before it started has
              only `id`.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.cancelled"`'
                required: true
              - name: id
                type: string
                required: true
              - name: audio_ms
                type: integer
                description: Audio sent before it stopped.
                required: false
              - name: timing
                type: object
                description: >-
                  Server-side timing in milliseconds. `null` when it doesn't
                  apply.
                required: false
                properties:
                  - name: queue_ms
                    type: &ref_8
                      - integer
                      - 'null'
                    description: >-
                      From the request arriving to it starting: waiting behind
                      earlier requests of this session.
                    required: false
                  - name: text_wait_ms
                    type: &ref_9
                      - integer
                      - 'null'
                    description: >-
                      Streamed text: from the request starting to its first
                      piece of text being ready.
                    required: false
                  - name: upstream_ttfb_ms
                    type: &ref_10
                      - integer
                      - 'null'
                    description: >-
                      From the first piece being ready to its first audio: the
                      voice model's time.
                    required: false
                  - name: first_audio_ms
                    type: &ref_11
                      - integer
                      - 'null'
                    description: >-
                      Request received to first audio sent. Your own time to
                      first audio minus this is network time.
                    required: false
                  - name: total_ms
                    type: integer
                    description: Request received to last audio sent.
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.cancelled
              description: '`"tts.cancelled"`'
              x-parser-schema-id: <anonymous-schema-188>
            id:
              type: string
              x-parser-schema-id: <anonymous-schema-189>
            audio_ms:
              type: integer
              description: Audio sent before it stopped.
              x-parser-schema-id: <anonymous-schema-190>
            timing:
              type: object
              description: >-
                Server-side timing in milliseconds. `null` when it doesn't
                apply.
              properties:
                queue_ms:
                  type: *ref_8
                  description: >-
                    From the request arriving to it starting: waiting behind
                    earlier requests of this session.
                  x-parser-schema-id: <anonymous-schema-192>
                text_wait_ms:
                  type: *ref_9
                  description: >-
                    Streamed text: from the request starting to its first piece
                    of text being ready.
                  x-parser-schema-id: <anonymous-schema-193>
                upstream_ttfb_ms:
                  type: *ref_10
                  description: >-
                    From the first piece being ready to its first audio: the
                    voice model's time.
                  x-parser-schema-id: <anonymous-schema-194>
                first_audio_ms:
                  type: *ref_11
                  description: >-
                    Request received to first audio sent. Your own time to first
                    audio minus this is network time.
                  x-parser-schema-id: <anonymous-schema-195>
                total_ms:
                  type: integer
                  description: Request received to last audio sent.
                  x-parser-schema-id: <anonymous-schema-196>
              additionalProperties: true
              x-parser-schema-id: <anonymous-schema-191>
          required:
            - type
            - id
          x-parser-schema-id: <anonymous-schema-187>
        title: tts.cancelled
        description: >-
          A request was stopped. A request stopped before it started has only
          `id`.
        example: |-
          {
            "type": "tts.cancelled",
            "id": "reply-1",
            "audio_ms": 960,
            "timing": {
              "queue_ms": 0,
              "text_wait_ms": 412,
              "upstream_ttfb_ms": 168,
              "first_audio_ms": 580,
              "total_ms": 1490
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsCancelled
      - &ref_36
        id: ttsError
        contentType: application/json
        payload:
          - name: tts.error
            description: A request failed. Later requests still run.
            type: object
            properties:
              - name: type
                type: string
                description: '`"tts.error"`'
                required: true
              - name: id
                type: string
                required: true
              - name: code
                type: string
                description: >-
                  `upstream_error`: speech couldn't be generated, for example
                  with an unknown voice name. Can come after `tts.started` and
                  some audio. `voice_not_available`: the voice ID isn't one of
                  your voices or a public voice; nothing was generated.
                  `internal_error`: the voice couldn't be checked; try again.
                enumValues:
                  - upstream_error
                  - voice_not_available
                  - internal_error
                required: true
              - name: message
                type: string
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: tts.error
              description: '`"tts.error"`'
              x-parser-schema-id: <anonymous-schema-198>
            id:
              type: string
              x-parser-schema-id: <anonymous-schema-199>
            code:
              type: string
              description: >-
                `upstream_error`: speech couldn't be generated, for example with
                an unknown voice name. Can come after `tts.started` and some
                audio. `voice_not_available`: the voice ID isn't one of your
                voices or a public voice; nothing was generated.
                `internal_error`: the voice couldn't be checked; try again.
              enum:
                - upstream_error
                - voice_not_available
                - internal_error
              x-parser-schema-id: <anonymous-schema-200>
            message:
              type: string
              x-parser-schema-id: <anonymous-schema-201>
          required:
            - type
            - id
            - code
            - message
          x-parser-schema-id: <anonymous-schema-197>
        title: tts.error
        description: A request failed. Later requests still run.
        example: |-
          {
            "type": "tts.error",
            "id": "greeting",
            "code": "upstream_error",
            "message": "Text-to-speech service error"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: ttsError
      - &ref_37
        id: pong
        contentType: application/json
        payload:
          - name: pong
            description: Reply to `ping`.
            type: object
            properties:
              - name: type
                type: string
                description: '`"pong"`'
                required: true
              - name: ts
                type: number
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: pong
              description: '`"pong"`'
              x-parser-schema-id: <anonymous-schema-203>
            ts:
              type: number
              x-parser-schema-id: <anonymous-schema-204>
          required:
            - type
            - ts
          x-parser-schema-id: <anonymous-schema-202>
        title: Pong
        description: Reply to `ping`.
        example: |-
          {
            "type": "pong",
            "ts": 1760000000000
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: pong
      - &ref_38
        id: error
        contentType: application/json
        payload:
          - name: error
            description: >-
              Something went wrong. Before the session opens, the socket is then
              closed; after, the session stays open.
            type: object
            properties:
              - name: type
                type: string
                description: '`"error"`'
                required: true
              - name: code
                type: string
                enumValues:
                  - handshake_required
                  - handshake_timeout
                  - unauthorized
                  - forbidden
                  - insufficient_balance
                  - rate_limited
                  - invalid_message
                  - stt_disabled
                  - upstream_error
                  - internal_error
                required: true
              - name: message
                type: string
                description: What went wrong, for people.
                required: true
              - name: reason
                type: string
                description: Sent with some key refusals.
                enumValues:
                  - PublicKeyMintOnly
                  - KeyRotated
                  - ApiKeyRevoked
                  - ApiKeyDisabled
                  - ApiKeyExpired
                required: false
              - name: id
                type: string
                description: >-
                  The request ID, for an ID still in use or a `tts.append` to a
                  request that already got `tts.end`.
                required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: error
              description: '`"error"`'
              x-parser-schema-id: <anonymous-schema-206>
            code:
              type: string
              enum:
                - handshake_required
                - handshake_timeout
                - unauthorized
                - forbidden
                - insufficient_balance
                - rate_limited
                - invalid_message
                - stt_disabled
                - upstream_error
                - internal_error
              x-parser-schema-id: <anonymous-schema-207>
            message:
              type: string
              description: What went wrong, for people.
              x-parser-schema-id: <anonymous-schema-208>
            reason:
              type: string
              enum:
                - PublicKeyMintOnly
                - KeyRotated
                - ApiKeyRevoked
                - ApiKeyDisabled
                - ApiKeyExpired
              description: Sent with some key refusals.
              x-parser-schema-id: <anonymous-schema-209>
            id:
              type: string
              description: >-
                The request ID, for an ID still in use or a `tts.append` to a
                request that already got `tts.end`.
              x-parser-schema-id: <anonymous-schema-210>
          required:
            - type
            - code
            - message
          x-parser-schema-id: <anonymous-schema-205>
        title: Error
        description: >-
          Something went wrong. Before the session opens, the socket is then
          closed; after, the session stays open.
        example: |-
          {
            "type": "error",
            "code": "unauthorized",
            "message": "API key was revoked",
            "reason": "ApiKeyRevoked"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: error
      - &ref_39
        id: draining
        contentType: application/json
        payload:
          - name: session.draining
            description: >-
              The server is restarting. Finish what you are doing and open a new
              session.
            type: object
            properties:
              - name: type
                type: string
                description: '`"session.draining"`'
                required: true
              - name: reconnect_within_ms
                type: integer
                description: Time left before the server closes the socket with code 1012.
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            type:
              type: string
              const: session.draining
              description: '`"session.draining"`'
              x-parser-schema-id: <anonymous-schema-212>
            reconnect_within_ms:
              type: integer
              description: Time left before the server closes the socket with code 1012.
              x-parser-schema-id: <anonymous-schema-213>
          required:
            - type
            - reconnect_within_ms
          x-parser-schema-id: <anonymous-schema-211>
        title: session.draining
        description: >-
          The server is restarting. Finish what you are doing and open a new
          session.
        example: |-
          {
            "type": "session.draining",
            "reconnect_within_ms": 90000
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: draining
    bindings: []
    extensions: *ref_12
sendOperations:
  - *ref_13
receiveOperations:
  - *ref_14
sendMessages:
  - *ref_15
  - *ref_16
  - *ref_17
  - *ref_18
  - *ref_19
  - *ref_20
  - *ref_21
  - *ref_22
  - *ref_23
  - *ref_24
  - *ref_25
receiveMessages:
  - *ref_26
  - *ref_27
  - *ref_28
  - *ref_29
  - *ref_30
  - *ref_31
  - *ref_32
  - *ref_33
  - *ref_34
  - *ref_35
  - *ref_36
  - *ref_37
  - *ref_38
  - *ref_39
extensions:
  - id: x-parser-unique-object-id
    value: realtime
securitySchemes:
  - id: apiKey
    name: api_key
    type: httpApiKey
    description: >-
      Send the key as `api_key` in the `handshake` message. The `api_key` query
      parameter and the `x-api-key` header also work. A secret key (`sk_`) or an
      older (legacy) key; a public key (`pk_`) is refused.
    in: query
    extensions: []

````

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