Call Commands API

Call Control command operations API

Dial

Dial a number or SIP URI 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
  • call.answered or call.hangup
  • call.machine.detection.ended if answering_machine_detection was requested
  • call.machine.greeting.ended if answering_machine_detection was set to detect_beep, greeting_end or detect_words
  • streaming.started and streaming.stopped or streaming.failed if stream_url was set
SecuritybearerAuth
Request
Request Body schema: application/json
required

Call request

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 call.machine.detection.ended webhook with the analysis result. If 'greeting_end' or 'detect_words' is used and a 'machine' is detected, you will receive another 'call.machine.greeting.ended' webhook when the answering machine greeting ends with a beep or silence. If detect_beep is used, you will only receive 'call.machine.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.

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. media_name and audio_url cannot be used together in one request.

billing_group_id
string <uuid>

Use this field to set the Billing Group ID for the call. Must be a valid and existing Billing Group ID.

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 others Dial commands with the same command_id.

connection_id
required
string

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

Array of objects (Custom SIP Header)

Custom headers to be added to the SIP INVITE.

object (DialogflowConfig)
enable_dialogflow
boolean
Default: false

Enables Dialogflow for the current call. The default value is false.

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.

from_display_name
string

The from_display_name string to be used as the caller id name (SIP From Display Name) presented to the destination (to number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the from field.

link_to
string

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

media_encryption
string
Default: "disabled"

Defines whether media should be encrypted on the call.

Enum: "disabled" "SRTP"
media_name
string

The media_name of a file to be played back to the callee when the call is answered. 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.

preferred_codecs
string

The list of comma-separated codecs in a preferred order for the media to be received.

record
string

Start recording automatically after an event. Disabled by default.

Value: "record-from-answer"
record_channels
string
Default: "dual"

Defines which channel should be recorded ('single' or 'dual') when record is specified.

Enum: "single" "dual"
record_format
string
Default: "mp3"

Defines the format of the recording ('wav' or 'mp3') when record is specified.

Enum: "wav" "mp3"
record_max_length
integer <int32>
Default: 0

Defines the maximum length for the recording in seconds when record is specified. The minimum value is 0. The maximum value is 43200. The default value is 0 (infinite).

record_timeout_secs
integer <int32>
Default: 0

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected when record is specified. The timer only starts when the speech is detected. The minimum value is 0. The default value is 0 (infinite).

sip_auth_password
string

SIP Authentication password used for SIP challenges.

sip_auth_username
string

SIP Authentication username used for SIP challenges.

Array of objects (SIP Header)

SIP headers to be added to the SIP INVITE request. Currently only User-to-User header is supported.

sip_transport_protocol
string
Default: "UDP"

Defines SIP transport protocol to be used on the call.

Enum: "UDP" "TCP" "TLS"
object (SoundModifications)

Use this field to modify sound effects, for example adjust the pitch.

stream_track
string
Default: "inbound_track"

Specifies which track should be streamed.

Enum: "inbound_track" "outbound_track" "both_tracks"
stream_url
string

The destination WebSocket address where the stream is going to be delivered.

send_silence_when_idle
boolean
Default: false

Generate silence RTP packets when no transmission available.

time_limit_secs
integer <int32> [ 30 .. 14400 ]
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.

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

required
string or Array of strings

The DID or SIP URI to dial out to. Multiple DID or SIP URIs can be provided using an array of strings

transcription
boolean
Default: false

Start transcription on answer.

object

Transcription configuration.

webhook_url
string

Use this field to override the URL for which Telnyx will send subsequent webhooks to for this call.

webhook_url_method
string
Default: "POST"

HTTP request type used for webhook_url.

Enum: "POST" "GET"
Responses
200

Successful response with details about a call status.

Response Schema: application/json
object (Call)
call_control_id
required
string

Unique identifier and token for controlling the call.

call_duration
integer

Indicates the duration of the call in seconds

call_leg_id
required
string

ID that is unique to the call and can be used to correlate webhook events

call_session_id
required
string

ID that is unique to the call session and can be used to correlate webhook events. Call session is a group of related call legs that logically belong to the same phone call, e.g. an inbound and outbound leg of a transferred call

client_state
string

State received from a command.

is_alive
required
boolean

Indicates whether the call is alive or not. For Dial command it will always be false (dialing is asynchronous).

record_type
required
string
Value: "call"
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postAnswer Post
postHangup Post
postInitiated Post
postMachine Detected Post
postMachine Greeting Ended Post
postStreaming Started Post
postStreaming Stopped Post
postStreaming Failed Post
post/calls
Request samples
application/json
{
  • "answering_machine_detection": "detect",
  • "answering_machine_detection_config": {
    • "after_greeting_silence_millis": 1000,
    • "between_words_silence_millis": 1000,
    • "greeting_duration_millis": 1000,
    • "greeting_silence_duration_millis": 2000,
    • "greeting_total_analysis_time_millis": 50000,
    • "initial_silence_millis": 1000,
    • "maximum_number_of_words": 1000,
    • "maximum_word_length_millis": 2000,
    • "silence_threshold": 512,
    • "total_analysis_time_millis": 5000
    },
  • "audio_url": "http://www.example.com/sounds/greeting.wav",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "connection_id": "7267xxxxxxxxxxxxxx",
  • "custom_headers": [
    • {
      • "name": "head_1",
      • "value": "val_1"
      },
    • {
      • "name": "head_2",
      • "value": "val_2"
      }
    ],
  • "dialogflow_config": {
    • "analyze_sentiment": false,
    • "partial_automated_agent_reply": false
    },
  • "enable_dialogflow": false,
  • "from": "+18005550101",
  • "from_display_name": "Company Name",
  • "media_encryption": "SRTP",
  • "link_to": "ilditnZK_eVysupV21KzmzN_sM29ygfauQojpm4BgFtfX5hXAcjotg==",
  • "sip_auth_password": "password",
  • "sip_auth_username": "username",
  • "sip_headers": [
    • {
      • "name": "User-to-User",
      • "value": "12345"
      }
    ],
  • "sip_transport_protocol": "TLS",
  • "send_silence_when_idle": true,
  • "timeout_limit_secs": 60,
  • "timeout_secs": 60,
  • "to": "+18005550100 or sip:[email protected]",
  • "transcription": true,
  • "transcription_config": {
    • "interim_results": true
    },
  • "webhook_url": "https://www.example.com/server-b/",
  • "webhook_url_method": "POST"
}
Response samples
application/json
{
  • "data": {
    • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
    • "call_duration": 50,
    • "call_leg_id": "2dc6fc34-f9e0-11ea-b68e-02420a0f7768",
    • "call_session_id": "2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768",
    • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    • "is_alive": false,
    • "record_type": "call"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.answered",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "from": "+35319605860",
      • "state": "answered",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

Answer call

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

Expected Webhooks:

  • call.answered
  • streaming.started and streaming.stopped or streaming.failed if stream_url was set
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Answer call request

billing_group_id
string <uuid>

Use this field to set the Billing Group ID for the call. Must be a valid and existing Billing Group ID.

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.

Array of objects (Custom SIP Header)

Custom headers to be added to the SIP INVITE response.

preferred_codecs
string

The list of comma-separated codecs in a preferred order for the media to be received.

Array of objects (SIP Header)

SIP headers to be added to the SIP INVITE response. Currently only User-to-User header is supported.

object (SoundModifications)

Use this field to modify sound effects, for example adjust the pitch.

stream_track
string
Default: "inbound_track"

Specifies which track should be streamed.

Enum: "inbound_track" "outbound_track" "both_tracks"
stream_url
string

The destination WebSocket address where the stream is going to be delivered.

send_silence_when_idle
boolean
Default: false

Generate silence RTP packets when no transmission available.

webhook_url
string

Use this field to override the URL for which Telnyx will send subsequent webhooks to for this call.

webhook_url_method
string
Default: "POST"

HTTP request type used for webhook_url.

Enum: "POST" "GET"
Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postAnswered Post
postStreaming Started Post
postStreaming Stopped Post
postStreaming Failed Post
post/calls/{call_control_id}/actions/answer
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "webhook_url": "https://www.example.com/server-b/",
  • "webhook_url_method": "POST",
  • "send_silence_when_idle": true
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.answered",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "from": "+35319605860",
      • "state": "answered",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

Bridge calls

Bridge two call control calls.

Expected Webhooks:

  • call.bridged for Leg A
  • call.bridged for Leg B
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Bridge call request

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 any command with the same command_id for the same call_control_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.

queue
string

The name of the queue you want to bridge with, can't be used together with call_control_id parameter. Bridging with a queue means bridging with the first call in the queue. The call will always be removed from the queue regardless of whether bridging succeeds. Returns an error when the queue is empty.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postBridged Post
post/calls/{call_control_id}/actions/bridge
Request samples
application/json
{
  • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "park_after_unbridge": "self"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Bridged Post
application/json
{
  • "data": {
    • "event_type": "call.bridged",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "from": "+35319605860",
      • "state": "bridged",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

Update client state

Updates client state

SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Updates client state for every subsequent webhook

client_state
required
string

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

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
put/calls/{call_control_id}/actions/client_state_update
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Enqueue call

Put the call in a queue.

SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Enqueue call request

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.

max_size
integer
Default: 100

The maximum number of calls allowed in the queue at a given time. Can't be modified for an existing queue.

max_wait_time_secs
integer

The number of seconds after which the call will be removed from the queue.

queue_name
string

The name of the queue the call should be put in. If a queue with a given name doesn't exist yet it will be created.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postEnqueued Post
postLeft Que Post
post/calls/{call_control_id}/actions/enqueue
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "max_size": 20,
  • "max_wait_time_secs": 600,
  • "queue_name": "support"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.enqueued",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "current_position": 5,
      • "queue": "support"
      },
    • "record_type": "event"
    }
}

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 to support 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:

  • call.fork.started
  • call.fork.stopped

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 to easily 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.
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Fork media request

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.

rx
string

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

stream_type
string
Default: "raw"

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

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

tx
string

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

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postFork Started Post
postFork Stopped Post
post/calls/{call_control_id}/actions/fork_start
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "rx": "udp:192.0.2.1:9000",
  • "target": "udp:192.0.2.1:9000",
  • "tx": "udp:192.0.2.1:9001"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.fork.started",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v2:OycMASgvIjsGIAVEx8x3n9rYeKnUJx6a3V8VGhs5futnr17KZhujZA",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "stream_type": "decrypted"
      },
    • "record_type": "event"
    }
}

