The Call Control API allows users to control call flow.
HTTP ENDPOINTS
https://api.telnyx.com/calls/
https://api.telnyx.com/calls/{call_control_id}/actions/answer
https://api.telnyx.com/calls/{call_control_id}/actions/fork_start
https://api.telnyx.com/calls/{call_control_id}/actions/fork_stop
https://api.telnyx.com/calls/{call_control_id}/actions/gather
https://api.telnyx.com/calls/{call_control_id}/actions/hangup
https://api.telnyx.com/calls/{call_control_id}/actions/playback_start
https://api.telnyx.com/calls/{call_control_id}/actions/record_start
https://api.telnyx.com/calls/{call_control_id}/actions/record_stop
https://api.telnyx.com/calls/{call_control_id}/actions/transfer
Getting Started with Call Control
REQUIREMENTS
Inbound calls require a DID or toll-free number purchased from or ported into the Telnyx platform. Outbound-only calls can be initiated without the purchase or porting of a number.
CONFIGURATION AND USAGE
Telnyx Programmatic Call Control is enabled using Connections. You can set up several connections to differentiate between use cases.
Outbound calls, initiated through the Dial and Transfer commands, are configured through an Outbound Profile that must be created and associated with the connection. The outbound profile allows you to initiate outbound traffic, and configure how that traffic is charged, managed and to which destinations it is permitted.
To issue call control commands, use our HTTPS API and authenticate using the API Key/Secret associated with your Mission Control account under API Keys.
To receive call control webhooks, set the webhook URL on your call control connection to a publicly accessible endpoint on your server.
GLOSSARY
Term | Description |
---|---|
Connection | Used to configure inbound traffic and authentication for one or more phone numbers. |
Outbound Profile | Used to configure outbound traffic and billing for one or more phone numbers. |
Webhook | An HTTP callback used to notify your server that you have received a message. |
Setting Up Call Control
1. Set up a Connection
To use Call Control, first create a connection, and set the authentication type to Call Control.
2. Assign a Number to a Call Control Connection
Either use the Numbers API to search for and purchase a number or use the Number Porting API to port one of your existing numbers to Telnyx. Once your number has been purchased or ported, assign it to the connection.
3. Set up an Outbound Profile and Assign a Call Control Connection
To use the Dial and Transfer commands, you must first create an Outbound Profile and assign your call control connection to it.
Example: Set up a connection
Start with a new connection by using the Create a new connection endpoint.
Example Request Body:
{ "connection_name": "Boston Call Center" }
Set the connection authentication type to call control using the call control connection authentication endpoint. For testing purposes, you can set the webhook URL using an endpoint you create at https://hookbin.com.
Example: Purchase a phone number:
Choose an available phone number using the number search endpoint to search for a number.
Example Request Body:
{ "search_type": 2, "search_descriptor": { "state": "MA", "city": "Boston", "country_iso": "US" } }
Purchase your chosen phone number using the create a number order endpoint.
- Update the number to associate it with the connection that you created earlier, i.e. “Boston Call Center”.
Receiving Webhooks
When you send a call control command and receive a successful response (i.e. 200 OK), you can expect to receive a webhook. The webhook will be delivered to the primary URL specified on the call control connection associated with the call. If that URL does not resolve, or your application returns a non 200 OK response, the webhook will be delivered to the failover URL, if one has been specified.
In order to minimize webhook delivery time, Telnyx:
- does not enforce the order in which webhooks are delivered
- retries webhook delivery if your application does not respond within a certain time threshold.
As a result, you may encounter:
- out-of-order webhooks
- simultaneous (or near simultaneous) webhooks
- duplicate webhooks
Duplicate webhooks may cause your application to issue duplicate commands.
You can instruct Telnyx to ignore duplicate commands by sending a command_id
parameter as part of your commands.
Commands with duplicate command_id
s within 60 seconds will be ignored.
EXAMPLE: RECEIVING A WEBHOOK
- When you place an incoming call to a number associated with your call control connection, you will receive a callback for the incoming call. It should look something like the JSON below:
{
"record_type": "event",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"event_type": "call_initiated",
"created_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"to": "+12025550131",
"start_time": "2018-02-02T22:25:27.521992Z",
"from": "+1-202-555-0133",
"call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
"connection_id": "7267xxxxxxxxxxxxxx",
"call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
"call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"direction": "incoming",
"state": "parked"
}
Field | Value |
---|---|
record_type | Description of the record. |
id | unique id for the webhook |
event_type | The type of event detected by the Telnyx system |
created_at | ISO-8601 datetime of when event was created |
to | Destination number or SIP URI of the call |
start_time | ISO-8601 datetime of when call was received |
from | Number or SIP URI placing the call |
call_control_id | call id used to issue commands via call control API |
connection_id | Telnyx connection id used in the call |
call_leg_id | ID that is unique to the call and can be used to correlate webhook events |
call_session_id | ID that is unique to the call session and can be used to correlate webhook vents |
client_state | State received from a command |
direction | Whether the call is 'incoming' or 'outgoing' |
state | Whether the call is in 'bridging' or 'parked' state |
Sending Commands
A Call Control command is sent with a call_control_id. The call_control_id allows a user to communicate to Telnyx the call_leg the user wants to control. It also helps Telnyx route the call to the location where the call is being managed, resulting in the lowest possible latency for Call Control interactions.
Authentication
To send a Call Control command from your application, you must authenticate your request by sending the Authorization header with a value of a key:secret pair. A key and secret can be retrieved from Auth in the Mission Control Portal under the tab Auth v2, or via the Telnyx API.
Credential Type | HTTP Header Format |
---|---|
Key + Secret | Authorization: Basic base64(" |
Available Commands and their Expected Webhooks
Telnyx offers a broad range of commands to enable granular control of your call flows. Below are a list of those commands, and the webhooks the Telnyx Call Control platform will always send in response. When multiple webhooks are listed, you can expect to often, though not always, receive webhooks in the order provided.
Command | Expected Webhooks |
---|---|
Answer call | Call_answered |
Bridge call | Call_bridged for Leg A Call_bridged for Leg B |
Dial | Call_initiated You will receive either a Call_answered webhook or a Call_hangup webhook. |
Forking start | There are no webhooks associated with this command. |
Forking stop | There are no webhooks associated with this command. |
Gather using audio | Playback_started Playback_ended DTMF (you may receive many of these webhooks) Gather ended |
Gather using speak | DTMF (you may receive many of these webhooks) Gather ended |
Hangup | Call hangup Recording saved (Only applies if the call is being recorded) |
Play audio url | Playback_started Playback_ended |
Playback stop command | You will either receive a Playback_ended webhook or a Speak ended webhook |
Recording start | There are no webhooks associated with this command. |
Recording stop | Recording saved |
Reject call | Call hangup |
Send DTMF | There are no webhooks associated with this command. |
Speak text | Speak started Speak ended |
Transfer call | Call initiated Call_bridged for Leg B You will receive either a Call_answered webhook or a Call_hangup webhook. |
Response when sending command
When you send a Call Control Command, you will immediately receive an http response. Responses include, but are not limited to:
HTTP Status Code | Message | Description |
---|---|---|
200 | OK | The request succeeded. |
403 | Forbidden | The request was valid, however the user is not authorized to perform this action. |
404 | Not Found | The requested resource could not be found. |
422 | Invalid Parameters | The request has invalid parameters or the call is no longer active. |
Command Retries
User Applications may encounter the following situations:
- 5XX Error: Telnyx actively monitors and alerts on the rate of 500, 501, 503, or 504 errors
- Duplicate Webhooks: Identical webhooks may occasionally be delivered.
Telnyx carefully monitors the Call Control platform for 5XX errors, latency, and duplicate webhooks, and actively works to keep all of these to a minimum.
However, no system is perfect, and so we Telnyx recommends users design their applications to do the following:
command_id
: send a uniquecommand_id
parameter as part of your commands. Thecommand_id
must be unique for each command. We suggest using UUIDv4.- Retry on 5XX Errors: If your application receives a 500 error, immediately retry the command
- Retry on Latency >500ms: If your application fails to receive a HTTP response from Telnyx within 500ms, send an identical command.