This is the API V2 documentation. To switch out of beta revert back to our API V1.

Telnyx DevelopersAPI v2
Sign inTelnyx Developers
Open Menu
DocsAPI ReferenceJoin Slack Community
Create an AccountSign in
Questions on setup? Talk to our experts
Open SidemenuAPI Reference

Call Commands

Answer callCallControlAnswer

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/answer

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

Expected Webhooks:

  • call.answered
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d","command_id":"891510ac-f3e4-11e8-af5b-de00688a4901"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/answer
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Answered
{
  "data": {
    "event_type": "call.answered",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "state": "answered",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Bridge callsCallControlBridge

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/bridge

Bridge two call control calls.

Expected Webhooks:

  • call.bridged for Leg A
  • call.bridged for Leg B
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"call_control_id": "bridge_uuid"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/bridge
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
call_control_id
string
required

The Call Control ID of the call you want to bridge with.

Example: "c8ac9611-25c3-494a-b8b4-2f036a18a6b2"
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
park_after_unbridge
string
optional

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.

Example: "self"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Bridged
{
  "data": {
    "event_type": "call.bridged",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "state": "bridged",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

DialCallControlDial

post https://api.telnyx.com/v2/calls

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

Expected Webhooks:

  • call.initiated
  • call.answered or call.hangup
  • call.machine.detection.ended if answering_machine_detection was requested
  • call.machine.greeting.ended if answering_machine_detection was requested to detect the end of machine greeting
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"connection_id": "uuid", "to": "+18005550199", "from": "+18005550100"}' \
  https://api.telnyx.com/v2/calls
Parameters
In body
connection_id
string
required

The ID of the connection to be used when dialing the destination.

from
string
required

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

Example: "+18005550101"
to
string
required

The DID or SIP URI to dial out to.

Example: "+18005550100 or SIP:username@sip.telnyx.com"
answering_machine_detection
string
optional

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.

Default: "disabled"
Options: [ "detect", "detect_beep", "detect_words", "greeting_end", "disabled" ]
answering_machine_detection_config
object
optional

Optional configuration parameters to modify 'answering_machine_detection' performance.

audio_url
string
optional

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.

Example: "http://example.com/message.wav"
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
custom_headers
array of object
optional

Custom headers to be added to the SIP INVITE.

Example: [ { "name": "head_1", "value": "val_1" }, { "name": "head_2", "value": "val_2" } ]
name
string

The name of the header to add.

Example: "head_1"
value
string

The value of the header.

Example: "val_1"
link_to
string
optional

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

Example: "ilditnZK_eVysupV21KzmzN_sM29ygfauQojpm4BgFtfX5hXAcjotg=="
sip_auth_password
string
optional

SIP Authentication password used for SIP challenges.

sip_auth_username
string
optional

SIP Authentication username used for SIP challenges.

time_limit_secs
integer (int32)
optional

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.

Default: 14400
Example: 600
timeout_secs
integer (int32)
optional

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.

Default: 30
Example: 60
Responses
200

Retrieve call status response

default

Unexpected error

Success Response
{
  "data": {
    "call_control_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
    "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
    "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
    "is_alive": true,
    "record_type": "call"
  }
}
Expected Webhooks
call Answered
{
  "data": {
    "event_type": "call.answered",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "state": "answered",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Hangup
{
  "data": {
    "event_type": "call.hangup",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "hangup_cause": "call_rejected",
      "hangup_source": "caller",
      "sip_hangup_cause": "603",
      "state": "hangup",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Initiated
{
  "data": {
    "event_type": "call.initiated",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "direction": "incoming",
      "from": "+35319605860",
      "state": "parked",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Machine Detection Ended
{
  "data": {
    "event_type": "call.machine.detection.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "result": "machine",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Machine Greeting Ended
{
  "data": {
    "event_type": "call.machine.greeting.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "result": "ended",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Forking startCallControlForkStart

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/fork_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.
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"target": "udp:192.0.2.1:9000"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/fork_start
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
rx
string
optional

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

Example: "192.0.2.1:9000"
target
string
optional

The network target, , 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.

Example: "udp:192.0.2.1:9000"
tx
string
optional

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

Example: "192.0.2.1:9001"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Fork Started
{
  "data": {
    "event_type": "call.fork.started",
    "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-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}
call Fork Stopped
{
  "data": {
    "event_type": "call.fork.stopped",
    "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-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}

Forking stopCallControlForkStop

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/fork_stop

Stop forking a call.

Expected Webhooks:

  • call.fork.stopped
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d","command_id":"891510ac-f3e4-11e8-af5b-de00688a4901"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/fork_stop
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Fork Stopped
{
  "data": {
    "event_type": "call.fork.stopped",
    "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-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}

Gather using audioCallControlGatherUsingAudio

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/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 AnswerAPI 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
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"audio_url": "http://example.com/message.wav"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/gather_using_audio
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
audio_url
string
required

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.

Example: "http://example.com/message.wav"
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
inter_digit_timeout_millis
integer (int32)
optional

The number of milliseconds to wait for input between digits.

Default: 5000
Example: 10000
invalid_audio_url
string
optional

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.

Example: "http://example.com/invalid.wav"
maximum_digits
integer (int32)
optional

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

Default: 128
Example: 10
maximum_tries
integer (int32)
optional

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

Default: 3
Example: 3
minimum_digits
integer (int32)
optional

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

Default: 1
Example: 1
terminating_digit
string
optional

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

Default: "#"
Example: "#"
timeout_millis
integer (int32)
optional

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

Default: 60000
Example: 60000
valid_digits
string
optional

A list of all digits accepted as valid.

Default: "0123456789#*"
Example: "123"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Dtmf Received
{
  "data": {
    "event_type": "call.dtmf.received",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "digit": "#",
      "from": "+35319605860",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Gather Ended
{
  "data": {
    "event_type": "call.gather.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "digits": "5503",
      "from": "+35319605860",
      "status": "valid",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Playback Ended
{
  "data": {
    "event_type": "call.playback.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "media_url": "http://example.com/audio.wav",
      "overlay": "false",
      "status": "valid"
    },
    "record_type": "event"
  }
}
call Playback Started
{
  "data": {
    "event_type": "call.playback.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "media_url": "http://example.com/audio.wav",
      "overlay": "false"
    },
    "record_type": "event"
  }
}

Gather using speakCallControlGatherUsingSpeak

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/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 AnswerAPI 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
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"payload": "Say this on the call"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/gather_using_speak
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
language
string
required

The language you want spoken.

Example: "en-US"
Options: [ "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
string
required

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

Example: "Say this on the call"
voice
string
required

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

Example: "female"
Options: [ "male", "female" ]
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
inter_digit_timeout_millis
integer (int32)
optional

The number of milliseconds to wait for input between digits.

Default: 5000
Example: 10000
invalid_payload
string
optional

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 5,000 character limit.

Example: "Say this on the call"
maximum_digits
integer (int32)
optional

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

Default: 128
Example: 10
maximum_tries
integer (int32)
optional

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

Default: 3
Example: 3
minimum_digits
integer (int32)
optional

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

Default: 1
Example: 1
payload_type
string
optional

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

Default: "text"
Example: "ssml"
Options: [ "text", "ssml" ]
service_level
string
optional

This parameter impacts speech quality, language options and payload types. When using `basic`, only the `en-US` language and payload type `text` are allowed.

Default: "premium"
Example: "premium"
Options: [ "basic", "premium" ]
terminating_digit
string
optional

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

Default: "#"
Example: "#"
timeout_millis
integer (int32)
optional

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

Default: 60000
Example: 60000
valid_digits
string
optional

A list of all digits accepted as valid.

Default: "0123456789#*"
Example: "123"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Dtmf Received
{
  "data": {
    "event_type": "call.dtmf.received",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "digit": "#",
      "from": "+35319605860",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Gather Ended
{
  "data": {
    "event_type": "call.gather.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "digits": "5503",
      "from": "+35319605860",
      "status": "valid",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Hangup callCallControlHangup

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/hangup

Hang up the call.

Expected Webhooks:

  • call.hangup
  • call.recording.saved
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d","command_id":"891510ac-f3e4-11e8-af5b-de00688a4901"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/hangup
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Hangup
{
  "data": {
    "event_type": "call.hangup",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "hangup_cause": "call_rejected",
      "hangup_source": "caller",
      "sip_hangup_cause": "603",
      "state": "hangup",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Recording Saved
{
  "data": {
    "event_type": "call.recording.saved",
    "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-abf3-3bc1-b7f4-5013ef9657c1",
      "channels": "single",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "public_recording_urls": {
        "mp3": "http://example.com/recording.mp3",
        "wav": "http://example.com/recording.wav"
      },
      "recording_ended_at": "2018-02-02T22:25:27.521992Z",
      "recording_started_at": "2018-02-02T22:20:27.521992Z",
      "recording_urls": {
        "mp3": "http://example.com/recording.mp3",
        "wav": "http://example.com/recording.wav"
      }
    },
    "record_type": "event"
  }
}

Play audio URLCallControlPlaybackStart

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/playback_start

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, loop is limited to 1, and target_legs is limited to self.
  • A customer cannot Play Audio with overlay=true unless there is a Play Audio with overlay=false actively playing.

Expected Webhooks:

  • call.playback.started
  • call.playback.ended
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"audio_url": "http://www.example.com/sounds/greeting.wav"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/playback_start
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
audio_url
string
required

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

Example: "http://www.example.com/sounds/greeting.wav"
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
loop
string
optional

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

Default: 1
Example: "infinity"
overlay
boolean
optional

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.

Default: "false"
Example: "true"
stop
string
optional

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.

Example: "current"
target_legs
string
optional

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

Default: "self"
Example: "self"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Playback Ended
{
  "data": {
    "event_type": "call.playback.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "media_url": "http://example.com/audio.wav",
      "overlay": "false",
      "status": "valid"
    },
    "record_type": "event"
  }
}
call Playback Started
{
  "data": {
    "event_type": "call.playback.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "media_url": "http://example.com/audio.wav",
      "overlay": "false"
    },
    "record_type": "event"
  }
}

Stop audio playbackCallControlPlaybackStop

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/playback_stop

Stop audio being played on the call.

Expected Webhooks:

  • call.playback.ended or call.speak.ended
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d","command_id":"891510ac-f3e4-11e8-af5b-de00688a4901"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/playback_stop
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
stop
string
optional

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

Default: "all"
Example: "current"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Playback Ended
{
  "data": {
    "event_type": "call.playback.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "media_url": "http://example.com/audio.wav",
      "overlay": "false",
      "status": "valid"
    },
    "record_type": "event"
  }
}
call Speak Ended
{
  "data": {
    "event_type": "call.speak.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "status": "completed"
    },
    "record_type": "event"
  }
}

Recording startCallControlRecordStart

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/record_start

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

Expected Webhooks:

There are no webhooks associated with this Command.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"format": "mp3", "channels": "single"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/record_start
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
channels
string
required

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

Example: "single"
Options: [ "single", "dual" ]
format
string
required

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

Example: "mp3"
Options: [ "wav", "mp3" ]
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
play_beep
boolean
optional

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

Example: true
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}

Recording stopCallControlRecordStop

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/record_stop

Stop recording the call.

Expected Webhooks:

  • call.recording.saved
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"format": "mp3", "channels": "single"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/record_stop
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Recording Saved
{
  "data": {
    "event_type": "call.recording.saved",
    "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-abf3-3bc1-b7f4-5013ef9657c1",
      "channels": "single",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "public_recording_urls": {
        "mp3": "http://example.com/recording.mp3",
        "wav": "http://example.com/recording.wav"
      },
      "recording_ended_at": "2018-02-02T22:25:27.521992Z",
      "recording_started_at": "2018-02-02T22:20:27.521992Z",
      "recording_urls": {
        "mp3": "http://example.com/recording.mp3",
        "wav": "http://example.com/recording.wav"
      }
    },
    "record_type": "event"
  }
}

Reject callCallControlReject

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/reject

Reject an incoming call.

Expected Webhooks:

  • call.hangup
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"cause":"USER_BUSY","client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/reject
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
cause
string
optional

Cause for call rejection.

Default: "none"
Example: "USER_BUSY"
Options: [ "CALL_REJECTED", "USER_BUSY" ]
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Hangup
{
  "data": {
    "event_type": "call.hangup",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "hangup_cause": "call_rejected",
      "hangup_source": "caller",
      "sip_hangup_cause": "603",
      "state": "hangup",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Send DTMFCallControlSendDTMF

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/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.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"digits": "1www2WABCDw9"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/send_dtmf
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
digits
string
required

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

Example: "1www2WABCDw9"
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
duration_millis
integer (int32)
optional

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

Default: 250
Example: 500
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}

Speak textCallControlSpeak

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/speak

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
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"payload": "Say this on the call"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/speak
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
language
string
required

The language you want spoken.

Example: "en-US"
Options: [ "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
string
required

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

Example: "Say this on the call"
voice
string
required

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

Example: "female"
Options: [ "male", "female" ]
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
payload_type
string
optional

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

Default: "text"
Example: "ssml"
Options: [ "text", "ssml" ]
service_level
string
optional

This parameter impacts speech quality, language options and payload types. When using `basic`, only the `en-US` language and payload type `text` are allowed.

Default: "premium"
Example: "premium"
Options: [ "basic", "premium" ]
stop
string
optional

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.

Default: null
Example: "current"
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Speak Ended
{
  "data": {
    "event_type": "call.speak.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "status": "completed"
    },
    "record_type": "event"
  }
}
call Speak Started
{
  "data": {
    "event_type": "call.speak.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}

Transfer callCallControlTransfer

post https://api.telnyx.com/v2/calls/{call_control_id}/actions/transfer

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

Expected Webhooks:

  • call.initiated
  • call.bridged to Leg B
  • call.answered or call.hangup
  • call.machine.detection.ended if answering_machine_detection was requested
  • call.machine.greeting.ended if answering_machine_detection was requested to detect the end of machine greeting
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"to": "+18005550101"}' \
  https://api.telnyx.com/v2/calls/{call_control_id}/actions/transfer
Parameters
In path
call_control_id
string
required

Unique identifier and token for controlling the call

In body
to
string
required

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

Example: "+18005550100 or SIP:username@sip.telnyx.com"
answering_machine_detection
string
optional

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.

Default: "disabled"
Options: [ "detect", "detect_beep", "detect_words", "greeting_end", "disabled" ]
answering_machine_detection_config
object
optional

Optional configuration parameters to modify 'answering_machine_detection' performance.

audio_url
string
optional

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

Example: "http://www.example.com/sounds/greeting.wav"
client_state
string
optional

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

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
custom_headers
array of object
optional

Custom headers to be added to the SIP INVITE.

Example: [ { "name": "head_1", "value": "val_1" }, { "name": "head_2", "value": "val_2" } ]
name
string

The name of the header to add.

Example: "head_1"
value
string

The value of the header.

Example: "val_1"
from
string
optional

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

Example: "+18005550101"
sip_auth_password
string
optional

SIP Authentication password used for SIP challenges.

Example: "password"
sip_auth_username
string
optional

SIP Authentication username used for SIP challenges.

Example: "username"
time_limit_secs
integer (int32)
optional

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.

Default: 14400
Example: 600
timeout_secs
integer (int32)
optional

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.

Default: 30
Example: 60
Responses
200

Command response

default

Unexpected error

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
call Answered
{
  "data": {
    "event_type": "call.answered",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "state": "answered",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Bridged
{
  "data": {
    "event_type": "call.bridged",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "state": "bridged",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Hangup
{
  "data": {
    "event_type": "call.hangup",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "hangup_cause": "call_rejected",
      "hangup_source": "caller",
      "sip_hangup_cause": "603",
      "state": "hangup",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}
call Initiated
{
  "data": {
    "event_type": "call.initiated",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "direction": "incoming",
      "from": "+35319605860",
      "state": "parked",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Was this section helpful?was-this-page-helpful