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 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 forked 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
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:username@sip.telnyx.com",
  • "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 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.

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
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)
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
post/calls/{call_control_id}/actions/record_pause
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Record resume

Resume recording the call.

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

Resume 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)
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
post/calls/{call_control_id}/actions/record_resume
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "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:

  • 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

Start recording audio request

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

format
required
string

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

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

Defines the maximum length for the recording in seconds. The minimum value is 0. The maximum value is 14400. The default value is 0 (infinite)

play_beep
boolean

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

timeout_secs
integer <int32>
Default: 0

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. The minimum value is 0. The default value is 0 (infinite). Please note that the transcription is being used for detecting the silence and the charge for it will be applied.

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
post/calls/{call_control_id}/actions/record_start
Request samples
application/json
{
  • "channels": "single",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "format": "wav",
  • "max_length": 0,
  • "play_beep": true,
  • "timeout_secs": 0
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Recording stop

Stop recording the call.

Expected Webhooks:

  • 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

Stop 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)
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
postRecording Error Post
postRecording Saved Post
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
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.recording.error",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "result": "Internal server error"
      },
    • "record_type": "event"
    }
}

SIP Refer a call

Initiate a SIP Refer on a Call Control call. You can initiate a SIP Refer at any point in the duration of a call.

Expected Webhooks:

  • call.refer.started
  • call.refer.completed
  • call.refer.failed
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Refer 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 execution of duplicate commands. Telnyx will ignore subsequent commands with the same command_id as one that has already been executed.

Array of objects (Custom SIP Header)

Custom headers to be added to the SIP INVITE.

sip_address
required
string

The SIP URI to which the call will be referred to.

sip_auth_password
string

SIP Authentication password used for SIP challenges.

sip_auth_username
string

SIP Authentication username used for SIP challenges.

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
postRefer Completed Post
postCall Refer Failed Post
postRefer Started Post
post/calls/{call_control_id}/actions/refer
Request samples
application/json
{
  • "sip_address": "sip:username@sip.non-telnyx-address.com"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.refer.completed",
    • "id": "4ce4366d-8d87-44be-a00b-942154e9c5f5",
    • "occurred_at": "2020-03-30T13:29:44.650000Z",
    • "payload": {
      • "call_control_id": "v2:OycMASgvIjsGIAVEx8x3n9rYeKnUJx6a3V8VGhs5futnr17KZhujZA",
      • "call_leg_id": "817f7de8-728a-11ea-9ce6-02420a0f8969",
      • "call_session_id": "817f8c2a-728a-11ea-9cbe-02420a0f8969",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "1289082222292239760",
      • "from": "+35319605860",
      • "sip_notify_response": 200,
      • "to": "+13129457420"
      },
    • "record_type": "event"
    }
}

Reject a call

Reject an incoming call.

Expected Webhooks:

  • call.hangup
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Reject request

cause
required
string

Cause for call rejection.

Enum: "CALL_REJECTED" "USER_BUSY"
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
post/calls/{call_control_id}/actions/reject
Request samples
application/json
{
  • "cause": "USER_BUSY",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Hangup Post
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"
    }
}

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.

SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Send DTMF 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.

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_millis
integer <int32>
Default: 250

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

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
post/calls/{call_control_id}/actions/send_dtmf
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "digits": "1www2WABCDw9",
  • "duration_millis": 500
}
Response samples
application/json
{
  • "data": {
    • "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:

  • call.speak.started
  • 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

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.

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

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
postSpeak Ended Post
postSpeak Started Post
post/calls/{call_control_id}/actions/speak
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "language": "arb",
  • "payload": "Say this on the call",
  • "payload_type": "text",
  • "service_level": "basic",
  • "stop": "current",
  • "voice": "female"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "call.speak.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",
      • "status": "completed"
      },
    • "record_type": "event"
    }
}

Streaming start

Start streaming the media from a call to a specific WebSocket address in near-realtime. Audio will be delivered as base64-encoded RTP payload (raw audio), wrapped in JSON payloads.

Expected Webhooks:

  • streaming.started
  • streaming.stopped

WebSocket events

When the WebSocket connection is established, the following event is being sent over it:

{
  "event": "connected",
  "version": "1.0.0"
}

And when the call is started, an event which contains information about the encoding and stream_id that identifies a particular stream:

{
  "event": "start",
  "sequence_number": "1",
  "start": {
    "user_id": "3e6f995f-85f7-4705-9741-53b116d28237",
    "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "media_format": {
      "encoding": "PCMU",
      "sample_rate": 8000,
      "channels": 1
    }
  },
  "stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc"
}

