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

Open SidemenuDocs
Docs
Close Sidemenu

Sending Commandssending-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.

Authenticationauthentication

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 v1, or via the Telnyx API.

Credential Type HTTP Header Format
Key + Secret Authorization: Basic base64("<key>:<secret>")

Example: Sending Commands With a Key + Secretexample--sending-commands-with-a-key---secret

To answer the call, send a POST request to the /actions/answer endpoint as shown in the example below.

curl -X POST \
  -u <key>:<secret> \
  https://api.telnyx.com/calls/428c31b6-7af4-4bcb-b7f5-5013ef9657c1/actions/answer

Available Commands and their Expected Webhooksavailable-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 Commandsresponse-when-sending-commands

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.