Call Commands V1

Call Command operations

Answer call

Answer an incoming call. You must issue this command before executing other subsequent commands on an incoming call.

Expected Webhooks:

  • Call answered
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
post/calls/{call_control_id}/actions/answer
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Bridge calls

Bridge two call control calls.

Expected Webhooks:

  • Call bridged for Leg A
  • Call bridged for Leg B
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
call_control_id
required
string

The call control id of the call you want to bridge with.

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

park_after_unbridge
string

Specifies behavior after the bridge ends (i.e. the opposite leg either hangs up or is transferred). If supplied with the value 'self', the current leg will be parked after unbridge. If not set, the default behavior is to hang up the leg.

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/bridge
Request samples
application/json
{
  • "call_control_id": "c8ac9611-25c3-494a-b8b4-2f036a18a6b2",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "park_after_unbridge": "self"
}
Response samples
application/json
{
  • "result": "ok"
}

Forking start

Call forking allows you to stream the media from a call to a specific target in realtime. This stream can be used to enable realtime audio analysis in support of a variety of use cases, including fraud detection, or the creation of AI-generated audio responses. Requests must specify either the "target" attribute or the "rx" and "tx" attributes.

Expected Webhooks:

There are currently no webhooks associated with the Forking start command.

Simple Telnyx RTP Encapsulation Protocol (STREP)

Note: This header/encapsulation is not used when the "rx" and "tx" parameters have been specified; it only applies when media is forked using the "target" attribute.

If the destination for forked media is specified using the "target" attribute, the RTP will be encapsulated in an extra Telnyx protocol, which adds a 24 byte header to the RTP payload in each packet. The STREP header includes the Call Control call_leg_id for stream identification, along with bits that represent the direction (inbound or outbound) of the media. This 24-byte header sits between the UDP header and the RTP header.

The STREP header makes it possible to fork RTP for multiple calls (or two RTP streams for the same call) to the same IP:port, where the streams can be demultiplexed by your application using the information in the header. Of course, it's still possible to ignore this header completely, for example, if sending forked media for different calls to different ports or IP addresses. In this case, simply strip 24 bytes (or use the second byte to find the header length) from the received UDP payload to get the RTP (RTP header and payload).

STREP Specification

  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |1 1|Version|L|D|    HeaderLen  |  reserved (2 bytes)           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |       reserved (4 bytes, for UDP ports or anything else)      |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |               The call_leg_id                                 |
 |                   from Call Control                           |
 |                       (128 bits / 16 bytes)                   |
 |                           (this is binary data)               |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

 11
   Static bits 11, always set to 11, so that we humans can easily
   visually distinguish forked media from RTP (10) and T.38 media (usually 00)
   and SIP (which begins with a capital letter, so begins with bits 01)
   This is a magic number.

 Version
   Four bits to indicate the version number of the protocol, starting at 0001.

 L
   One bit to represent the leg of the call (A or B).
   0 represents the A (first) leg of the call.
   1 represents the B (second) leg of the call.

 D
   One bit to represent the direction of this RTP stream.
   0 represents media received by Telnyx.
   1 represents media transmitted by Telnyx.

 HeaderLen (1 byte)
   The length of the header in bytes.
   Note that this value does not include the length of the payload. The total
   size of the RTP can be calculated by subtracting the HeaderLen from the UDP
   length (minus 8 for the UDP header).
   In version 1, this value will always be 24.

 Reserved (6 bytes)
   Reserved for future use and to make sure that the header is a multiple of 32 bits

 Call Leg ID
   A 128-bit identifier for the call leg.
   This is the call_leg_id from Call Control.
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
target
string

The network target, udp:ip_address:port, where the call's RTP media packets should be forwarded. Both incoming and outgoing media packets will be delivered to the specified target, and information about the stream will be included in the encapsulation protocol header, including the direction (0 = inbound; 1 = outbound), leg (0 = A-leg; 1 = B-leg), and call_leg_id.

rx
string

The network target, udp:ip_address:port, where the call's incoming RTP media packets should be forwarded.

tx
string

The network target, udp:ip_address:port, where the call's outgoing RTP media packets should be forwarded.

stream_type
string
Default: "raw"

Optionally specify a media type to stream. If decrpyted selected, Telnyx will decrypt incoming SIP media before forking to the target. rx and tx are required fields if decrypted selected.

