Skip to main content

Gather using speak


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


Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call



Gather using speak request

    payload stringrequired

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

    invalid_payload string

    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 string

    Possible values: [text, ssml]

    Default value: text

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

    service_level string

    Possible values: [basic, premium]

    Default value: 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.

    voice stringrequired

    Possible values: [male, female]

    The gender of the voice used to speak back the text or the specific Amazon Polly voice to be used in the form of Polly.<voice>, e.g. Polly.Brian. All standard Amazon Polly voices are supported.

    language string

    Possible values: [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_digits int32

    Default value: 1

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

    maximum_digits int32

    Default value: 128

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

    maximum_tries int32

    Default value: 3

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

    timeout_millis int32

    Default value: 60000

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

    terminating_digit string

    Default value: #

    The digit used to terminate input if fewer than maximum_digits digits have been gathered.

    valid_digits string

    Default value: 0123456789#*

    A list of all digits accepted as valid.

    inter_digit_timeout_millis int32

    Default value: 5000

    The number of milliseconds to wait for input between digits.

    client_state string

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

    command_id string

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


200: Successful response upon making a call control command.

default: Unexpected error