The start event is followed by the following media events that contain base64-encoded RTP payload (raw audio, no RTP headers) (:

{
  "event": "media",
  "sequence_number": "4",
  "media": {
    "track": "inbound/outbound",
    "chunk": "2",
    "timestamp": "5",
    "payload": "no+JhoaJjpzSHxAKBgYJD...IsSbjomGhoqQn1Ic"
  },
  "stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc"
}

Please note that the order of events is not guaranteed and the chunk number can be used to reorder the events.

When the call ends, the stop event over WebSockets connection is sent:

{
  "event": "stop",
  "sequence_number": "5",
  "stop": {
    "user_id": "3e6f995f-85f7-4705-9741-53b116d28237",
    "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ"
   },
    "stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc"
 }
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Start streaming 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.

object (DialogflowConfig)
enable_dialogflow
boolean
Default: false

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

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.

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
postStreaming Started Post
postStreaming Stopped Post
post/calls/{call_control_id}/actions/streaming_start
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "dialogflow_config": {
    • "analyze_sentiment": false,
    • "partial_automated_agent_reply": false
    },
  • "enable_dialogflow": false,
  • "stream_track": "both_tracks",
  • "stream_url": "wss://www.example.com/websocket"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "streaming.started",
    • "id": "7d743d69-f7e8-4761-b7d4-8cacf9d3c031",
    • "occurred_at": "2021-12-15T14:06:32.059436Z",
    • "payload": {
      • "call_control_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      • "call_leg_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      • "call_session_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "stream_url": "wss://www.example.com/websocket"
      },
    • "record_type": "event"
    }
}

Streaming stop

Stop streaming a call to a WebSocket.

Expected Webhooks:

  • streaming.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 streaming 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.

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
postStreaming Stopped Post
post/calls/{call_control_id}/actions/streaming_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: Streaming Stopped Post
application/json
{
  • "data": {
    • "event_type": "streaming.stopped",
    • "id": "25dc3731-e51e-4927-a50d-a61cc25984b1",
    • "occurred_at": "2021-12-15T14:11:24.613295Z",
    • "payload": {
      • "call_control_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      • "call_leg_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      • "call_session_id": "31f19208-5db0-11ec-9ea7-02420a0d3a69",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "stream_url": "wss://www.example.com/websocket"
      },
    • "record_type": "event"
    }
}

Transcription start

Start real-time transcription. Transcription will stop on call hang-up, or can be initiated via the Transcription stop command.

Expected Webhooks:

  • call.transcription
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Transcription start 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.

interim_results
boolean
Default: false

Whether to send also interim results. If set to false, only final results will be sent. Applies to transcription_engine A only.

language
string
Default: "en"

Language to use for speech recognition

Enum: "de" "en" "es" "fr" "it" "pl"
transcription_engine
string
Default: "A"

Engine to use for speech recognition. A - google, B - telnyx.

Enum: "A" "B"
transcription_tracks
string
Default: "inbound"

Indicates which leg of the call will be transcribed. Use inbound for the leg that requested the transcription, outbound for the other leg, and both for both legs of the call. Will default to inbound.

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
postTranscription Post
post/calls/{call_control_id}/actions/transcription_start
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "language": "en",
  • "transcription_engine": "A"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Transcription Post
application/json
{
  • "data": {
    • "event_type": "call.transcription",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v2:7subYr8fLrXmaAXm8egeAMpoSJ72J3SGPUuome81-hQuaKRf9b7hKA",
      • "call_leg_id": "5ca81340-5beb-11eb-ae45-02420a0f8b69",
      • "call_session_id": "5ca81eee-5beb-11eb-ba6c-02420a0f8b69",
      • "client_state": null,
      • "connection_id": "1240401930086254526",
      • "transcription_data": {
        • "confidence": 0.977219,
        • "is_final": true,
        • "transcript": "hello this is a test speech"
        }
      },
    • "record_type": "event"
    }
}

Transcription stop

Stop real-time transcription.

SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Transcription stop 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
post/calls/{call_control_id}/actions/transcription_stop
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Transfer call

Transfer a call to a new destination. If the transfer is unsuccessful, a call.hangup webhook for the other call (Leg B) 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
  • 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
SecuritybearerAuth
Request
path Parameters
call_control_id
required
string

Unique identifier and token for controlling the call

Request Body schema: application/json
required

Transfer 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 when the transfer destination answers before bridging 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.

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.

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 to number of the original call if omitted.

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.

media_encryption
string
Default: "disabled"

Defines whether media should be encrypted on the new call leg.

Enum: "disabled" "SRTP"
media_name
string

The media_name of a file to be played back when the transfer destination answers before bridging 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.

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

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.

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

to
required
string

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

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
postBridged Post
postHangup Post
postInitiated Post
post/calls/{call_control_id}/actions/transfer
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",
  • "custom_headers": [
    • {
      • "name": "head_1",
      • "value": "val_1"
      },
    • {
      • "name": "head_2",
      • "value": "val_2"
      }
    ],
  • "from": "+18005550101",
  • "from_display_name": "Company Name",
  • "media_encryption": "SRTP",
  • "sip_auth_password": "password",
  • "sip_auth_username": "username",
  • "sip_headers": [
    • {
      • "name": "User-to-User",
      • "value": "value"
      }
    ],
  • "sip_transport_protocol": "TLS",
  • "stream_track": "both_tracks",
  • "stream_url": "wss://www.example.com/websocket",
  • "timeout_limit_secs": 60,
  • "timeout_secs": 60,
  • "to": "+18005550100 or sip:username@sip.telnyx.com",
  • "webhook_url": "https://www.example.com/server-b/",
  • "webhook_url_method": "POST"
}
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"
    }
}