Enum: "raw" "decrypted"
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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/fork_start
Request samples
application/json
{
  • "target": "udp:186.52.113.6:9000",
  • "rx": "186.52.113.6:9000",
  • "tx": "186.52.113.6:9001",
  • "stream_type": "decrypted",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Forking stop

Stop forking a call.

Expected Webhooks:

There are currently no webhooks associated with the Forking start command.

SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
post/calls/{call_control_id}/actions/fork_stop
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

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:

  • Playback started
  • Playback ended
  • DTMF (you may receive many of these webhooks)
  • Gather ended
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
audio_url
required
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.

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.

min
integer <int32>
Default: 1

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

max
integer <int32>
Default: 128

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

tries
integer <int32>
Default: 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
integer <int32>
Default: 60000

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

terminating_digit
string
Default: "#"

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

valid_digits
string
Default: "0123456789#*"

A list of all digits accepted as valid.

inter_digit_timeout
integer <int32>
Default: 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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/gather_using_audio
Request samples
application/json
{
  • "audio_url": "http://example.com/message.wav",
  • "invalid_audio_url": "http://example.com/invalid.wav",
  • "min": 1,
  • "max": 10,
  • "tries": 3,
  • "timeout": 60000,
  • "terminating_digit": "#",
  • "valid_digits": "123",
  • "inter_digit_timeout": 10000,
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

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 (you may receive many of these webhooks)
  • Gather ended
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
payload
required
string

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
Default: "text"

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

Enum: "text" "ssml"
service_level
string
Default: "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.

Enum: "basic" "premium"
voice
required
string

The gender of the voice used to speak back the text.

Enum: "male" "female"
language
required
string

The language you want spoken.

Enum: "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"
min
integer <int32>
Default: 1

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

max
integer <int32>
Default: 128

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

tries
integer <int32>
Default: 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
integer <int32>
Default: 60000

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

terminating_digit
string
Default: "#"

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

valid_digits
string
Default: "0123456789#*"

A list of all digits accepted as valid.

inter_digit_timeout
integer <int32>
Default: 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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/gather_using_speak
Request samples
application/json
{
  • "payload": "Say this on the call",
  • "invalid_payload": "Say this on the call",
  • "payload_type": "ssml",
  • "service_level": "premium",
  • "voice": "female",
  • "language": "en-US",
  • "min": 1,
  • "max": 10,
  • "tries": 3,
  • "timeout": 60000,
  • "terminating_digit": "#",
  • "valid_digits": "123",
  • "inter_digit_timeout": 10000,
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Stop gather

Stops previously started gather

Expected Webhooks:

  • Gather ended
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/gather_stop
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Hangup call

Expected Webhooks:

  • Call hangup
  • Recording saved (applies only if a call is being recorded)
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
post/calls/{call_control_id}/actions/hangup
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Reject call

Reject an incoming call

Expected Webhooks:

  • Call hangup
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
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".

cause
string

Cause for call rejection.

Enum: "CALL_REJECTED" "USER_BUSY"
Responses
200

Successful response

Response Schema: application/json
result
required
string
post/calls/{call_control_id}/actions/reject
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "cause": "USER_BUSY"
}
Response samples
application/json
{
  • "result": "ok"
}

Play audio URL

Play an audio file on the call. If multiple play audio commands are consecutively issued, the audio files will be placed in a queue awaiting playback.

Notes:

  • when 'overlay' is enabled, 'loop' is limited to 1, and 'target_legs' is limited to 'self'.
  • A customer cannot Play Audio with overlay=true unless there is a Play Audio with overlay=false actively playing.

Expected Webhooks:

  • Playback started
  • Playback ended
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
audio_url
required
string

The URL of the file to be played back on the call. The URL can point to either a WAV or MP3 file.

loop
string
Default: 1

The number of times the audio file should be played. If supplied, the value must be an integer between 1 and 100, or the special string 'infinity' for an endless loop.

overlay
boolean
Default: "false"

When enabled, audio will be mixed on top of any other audio that is actively being played back. Note that overlay: true will only work if there is another audio file already being played on the call.

stop
string
Default: null

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.

target_legs
string
Default: "self"

Specifies the leg or legs on which audio will be played. If supplied, the value must be either 'self', 'opposite' or 'both'.

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

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/playback_start
Request samples
application/json
{
  • "audio_url": "http://www.example.com/sounds/greeting.wav",
  • "loop": "infinity",
  • "overlay": "true",
  • "stop": "current",
  • "target_legs": "self",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Stop audio playback

Stops audio being played on the call.

Expected Webhooks:

  • Either Playback ended or Speak ended
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
stop
string
Default: "all"

Use 'current' to stop only the current audio or 'all' to stop all audios in the queue.

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

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/playback_stop
Request samples
application/json
{
  • "stop": "current",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Recording start

Start recording the call. Recording will stop on call hang-up, or can be initiated via the Stop Recording command.

Expected Webhooks: There are no webhooks associated with this Command.

SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
format
required
string

The audio file format used when storing the call recording. Can be either 'mp3' or 'wav'.

Enum: "wav" "mp3"
channels
required
string

When 'dual', final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.

Enum: "single" "dual"
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".

play_beep
boolean

If enabled, a beep sound will be played at the start of a recording.

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/record_start
Request samples
application/json
{
  • "format": "mp3",
  • "channels": "single",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "play_beep": true
}
Response samples
application/json
{
  • "result": "ok"
}

Recording stop

Stop recording the call.

Expected Webhooks:

  • Recording saved
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
post/calls/{call_control_id}/actions/record_stop
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Send DTMF

Sends DTMF tones from this leg. DTMF tones will be heard by the other end of the call.

Expected Webhooks:

There are no webhooks associated with this command.

SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
digits
required
string

DTMF digits to send. Valid digits are 0-9, A-D, *, and #. Pauses can be added using w (0.5s) and W (1s).

duration
integer <int32>
Default: 250

Specifies for how many milliseconds each digit will be played in the audio stream. Ranges from 100 to 500ms

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

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/send_dtmf
Request samples
application/json
{
  • "digits": "1www2WABCDw9",
  • "duration": 500,
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Speak text

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:

  • Speak started
  • Speak ended
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
payload
required
string

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

payload_type
string
Default: "text"

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

Enum: "text" "ssml"
service_level
string
Default: "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.

Enum: "basic" "premium"
stop
string
Default: null

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.

voice
required
string

The gender of the voice used to speak back the text.

Enum: "male" "female"
language
required
string

The language you want spoken.

Enum: "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"
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".

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/speak
Request samples
application/json
{
  • "payload": "Say this on the call",
  • "payload_type": "ssml",
  • "service_level": "premium",
  • "stop": "current",
  • "voice": "female",
  • "language": "en-US",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "result": "ok"
}

Transfer call

Transfer a call to a new destination. If the transfer is unsuccessful, a 'call_hangup' webhook will be sent indicating that the transfer could not be completed. The original call will remain active and may be issued additional commands, potentially transfering the call to an alternate destination.

Expected Webhooks:

  • Call initiated
  • Call bridged to Leg B
  • You will receive either a Call answered webhook or a Call hangup webhook.
  • Answering Machine Detection Result if answering_machine_detection set to detect, greeting_end or detect_words.
  • Answering Machine Greeting Ended if answering_machine_detection set to greeting_end or detect_words and machine detected initially.
SecuritybasicAuth or bearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required
to
required
string

The DID or SIP URI to dial out and bridge to the given call.

from
string

The 'from' number to be used as the caller id presented to the destination ('to' number). The number should be in +E164 format. This attribute will default to the 'from' number of the original call if omitted.

audio_url
string

Audio URL to be played back when the transfer destination answers before bridging the call. The URL can point to either a WAV or MP3 file.

timeout
integer <int32>
Default: 30

The number of seconds that Telnyx will wait for the call to be answered by the destination to which it is being transferred. If the timeout is reached before an answer is received, the call will hangup and a 'call_hangup' webhook with a 'hangup_cause' of 'timeout' will be sent. Minimum value is 5 seconds. Maximum value is 120 seconds.

time_limit
integer <int32>
Default: 14400

Sets the maximum duration of a Call Control Leg in seconds. If the time limit is reached, the call will hangup and a 'call_hangup' webhook with a 'hangup_cause' of 'time_limit' will be sent. For example, by setting a time limit of 120 seconds, a Call Leg will be automatically terminated two minutes after being answered. The default time limit is 14400 seconds or 4 hours and this is also the maximum allowed call length.

answering_machine_detection
string
Default: "disabled"

Enables Answering Machine Detection. When a call is answered, Telnyx runs real-time detection to determine if it was picked up by a human or a machine and sends an 'answering_machine_detection_result' webhook with the analysis result. If 'greeting_end' or 'detect_words' is used and a 'machine' is detected, you will receive another 'amd_greeting_ended' webhook when the answering machine greeting ends with a beep or silence. If detect_beep is used, you will only receive 'amd_greeting_ended' if a beep is detected.

Enum: "detect" "detect_beep" "detect_words" "greeting_end" "disabled"
object

Optional configuration parameters to modify 'answering_machine_detection' performance.

Array of objects (Custom SIP header)

Custom headers to be added to the SIP INVITE.

client_state
string

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

target_leg_client_state
string

Use this field to add state to every subsequent webhook for the new leg. 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".

sip_auth_username
string

SIP Authentication username used for SIP challenges.

sip_auth_password
string

SIP Authentication password used for SIP challenges.

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls/{call_control_id}/actions/transfer
Request samples
application/json
{
  • "to": "+13129457420 or SIP:[email protected]",
  • "from": "+35319605860",
  • "audio_url": "http://www.example.com/sounds/greeting.wav",
  • "timeout": 60,
  • "time_limit": 600,
  • "answering_machine_detection": "detect",
  • "answering_machine_detection_config": {
    • "total_analysis_time_millis": 5000,
    • "after_greeting_silence_millis": 1000,
    • "between_words_silence_millis": 100,
    • "greeting_duration_millis": 1500,
    • "initial_silence_millis": 1800,
    • "maximum_number_of_words": 3,
    • "maximum_word_length_millis": 2000,
    • "silence_threshold": 512,
    • "greeting_total_analysis_time_millis": 7500,
    • "greeting_silence_duration_millis": 2000
    },
  • "custom_headers": [
    • {
      • "name": "head_1",
      • "value": "val_1"
      },
    • {
      • "name": "head_2",
      • "value": "val_2"
      }
    ],
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "target_leg_client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "sip_auth_username": "string",
  • "sip_auth_password": "string"
}
Response samples
application/json
{
  • "result": "ok"
}

Dial

Dial a number from a given connection. A successful response will include a call_leg_id which can be used to correlate the command with subsequent webhooks.

Expected Webhooks:

  • Call initiated
  • You will receive either a Call answered webhook or a Call hangup webhook.
  • Answering Machine Detection Result if answering_machine_detection set to detect, greeting_end or detect_words.
  • Answering Machine Greeting Ended if answering_machine_detection set to greeting_end or detect_words and machine detected initially.
SecuritybasicAuth or bearerAuth
Request
Request Body schema: application/json
required
to
required
string

The DID or SIP URI to dial out to.

from
required
string

The 'from' number to be used as the caller id presented to the destination ('to' number). The number should be in +E164 format. This attribute will default to the 'from' number of the original call if omitted.

connection_id
required
string

The ID of the Call Control App (formerly ID of the connection) to be used when dialing the destination.

audio_url
string

The URL of a file to be played back to the callee when the call is answered. The URL can point to either a WAV or MP3 file.

timeout
integer <int32>
Default: 30

The number of seconds that Telnyx will wait for the call to be answered by the destination to which it is being called. If the timeout is reached before an answer is received, the call will hangup and a 'call_hangup' webhook with a 'hangup_cause' of 'timeout' will be sent. Minimum value is 5 seconds. Maximum value is 120 seconds.

time_limit
integer <int32>
Default: 14400

Sets the maximum duration of a Call Control Leg in seconds. If the time limit is reached, the call will hangup and a 'call_hangup' webhook with a 'hangup_cause' of 'time_limit' will be sent. For example, by setting a time limit of 120 seconds, a Call Leg will be automatically terminated two minutes after being answered. The default time limit is 14400 seconds or 4 hours and this is also the maximum allowed call length.

answering_machine_detection
string
Default: "disabled"

Enables Answering Machine Detection. When a call is answered, Telnyx runs real-time detection to determine if it was picked up by a human or a machine and sends an 'answering_machine_detection_result' webhook with the analysis result. If 'greeting_end' or 'detect_words' is used and a 'machine' is detected, you will receive another 'amd_greeting_ended' webhook when the answering machine greeting ends with a beep or silence. If detect_beep is used, you will only receive 'amd_greeting_ended' if a beep is detected.

Enum: "detect" "detect_beep" "detect_words" "greeting_end" "disabled"
object

Optional configuration parameters to modify 'answering_machine_detection' performance.

Array of objects (Custom SIP header)

Custom headers to be added to the SIP INVITE.

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

link_to
string

Use another call's control id for sharing the same call session id

sip_auth_username
string

SIP Authentication username used for SIP challenges.

sip_auth_password
string

SIP Authentication password used for SIP challenges.

Responses
200

Successful response

Response Schema: application/json
result
required
string
422

Error response

Response Schema: application/json
code
required
string
title
required
string
detail
required
string
post/calls
Request samples
application/json
{
  • "to": "+13129457420 or SIP:[email protected]",
  • "from": "+35319605860",
  • "connection_id": "string",
  • "audio_url": "http://example.com/message.wav",
  • "timeout": 60,
  • "time_limit": 600,
  • "answering_machine_detection": "detect",
  • "answering_machine_detection_config": {
    • "total_analysis_time_millis": 5000,
    • "after_greeting_silence_millis": 1000,
    • "between_words_silence_millis": 100,
    • "greeting_duration_millis": 1500,
    • "initial_silence_millis": 1800,
    • "maximum_number_of_words": 3,
    • "maximum_word_length_millis": 2000,
    • "silence_threshold": 512,
    • "greeting_total_analysis_time_millis": 7500,
    • "greeting_silence_duration_millis": 2000
    },
  • "custom_headers": [
    • {
      • "name": "head_1",
      • "value": "val_1"
      },
    • {
      • "name": "head_2",
      • "value": "val_2"
      }
    ],
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "link_to": "ilditnZK_eVysupV21KzmzN_sM29ygfauQojpm4BgFtfX5hXAcjotg==",
  • "sip_auth_username": "string",
  • "sip_auth_password": "string"
}
Response samples
application/json
{
  • "result": "ok"
}