This is the current API V1 documentation. Explore our API V2 if you’d like to test new features.

Overview

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

TermDescription
ConnectionUsed to configure inbound traffic and authentication for one or more phone numbers.
Outbound ProfileUsed to configure outbound traffic and billing for one or more phone numbers.
WebhookAn HTTP callback used to notify your server that you have received a message.

GUIDED EXAMPLE

Follow our guided example to set up call control, send commands and receive webhooks, using the Telnyx API.

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

  1. Start with a new connection by using the Create a new connection endpoint.

    Example Request Body:

    {
      "connection_name": "Boston Call Center"
    }
  2. 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:

  1. 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"
      }
    }
  2. Purchase your chosen phone number using the create a number order endpoint.

  3. 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_ids within 60 seconds will be ignored.

EXAMPLE: RECEIVING A WEBHOOK

  1. 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"
    }
FieldValue
record_typeDescription of the record.
idunique id for the webhook
event_typeThe type of event detected by the Telnyx system
created_atISO-8601 datetime of when event was created
toDestination number or SIP URI of the call
start_timeISO-8601 datetime of when call was received
fromNumber or SIP URI placing the call
call_control_idcall id used to issue commands via call control API
connection_idTelnyx connection id used in the call
call_leg_idID that is unique to the call and can be used to correlate webhook events
call_session_idID that is unique to the call session and can be used to correlate webhook vents
client_stateState received from a command
directionWhether the call is 'incoming' or 'outgoing'
stateWhether 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 TypeHTTP Header Format
Key + SecretAuthorization: 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 CodeMessageDescription
200OKThe request succeeded.
403ForbiddenThe request was valid, however the user is not authorized to perform this action.
404Not FoundThe requested resource could not be found.
422Invalid ParametersThe request has invalid parameters or the call is no longer active.

EXAMPLE: SENDING COMMANDS

  1. To answer the call, send a POST request to the /actions/answer endpoint as shown in the example below.
With a Key + Secret
curl -X POST \
  -u <key>:<secret> \
  https://api.telnyx.com/calls/428c31b6-7af4-4bcb-b7f5-5013ef9657c1/actions/answer

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 unique command_id parameter as part of your commands. The command_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.