Call Commands

Gather using speak

Changed on

Convert text to speech and play it on the call until the required DTMF signals are gathered to build interactive menus.

You can pass a list of valid digits along with an 'invalid_payload', which will be played back at the beginning of each prompt. Speech will be interrupted when a DTMF signal is received. The Answer command must be issued before the gather_using_speak command.

Expected Webhooks:

  • call.dtmf.received (you may receive many of these webhooks)
  • call.gather.ended
post/calls/{call_control_id}/actions/gather_using_speak

Request

  • Base URL
    https://api.telnyx.com/v2
  • URL
    https://api.telnyx.com/v2/calls/{call_control_id}/actions/gather_using_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.

invalid_payloadstring

The text or SSML to be converted into speech when digits don't match the valid_digits parameter or the number of digits is not between min and max. 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.

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

minimum_digitsinteger

The minimum number of digits to fetch. This parameter has a minimum value of 1.

maximum_digitsinteger

The maximum number of digits to fetch. This parameter has a maximum value of 128.

maximum_triesinteger

The maximum number of times that a file should be played back if there is no input from the user on the call.

timeout_millisinteger

The number of milliseconds to wait for a DTMF response after speak ends before a replaying the sound file.

terminating_digitstring

The digit used to terminate input if fewer than maximum_digits digits have been gathered. Set to an empty string to disable the terminating digit entirely, so that a digit such as # can be collected as input per valid_digits.

valid_digitsstring

A list of all digits accepted as valid.

inter_digit_timeout_millisinteger

The number of milliseconds to wait for input between digits.

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.

Example request

{
  "payload": "say this on call",
  "invalid_payload": "say this on call",
  "payload_type": "text",
  "service_level": "premium",
  "voice": "male",
  "language": "arb",
  "minimum_digits": 1,
  "maximum_digits": 10,
  "terminating_digit": "#",
  "valid_digits": "123",
  "inter_digit_timeout_millis": 10000,
  "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