Call Commands
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
Use this field to set the Billing Group ID for the call. Must be a valid and existing Billing Group ID.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Use this field to override the URL for which Telnyx will send subsuqeunt webhooks to for this call.
HTTP request type used for `webhook_url`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.answered",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
The Call Control ID of the call you want to bridge with.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
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.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.bridged",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
Dial' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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
orcall.hangup
call.machine.detection.ended
ifanswering_machine_detection
was requestedcall.machine.greeting.ended
ifanswering_machine_detection
was set todetect_beep
,greeting_end
ordetect_words
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In body
The ID of the connection to be used when dialing the destination.
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.
The DID or SIP URI to dial out to.
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.
Optional configuration parameters to modify 'answering_machine_detection' performance.
Silence duration threshold after a greeting message or voice for it be considered human.
Maximum threshold for silence between words.
Maximum threshold of a human greeting. If greeting longer than this value, considered machine.
If machine already detected, maximum threshold for silence between words. If exceeded, the greeting is considered ended.
If machine already detected, maximum timeout threshold to determine the end of the machine greeting.
If initial silence duration is greater than this value, consider it a machine.
If number of detected words is greater than this value, consder it a machine.
If a single word lasts longer than this threshold, consider it a machine.
Minimum noise threshold for any analysis.
Maximum timeout threshold for overall detection.
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.
Use this field to set the Billing Group ID for the call. Must be a valid and existing Billing Group ID.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Custom headers to be added to the SIP INVITE.
The name of the header to add.
The value of the header.
Use another call's control id for sharing the same call session id
SIP Authentication password used for SIP challenges.
SIP Authentication username used for SIP challenges.
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.
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.
Use this field to override the URL for which Telnyx will send subsuqeunt webhooks to for this call.
HTTP request type used for `webhook_url`.
Successful response with details about a call status.
Unexpected error
- JSON
- Schema
{
"data": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"call_leg_id": "2dc6fc34-f9e0-11ea-b68e-02420a0f7768",
"call_session_id": "2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768",
"is_alive": false,
"record_type": "call"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.answered",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.hangup",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.initiated",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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 start' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
The network target,
Optionally specify a media type to stream. If `decrpyted` selected, Telnyx will decrypt incoming SIP media before forking to the target. `rx` and `tx` are required fields if `decrypted` selected.
The network target,
The network target,
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"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"
}
}
{
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"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 audio' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
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.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
The number of milliseconds to wait for input between digits.
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.
The maximum number of digits to fetch. This parameter has a maximum value of 128.
The maximum number of times the file should be played if there is no input from the user on the call.
The minimum number of digits to fetch. This parameter has a minimum value of 1.
The digit used to terminate input if fewer than `maximum_digits` digits have been gathered.
The number of milliseconds to wait for a DTMF response after file playback ends before a replaying the sound file.
A list of all digits accepted as valid.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.dtmf.received",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.gather.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.playback.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.playback.started",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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 speak' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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", "language": "en-US", "voice": "female"}' \
https://api.telnyx.com/v2/calls/{call_control_id}/actions/gather_using_speak
In path
Unique identifier and token for controlling the call
In body
The language you want spoken.
The text or SSML to be converted into speech. There is a 5,000 character limit.
The gender of the voice used to speak back the text.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
The number of milliseconds to wait for input between digits.
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.
The maximum number of digits to fetch. This parameter has a maximum value of 128.
The maximum number of times that a file should be played back if there is no input from the user on the call.
The minimum number of digits to fetch. This parameter has a minimum value of 1.
The type of the provided payload. The payload can either be plain text, or Speech Synthesis Markup Language (SSML).
This parameter impacts speech quality, language options and payload types. When using `basic`, only the `en-US` language and payload type `text` are allowed.
The digit used to terminate input if fewer than `maximum_digits` digits have been gathered.
The number of milliseconds to wait for a DTMF response after speak ends before a replaying the sound file.
A list of all digits accepted as valid.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.dtmf.received",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.gather.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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/gather_stop
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.gather.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.hangup",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"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 URL' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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, andtarget_legs
is limited toself
. - A customer cannot Play Audio with
overlay=true
unless there is a Play Audio withoverlay=false
actively playing.
Expected Webhooks:
call.playback.started
call.playback.ended
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
The URL of the file to be played back on the call. The URL can point to either a WAV or MP3 file.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
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.
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.
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.
Specifies the leg or legs on which audio will be played. If supplied, the value must be either `self`, `opposite` or `both`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.playback.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.playback.started",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Use `current` to stop only the current audio or `all` to stop all audios in the queue.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.playback.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.speak.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
When `dual`, final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.
The audio file format used when storing the call recording. Can be either `mp3` or `wav`.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
If enabled, a beep sound will be played at the start of a recording.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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/record_pause
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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/record_resume
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
Cause for call rejection.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.hangup",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
DTMF digits to send. Valid digits are 0-9, A-D, *, and #. Pauses can be added using w (0.5s) and W (1s).
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Specifies for how many milliseconds each digit will be played in the audio stream. Ranges from 100 to 500ms
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{"sip_address":"sip:username@sip.non-telnyx-address.com"}' \
https://api.telnyx.com/v2/calls/{call_control_id}/actions/refer
In path
Unique identifier and token for controlling the call
In body
The SIP URI to which the call will be referred to.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded 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.
Custom headers to be added to the SIP INVITE.
The name of the header to add.
The value of the header.
SIP Authentication password used for SIP challenges.
SIP Authentication username used for SIP challenges.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.refer.completed",
"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-abf3-3bc1-b7f4-5013ef9657c1",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"connection_id": "7267xxxxxxxxxxxxxx",
"from": "+35319605860",
"sip_notify_response": 200,
"to": "+13129457420"
},
"record_type": "event"
}
}
{
"data": {
"event_type": "call.refer.failed",
"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-abf3-3bc1-b7f4-5013ef9657c1",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"connection_id": "7267xxxxxxxxxxxxxx",
"from": "+35319605860",
"sip_notify_response": 603,
"to": "+13129457420"
},
"record_type": "event"
}
}
{
"data": {
"event_type": "call.refer.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-abf3-3bc1-b7f4-5013ef9657c1",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"connection_id": "7267xxxxxxxxxxxxxx",
"from": "+35319605860",
"sip_notify_response": 100,
"to": "+13129457420"
},
"record_type": "event"
}
}
Speak text' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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", "voice": "female", "language": "en-US"}' \
https://api.telnyx.com/v2/calls/{call_control_id}/actions/speak
In path
Unique identifier and token for controlling the call
In body
The language you want spoken.
The text or SSML to be converted into speech. There is a 5,000 character limit.
The gender of the voice used to speak back the text.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
The type of the provided payload. The payload can either be plain text, or Speech Synthesis Markup Language (SSML).
This parameter impacts speech quality, language options and payload types. When using `basic`, only the `en-US` language and payload type `text` are allowed.
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.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.speak.ended",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.speak.started",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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 call' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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 Bcall.answered
orcall.hangup
call.machine.detection.ended
ifanswering_machine_detection
was requestedcall.machine.greeting.ended
ifanswering_machine_detection
was set todetect_beep
,greeting_end
ordetect_words
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
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
In path
Unique identifier and token for controlling the call
In body
The DID or SIP URI to dial out and bridge to the given call.
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.
Optional configuration parameters to modify 'answering_machine_detection' performance.
Silence duration threshold after a greeting message or voice for it be considered human.
Maximum threshold for silence between words.
Maximum threshold of a human greeting. If greeting longer than this value, considered machine.
If machine already detected, maximum threshold for silence between words. If exceeded, the greeting is considered ended.
If machine already detected, maximum timeout threshold to determine the end of the machine greeting.
If initial silence duration is greater than this value, consider it a machine.
If number of detected words is greater than this value, consder it a machine.
If a single word lasts longer than this threshold, consider it a machine.
Minimum noise threshold for any analysis.
Maximum timeout threshold for overall detection.
Audio URL to be played back when the transfer destination answers before bridging the call. The URL can point to either a WAV or MP3 file.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same `command_id`.
Custom headers to be added to the SIP INVITE.
The name of the header to add.
The value of the header.
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.
SIP Authentication password used for SIP challenges.
SIP Authentication username used for SIP challenges.
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.
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.
Use this field to override the URL for which Telnyx will send subsuqeunt webhooks to for this call.
HTTP request type used for `webhook_url`.
Successful response upon making a call control command.
Unexpected error
- JSON
- Schema
{
"data": {
"result": "ok"
}
}
- JSON
- Schema
{
"data": {
"event_type": "call.answered",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.bridged",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.hangup",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}
{
"data": {
"event_type": "call.initiated",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
"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"
}
}