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

# Audio scenarios and languages

> Play bundled scripts or synthesize caller and call-taker transcripts.

Set `needAudio` to `true` to send separate caller and call-taker audio tracks. Speech is generated
with eSpeak NG: useful for integration tests, but robotic rather than a human voice or live AI.

## Canonical request values

The public schema requires exact lowercase `scenario` and `role` enum values, without surrounding
whitespace. Use `counting` and `call-taker`, not `" COUNTING "` or `" CALL-TAKER "`. The server
still trims and case-normalizes those inputs for compatibility, but that tolerance is intentionally
not part of the public schema. With a custom script, omit `scenario` or send `null`; the server
also tolerates blank scenario strings, but schema-based clients should not send them.

## Bundled scenarios

| `scenario` | Purpose |
| - | - |
| `domestic-disturbance` | Default emergency conversation, including address and callback details |
| `medical-emergency` | Medical emergency conversation |
| `traffic-collision` | Traffic-collision conversation |
| `counting` | Alternating role-labeled three-number turns with one-second gaps |

```json theme={null}
{
  "stationId": "2202",
  "phoneNumber": "2025550100",
  "needAudio": true,
  "callLengthSeconds": 60,
  "scenario": "medical-emergency"
}
```

`callLengthSeconds` is a **maximum**, not a minimum. Audio plays once, then the simulator ends
the recording and confirms cleanup. There is no silent tail to fill the requested duration.
A shorter maximum cuts playback off. Counting also plays only one cycle. Without audio, the
requested duration controls the call lifetime unless cancelled or ended by the recording server.

## Custom and mixed-language conversations

Omit `scenario` when supplying `customScenario`. Turns play in order, with silence on the other
track and a default one-second gap. Consecutive turns may use the same role.

```json theme={null}
{
  "stationId": "2202",
  "phoneNumber": "2025550100",
  "needAudio": true,
  "callLengthSeconds": 60,
  "customScenario": {
    "language": "es",
    "pauseBetweenTurnsMs": 1000,
    "turns": [
      { "role": "call-taker", "language": "en", "text": "911, what is your emergency?" },
      { "role": "caller", "text": "Necesito ayuda. Mi dirección es calle Mayor número doce." },
      { "role": "call-taker", "text": "Estoy enviando ayuda." },
      { "role": "call-taker", "language": "en", "text": "Please stay on the line." }
    ]
  }
}
```

The scenario language is the default for its turns; a turn's `language` overrides it. Omitted or
blank turn language inherits the scenario. Without a scenario language, English is used.
To switch languages for one speaker, split the text into consecutive turns with that role.

All supported language codes installed in the deployed eSpeak image are available—not just
English, Spanish and French. Use eSpeak codes such as `es`, `fr` or `hi`; unsupported codes return
`400 invalid_custom_scenario`. Codes are trimmed and case-normalized; `en` and `en-us` select
default English, and `es-ES` maps to `es`. The service does not translate text or detect language.
Support can confirm the installed catalog; there is no public language-list endpoint.

## Bounds

* 1–32 turns; each `role` is `caller` or `call-taker`.
* Nonblank text, up to 512 UTF-16 code units per turn and 4,000 total after trimming.
* `pauseBetweenTurnsMs`: 0–5,000; default 1,000. Keep a gap for clearer speaker separation.
* Printable Unicode is supported, including linguistic ZWJ/ZWNJ. Control, bidi/other invisible
  formatting, private-use and invalid characters are rejected. Pasted formatting marks may need removal.
* The entire JSON request is limited to **8 KiB in UTF-8**, which can bind before text/turn limits,
  particularly for non-ASCII text or JSON escaped as `\uXXXX`.
* Prepared custom audio, including pauses, has an absolute **five-minute** cap. A longer
  generated script returns `422 custom_scenario_too_long`; fitting audio is truncated if the
  requested call maximum is shorter. Environment and tenant duration policies also apply.

The schema's `minLength`/`maxLength` inspect **raw Unicode code points**. They are approximations,
not exact models of the runtime's UTF-16 limits or its trimming step. For example, 257 emoji are
257 code points but 514 UTF-16 units, exceeding a turn's limit. Conversely, 512 ASCII letters
padded with spaces can exceed the raw schema bound but pass the service after trimming.
Trim valid text and count UTF-16 units before schema validation; in JavaScript, string `.length`
counts these units. Do not strip forbidden controls to make an invalid script pass: the service
rejects those before trimming. The server also checks the total 4,000-unit bound and all other
text rules, so passing the schema alone does not guarantee acceptance.

Keep real caller information out of test scripts. Synthesized speech quality and downstream
transcription/translation support vary by language; successful audio generation does not prove
the language is supported by your Assist transcription configuration.


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