Skip to main content

Sending Commands for Programmable Voice

A Voice API 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 Voice API command request

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

Credential TypeHTTP Header Format
API KeyAuthorization: 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" \

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

CommandExpected Webhooks
Answer callcall.answered
Bridge call

call.bridged for Leg A call.bridged for Leg B


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 startcall.fork.startedcall.fork.stopped
Forking stopcall.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


call.hangup call.recording.saved - if the call is being recorded

Play audio urlcall.playback.startedcall.playback.ended
Playback stop commandcall.playback.ended or call.speak.ended
Recording startno webhooks
Recording stopcall.recording.saved
Reject callcall.hangup
Send DTMFno webhooks
Speak textcall.speak.startedcall.speak.ended
Transfer call

call.initiated call.bridged to Leg B call.answered or call.hangup

Response when sending Voice API commands

When you send a Voice API 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.

On this page