Gather using audio

Play an audio file 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_audio_url’, which will be played back at the beginning of each prompt. Playback will be interrupted when a DTMF signal is received. The Answer command must be issued before the gather_using_audio` command.

Expected Webhooks:

• call.playback.started
• call.playback.ended
• call.dtmf.received (you may receive many of these webhooks)
• call.gather.ended

POST /calls/{call_control_id}/actions/gather_using_audio

JavaScript

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.actions.gatherUsingAudio('call_control_id');

console.log(response.data);

200

Example

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

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

call_control_id · string · required

Unique identifier and token for controlling the call

Body

application/json

Gather using audio request

audio_url · string

The URL of a file to be played back at the beginning of each prompt. The URL can point to either a WAV or MP3 file. media_name and audio_url cannot be used together in one request.

Example:

"http://example.com/message.wav"

media_name · string

The media_name of a file to be played back at the beginning of each prompt. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file.

Example:

"my_media_uploaded_to_media_storage_api"

invalid_audio_url · string

The URL of a file to play when digits don't match the valid_digits parameter or the number of digits is not between min and max. The URL can point to either a WAV or MP3 file. invalid_media_name and invalid_audio_url cannot be used together in one request.

Example:

"http://example.com/invalid.wav"

invalid_media_name · string

The media_name of a file to be played back when digits don't match the valid_digits parameter or the number of digits is not between min and max. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file.

Example:

"my_media_uploaded_to_media_storage_api"

minimum_digits · integer<int32> · default: 1

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

Example:

1

maximum_digits · integer<int32> · default: 128

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

Example:

10

maximum_tries · integer<int32> · default: 3

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

Example:

3

timeout_millis · integer<int32> · default: 60000

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

Example:

60000

terminating_digit · string · default: #

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.

Example:

"#"

valid_digits · string · default: 0123456789#*

A list of all digits accepted as valid.

Example:

"123"

inter_digit_timeout_millis · integer<int32> · default: 5000

The number of milliseconds to wait for input between digits.

Example:

10000

client_state · string

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

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

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.

Example:

"891510ac-f3e4-11e8-af5b-de00688a4901"

Response

200

application/json

Successful response upon making a call control command.

data · Call Control Command Result · object

Show child attributes

Example:

{ "result": "ok" }