Skip to main content
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

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