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:

  • DTMF
  • Gather ended


Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call



    payload stringrequired

    The text or SSML to be converted into speech. There is a 3,500 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,500 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.

    language stringrequired

    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.

    min int32

    Default value: 1

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

    max int32

    Default value: 128

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

    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 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 "max" digits have been gathered.

    valid_digits string

    Default value: 0123456789#*

    A list of all digits accepted as valid.

    inter_digit_timeout 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 commands with the same "command_id".


200: Successful response

422: Error response