TEteam-telnyx
Call Commands

Speak text

Changed on

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

Request

  • Base URL
    https://api.telnyx.com/v2
  • URL
    https://api.telnyx.com/v2/calls/{call_control_id}/actions/speak
  • Auth
    HTTP bearer

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

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.

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.
  • Resemble: Use Resemble.<ModelId>.<VoiceId> (e.g., Resemble.Turbo.Aaron_en-US). Supported models: Pro, Turbo, Urdu. <VoiceId> is a stock voice name or the ID of a Resemble voice clone. 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.
  • Soniox: Use Soniox.<ModelId>.<VoiceId> (e.g., Soniox.tts-rt-v2.Emma). Supported model: tts-rt-v2. Browse the catalog via the Voices API. Every voice speaks all supported languages; set language to the two-letter ISO 639-1 code of the text, for example it. SSML is not supported. Use voice_settings to configure speed (0.7 to 1.3) and reduce_silence.
  • 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).

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.

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.

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

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

Example request

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

Response

Successful response upon making a call control command.

Example response

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

Changes

  • 824e8d33d07aRevision changes
    • breaking

      removed subschema #1 from the request property anyOf list

    • info

      added discriminator to request property

    • info

      added to the request property oneOf list

  • 4198718f2811Revision changes
    • breaking

      removed from the request property oneOf list

    • info

      added subschema #1 to the request property anyOf list

    • info

      removed discriminator from request property