Sign in

v52

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Call Commands

Speak text

Convert text to speech and play it back on the call. If multiple speak text commands are issued consecutively, the audio files will be placed in a queue awaiting playback.

Expected Webhooks:

  • call.speak.started
  • call.speak.ended
post/calls/{call_control_id}/actions/speak

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

client_statestring

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

command_idstring

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

language'arb' | 'cmn-CN' | 'cy-GB' | 'da-DK' | 'de-DE' | 'en-AU' | 'en-GB' | 'en-GB-WLS' | 'en-IN' | 'en-US' | 'es-ES' | 'es-MX' | 'es-US' | 'fr-CA' | 'fr-FR' | 'hi-IN' | 'is-IS' | 'it-IT' | 'ja-JP' | 'ko-KR' | 'nb-NO' | 'nl-NL' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sv-SE' | 'tr-TR'

The language you want spoken. This parameter is ignored when a Polly.* voice is specified.

payloadstring required

The text or SSML to be converted into speech. There is a 3,000 character limit.

payload_type'text' | 'ssml'

The type of the provided payload. The payload can either be plain text, or Speech Synthesis Markup Language (SSML).

service_level'basic' | 'premium'

This parameter impacts speech quality, language options and payload types. When using basic, only the en-US language and payload type text are allowed.

stopstring

When specified, it stops the current audio being played. Specify current to stop the current audio being played, and to play the next file in the queue. Specify all to stop the current audio file being played and to also clear all audio files from the queue.

target_legs'self' | 'opposite' | 'both'

Specifies which legs of the call should receive the spoken audio.

voicestring required

Specifies the voice used in speech synthesis.

  • Define voices using the format <Provider>.<Model>.<VoiceId>. Specifying only the provider will give default values for voice_id and model_id.

Supported Providers:

  • AWS: Use AWS.Polly.<VoiceId> (e.g., AWS.Polly.Joanna). For neural voices, which provide more realistic, human-like speech, append -Neural to the VoiceId (e.g., AWS.Polly.Joanna-Neural). Check the available voices for compatibility.
  • Azure: Use Azure.<VoiceId> (e.g., Azure.en-CA-ClaraNeural, Azure.en-US-BrianMultilingualNeural, Azure.en-US-Ava:DragonHDLatestNeural). For a complete list of voices, go to Azure Voice Gallery. Use voice_settings to configure custom deployments, regions, or API keys.
  • ElevenLabs: Use ElevenLabs.<ModelId>.<VoiceId> (e.g., ElevenLabs.eleven_multilingual_v2.21m00Tcm4TlvDq8ikWAM). The ModelId part is optional. To use ElevenLabs, you must provide your ElevenLabs API key as an integration identifier secret in "voice_settings": {"api_key_ref": "<secret_identifier>"}. See integration secrets documentation for details. Check available voices.
  • Telnyx: Use Telnyx.<model_id>.<voice_id> (e.g., Telnyx.KokoroTTS.af). Use voice_settings to configure voice_speed and other synthesis parameters. Bayan provides Arabic (multiple dialects) and English voices (e.g., Telnyx.Bayan.Ahmed, Telnyx.Bayan.Amanda). Sukhan provides Urdu voices (e.g., Telnyx.Sukhan.urdu-professor); voice_speed is not supported.
  • Minimax: Use Minimax.<ModelId>.<VoiceId> (e.g., Minimax.speech-02-hd.Wise_Woman). Supported models: speech-02-turbo, speech-02-hd, speech-2.6-turbo, speech-2.8-turbo. Use voice_settings to configure speed, volume, pitch, and language_boost.
  • Rime: Use Rime.<model_id>.<voice_id> (e.g., Rime.Arcana.cove). Supported model_ids: Arcana, Mist, ArcanaV3, Coda. Use voice_settings to configure voice_speed.
  • Resemble: Use Resemble.Turbo.<voice_id> (e.g., Resemble.Turbo.my_voice). Only Turbo model is supported. Use voice_settings to configure precision, sample_rate, and format.
  • Inworld: Use Inworld.<ModelId>.<VoiceId> (e.g., Inworld.Mini.Loretta, Inworld.Max.Oliver, Inworld.TTS2.Loretta). Supported models: Mini, Max, TTS2. Use voice_settings to configure delivery_mode (STABLE, BALANCED, CREATIVE), supported by TTS2 only.
  • Fish Audio: Use FishAudio.<ModelId>.<VoiceId> (e.g., FishAudio.s2.1-pro.<reference_id>). Supported models: s2.1-pro, s2-pro, s1. VoiceId is a Fish Voice-Library reference ID.
  • xAI: Use xAI.<VoiceId> (e.g., xAI.eve). Available voices: eve, ara, rex, sal, leo.
  • Humain: Use Humain.<VoiceId> (e.g., Humain.sara-ar). Available voices: sara-en, abdulaziz-en, sara-ar, abdulaziz-ar, nourah-ar, abdullah-ar. Native Arabic (Saudi dialect) and English voices only — no ModelId segment.

For service_level basic, you may define the gender of the speaker (male or female).

Example request

{
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "language": "arb",
  "payload": "Say this on the call",
  "payload_type": "text",
  "service_level": "basic",
  "stop": "current",
  "voice": "female"
}

Response

Successful response upon making a call control command.

Example response

{
  "data": {
    "result": "ok"
  }
}