Overview

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

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

   Copy Code

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

   Copy Code

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

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.

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.

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:

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