Forking stop

Stop forking a call.

Expected Webhooks:

  • call.fork.stopped
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Stop forking media request

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.

stream_type
string
Default: "raw"

Optionally specify a stream_type. This should match the stream_type that was used in fork_start command to properly stop the fork.

Enum: "raw" "decrypted"
Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postFork Stopped Post
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
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Fork Stopped Post
application/json
{
  • "data": {
    • "event_type": "call.fork.stopped",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v2:OycMASgvIjsGIAVEx8x3n9rYeKnUJx6a3V8VGhs5futnr17KZhujZA",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "stream_type": "decrypted"
      },
    • "record_type": "event"
    }
}

Gather

Gather DTMF signals to build interactive menus.

You can pass a list of valid digits. The Answer command must be issued before the gather command.

Expected Webhooks:

  • call.dtmf.received (you may receive many of these webhooks)
  • call.gather.ended
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Gather

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.

initial_timeout_millis
integer <int32>
Default: 5000

The number of milliseconds to wait for the first DTMF.

inter_digit_timeout_millis
integer <int32>
Default: 5000

The number of milliseconds to wait for input between digits.

maximum_digits
integer <int32>
Default: 128

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

minimum_digits
integer <int32>
Default: 1

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

terminating_digit
string
Default: "#"

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

timeout_millis
integer <int32>
Default: 60000

