Sending Commands for Programmable Voice

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.

Authenticating your Call Control Command Request

Like all other Telnyx API V2 requests, you must authenticate your Call Control command requests by sending the Authorization header with a value of an API Key. You can read more about API Keys here.


Credential Type	HTTP Header Format
API Key	Authorization: Bearer YOUR_API_KEY

Example: 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.

Copy

Copied

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  https://api.telnyx.com/v2/calls/428c31b6-7af4-4bcb-b7f5-5013ef9657c1/actions/answer

Note: After pasting the above content, Kindly check and remove any new line added

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` `call.answered` or `call.hangup` `call.machine.detection.ended` - if `answering_machine_detection` was requested `call.machine.greeting.ended` - if `answering_machine_detection` was requested to detect the end of machine greeting
Forking start	`call.fork.started` `call.fork.stopped`
Forking stop	`call.fork.stopped`
Gather using audio	`call.playback.started` `call.playback.ended` `call.dtmf.received` - you may receive many of these webhooks `call.gather.ended`
Gather using speak	`call.dtmf.received` - you may receive many of these webhooks `call.gather.ended`
Hangup	`call.hangup` `call.recording.saved` - if the call is being recorded
Play audio url	`call.playback.started` `call.playback.ended`
Playback stop command	`call.playback.ended` or `call.speak.ended`
Recording start	no webhooks
Recording stop	`call.recording.saved`
Reject call	`call.hangup`
Send DTMF	no webhooks
Speak text	`call.speak.started` `call.speak.ended`
Transfer call	`call.initiated` `call.bridged` to Leg B `call.answered` or `call.hangup`

Response when Sending Call Control 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.