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