The number of milliseconds to wait to complete the request.

valid_digits
string
Default: "0123456789#*"

A list of all digits accepted as valid.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postDTMF Received Post
postGather Ended Post
post/calls/{call_control_id}/actions/gather
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "initial_timeout_millis": 10000,
  • "inter_digit_timeout_millis": 10000,
  • "maximum_digits": 10,
  • "minimum_digits": 1,
  • "terminating_digit": "#",
  • "timeout_millis": 60000,
  • "valid_digits": "123"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.dtmf.received",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "digit": "#",
      • "from": "+35319605860",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

Gather stop

Stop current gather.

Expected Webhooks:

  • call.gather.ended
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Stop current gather

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.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postGather Ended Post
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
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Gather Ended Post
application/json
{
  • "data": {
    • "event_type": "call.gather.ended",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "digits": "123",
      • "from": "+35319605860",
      • "status": "valid",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

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
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

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.

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.

inter_digit_timeout_millis
integer <int32>
Default: 5000

The number of milliseconds to wait for input between digits.

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.

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.

maximum_digits
integer <int32>
Default: 128

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

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.

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.

minimum_digits
integer <int32>
Default: 1

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

terminating_digit
string
Default: "#"

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

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.

valid_digits
string
Default: "0123456789#*"

A list of all digits accepted as valid.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postDTMF Received Post
postGather Ended Post
postCall Playback Ended Post
postCall Playback Started Post
post/calls/{call_control_id}/actions/gather_using_audio
Request samples
application/json
{
  • "audio_url": "http://example.com/message.wav",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "inter_digit_timeout_millis": 10000,
  • "invalid_audio_url": "http://example.com/message.wav",
  • "maximum_digits": 10,
  • "minimum_digits": 1,
  • "terminating_digit": "#",
  • "timeout_millis": 10000,
  • "valid_digits": "123"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.dtmf.received",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "digit": "#",
      • "from": "+35319605860",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

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
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Gather using speak request

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.

inter_digit_timeout_millis
integer <int32>
Default: 5000

The number of milliseconds to wait for input between digits.

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.

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"
maximum_digits
integer <int32>
Default: 128

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

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

minimum_digits
integer <int32>
Default: 1

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

payload
required
string

The text or SSML to be converted into speech. There is a 3,000 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"
terminating_digit
string
Default: "#"

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

timeout_millis
integer <int32>
Default: 60000

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

valid_digits
string
Default: "0123456789#*"

A list of all digits accepted as valid.

voice
required
string

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

Enum: "male" "female"
Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postDTMF Received Post
postGather Ended Post
post/calls/{call_control_id}/actions/gather_using_speak
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "inter_digit_timeout_millis": 10000,
  • "invalid_payload": "say this on call",
  • "language": "arb",
  • "maximum_digits": 10,
  • "minimum_digits": 1,
  • "payload": "say this on call",
  • "payload_type": "text",
  • "service_level": "premium",
  • "terminating_digit": "#",
  • "valid_digits": "123",
  • "voice": "male"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.dtmf.received",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "digit": "#",
      • "from": "+35319605860",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

Hangup call

Hang up the call.

Expected Webhooks:

  • call.hangup
  • call.recording.saved
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Hangup request

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.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postHangup Post
postRecording Error Post
postRecording Saved Post
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
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.hangup",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "from": "+35319605860",
      • "hangup_cause": "call_rejected",
      • "hangup_source": "caller",
      • "sip_hangup_cause": "603",
      • "start_time": "2018-02-02T22:20:27.521992Z",
      • "state": "hangup",
      • "to": "+35319605860"
      },
    • "record_type": "event"
    }
}

Remove call from a queue

Removes the call from a queue.

SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Removes the call from the queue, the call currently is enqueued in.

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.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postCall Left Queue Post
post/calls/{call_control_id}/actions/leave_queue
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Call Left Queue Post
application/json
{
  • "data": {
    • "event_type": "call.dequeued",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "queue": "support",
      • "queue_position": 3,
      • "reason": "leave"
      },
    • "record_type": "event"
    }
}

Play audio URL

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

Notes:

  • When overlay is enabled, 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:

  • call.playback.started
  • call.playback.ended
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Play audio URL request

audio_url
string

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

cache_audio
boolean
Default: true

Caches the audio file. Useful when playing the same audio file multiple times during the call.

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.

string or integer (Loopcount)
media_name
string

The media_name of a file to be played back on the call. 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.

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.

playback_content
string

Allows a user to provide base64 encoded mp3. Note: when using this parameter, media_url and media_name in the playback_started and playback_ended webhooks will be empty

stop
string

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.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postPlayback Ended Post
postPlayback Started Post
post/calls/{call_control_id}/actions/playback_start
Request samples
application/json
{
  • "audio_url": "http://www.example.com/sounds/greeting.wav",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "loop": "infinity",
  • "overlay": true,
  • "stop": "current",
  • "target_legs": "self"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.playback.ended",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "media_name": "my_media_uploaded_to_media_storage_api",
      • "overlay": false,
      • "status": "completed"
      },
    • "record_type": "event"
    }
}

Stop audio playback

Stop audio being played on the call.

Expected Webhooks:

  • call.playback.ended or call.speak.ended
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Stop audio playback request

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.

overlay
boolean
Default: false

When enabled, it stops the audio being played in the overlay queue.

stop
string
Default: "all"

Use current to stop the current audio being played. Use all to stop the current audio file being played and clear all audio files from the queue.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)
result
string
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postPlayback Ended Post
postSpeak Ended Post
post/calls/{call_control_id}/actions/playback_stop
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "overlay": false,
  • "stop": "all"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.playback.ended",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "media_name": "my_media_uploaded_to_media_storage_api",
      • "overlay": false,
      • "status": "completed"
      },
    • "record_type": "event"
    }
}

Record pause

Pause recording the call. Recording can be resumed via Resume recording command.

Expected Webhooks:

There are no webhooks associated with this command.

SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Pause recording call request

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.

Responses
200

Successful response upon making a call control command.

Response Schema: application/json
object (CallControlCommandResult)