Dial

POST

/calls

Call Commands

Dial a number or SIP URI from a given connection. A successful response will include a call_leg_id which can be used to correlate the command with subsequent webhooks.

Expected Webhooks (see schema below):

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

call.machine.premium.detection.ended if answering_machine_detection=premium was requested

call.machine.premium.greeting.ended if answering_machine_detection=premium was requested and a beep was detected

streaming.started, streaming.stopped or streaming.failed if stream_url was set

When the record parameter is set to record-from-answer, the response will include a recording_id field.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/calls' \
--header 'Content-Type: application/json' \
--data-raw '{
    "answering_machine_detection": "detect",
    "answering_machine_detection_config": {
        "after_greeting_silence_millis": 1000,
        "between_words_silence_millis": 1000,
        "greeting_duration_millis": 1000,
        "greeting_silence_duration_millis": 2000,
        "greeting_total_analysis_time_millis": 50000,
        "initial_silence_millis": 1000,
        "maximum_number_of_words": 1000,
        "maximum_word_length_millis": 2000,
        "silence_threshold": 512,
        "total_analysis_time_millis": 5000
    },
    "audio_url": "http://www.example.com/sounds/greeting.wav",
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
    "conference_config": {
        "conference_name": "telnyx-conference",
        "start_conference_on_enter": true
    },
    "connection_id": "7267xxxxxxxxxxxxxx",
    "custom_headers": [
        {
            "name": "head_1",
            "value": "val_1"
        },
        {
            "name": "head_2",
            "value": "val_2"
        }
    ],
    "dialogflow_config": {
        "analyze_sentiment": false,
        "partial_automated_agent_reply": false
    },
    "enable_dialogflow": false,
    "from": "+18005550101",
    "from_display_name": "Company Name",
    "link_to": "ilditnZK_eVysupV21KzmzN_sM29ygfauQojpm4BgFtfX5hXAcjotg==",
    "media_encryption": "SRTP",
    "send_silence_when_idle": true,
    "sip_auth_password": "password",
    "sip_auth_username": "username",
    "sip_headers": [
        {
            "name": "User-to-User",
            "value": "12345"
        }
    ],
    "sip_transport_protocol": "TLS",
    "stream_track": "both_tracks",
    "stream_url": "wss://www.example.com/websocket",
    "timeout_limit_secs": 60,
    "timeout_secs": 60,
    "to": "+18005550100 or sip:username@sip.telnyx.com",
    "webhook_url": "https://www.example.com/server-b/",
    "webhook_url_method": "POST"
}'

Response Example

200 - Example 1

{
    "data": {
        "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
        "call_duration": 50,
        "call_leg_id": "2dc6fc34-f9e0-11ea-b68e-02420a0f7768",
        "call_session_id": "2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "end_time": "2019-01-23T18:11:52.574Z",
        "is_alive": false,
        "record_type": "call",
        "recording_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a",
        "start_time": "2019-01-23T18:10:02.574Z"
    }
}

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

answering_machine_detection

enum<string>

optional

Enables Answering Machine Detection. Telnyx offers Premium and Standard detections. With Premium detection, when a call is answered, Telnyx runs real-time detection and sends a call.machine.premium.detection.ended webhook with one of the following results: human_residence, human_business, machine, silence or fax_detected. If we detect a beep, we also send a call.machine.premium.greeting.ended webhook with the result of beep_detected. If we detect a beep before call.machine.premium.detection.ended we only send call.machine.premium.greeting.ended, and if we detect a beep after call.machine.premium.detection.ended, we send both webhooks. With Standard detection, when a call is answered, Telnyx runs real-time detection to determine if it was picked up by a human or a machine and sends an call.machine.detection.ended webhook with the analysis result. If greeting_end or detect_words is used and a machine is detected, you will receive another call.machine.greeting.ended webhook when the answering machine greeting ends with a beep or silence. If detect_beep is used, you will only receive call.machine.greeting.ended if a beep is detected.

Allowed values:

premiumdetectdetect_beepdetect_wordsgreeting_enddisabled

Default:

disabled

answering_machine_detection_config

object

optional

Optional configuration parameters to modify 'answering_machine_detection' performance.

after_greeting_silence_millis

integer <int32>

optional

Silence duration threshold after a greeting message or voice for it be considered human.

Default:

800

Example:

1000

between_words_silence_millis

integer <int32>

optional

Maximum threshold for silence between words.

Default:

Example:

100

greeting_duration_millis

integer <int32>

optional

Maximum threshold of a human greeting. If greeting longer than this value, considered machine.

Default:

3500

Example:

1500

greeting_silence_duration_millis

integer <int32>

optional

If machine already detected, maximum threshold for silence between words. If exceeded, the greeting is considered ended.

Default:

1500

Example:

2000

greeting_total_analysis_time_millis

integer <int32>

optional

If machine already detected, maximum timeout threshold to determine the end of the machine greeting.

Default:

5000

Example:

7500

initial_silence_millis

integer <int32>

optional

If initial silence duration is greater than this value, consider it a machine.

Default:

3500

Example:

1800

maximum_number_of_words

integer <int32>

optional

If number of detected words is greater than this value, consder it a machine.

Default:

Example:

maximum_word_length_millis

integer <int32>

optional

If a single word lasts longer than this threshold, consider it a machine.

Default:

3500

Example:

2000

silence_threshold

integer <int32>

optional

Minimum noise threshold for any analysis.

Default:

256

Example:

512

total_analysis_time_millis

integer <int32>

optional

Maximum timeout threshold for overall detection.

Default:

3500

Example:

5000

audio_url

string

optional

The URL of a file to be played back to the callee when the call is answered. The URL can point to either a WAV or MP3 file. media_name and audio_url cannot be used together in one request.

Example:

http://example.com/message.wav

billing_group_id

string <uuid>

optional

Use this field to set the Billing Group ID for the call. Must be a valid and existing Billing Group ID.

Example:

f5586561-8ff0-4291-a0ac-84fe544797bd

client_state

string

optional

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example:

aGF2ZSBhIG5pY2UgZGF5ID1d

command_id

string

optional

Use this field to avoid duplicate commands. Telnyx will ignore others Dial commands with the same command_id.

Example:

891510ac-f3e4-11e8-af5b-de00688a4901

conference_config

object

optional

Optional configuration parameters to dial new participant into a conference.

beep_enabled

enum<string>

optional

Whether a beep sound should be played when the participant joins and/or leaves the conference. Can be used to override the conference-level setting.

Allowed values:

alwaysneveron_enteron_exit

Example:

on_exit

conference_name

string

optional

Conference name to be joined

Example:

telnyx-conference

early_media

boolean

optional

Controls the moment when dialled call is joined into conference. If set to true user will be joined as soon as media is available (ringback). If false user will be joined when call is answered. Defaults to true

Default:

true

Example:

false

end_conference_on_exit

boolean

optional

Whether the conference should end and all remaining participants be hung up after the participant leaves the conference. Defaults to "false".

Example:

true

hold

boolean

optional

Whether the participant should be put on hold immediately after joining the conference. Defaults to "false".

Example:

true

hold_audio_url

string

optional

The URL of a file to be played to the participant when they are put on hold after joining the conference. hold_media_name and hold_audio_url cannot be used together in one request. Takes effect only when "start_conference_on_create" is set to "false". This property takes effect only if "hold" is set to "true".

Example:

http://example.com/message.wav

hold_media_name

string

optional

The media_name of a file to be played to the participant when they are put on hold after joining the conference. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file. Takes effect only when "start_conference_on_create" is set to "false". This property takes effect only if "hold" is set to "true".

Example:

my_media_uploaded_to_media_storage_api

string <uuid>

optional

Conference ID to be joined

Example:

0ccc7b54-4df3-4bca-a65a-3da1ecc777f0

mute

boolean

optional

Whether the participant should be muted immediately after joining the conference. Defaults to "false".

Example:

true

soft_end_conference_on_exit

boolean

optional

Whether the conference should end after the participant leaves the conference. NOTE this doesn't hang up the other participants. Defaults to "false".

Example:

true

start_conference_on_create

boolean

optional

Whether the conference should be started on creation. If the conference isn't started all participants that join are automatically put on hold. Defaults to "true".

Example:

false

start_conference_on_enter

boolean

optional

Whether the conference should be started after the participant joins the conference. Defaults to "false".

Example:

true

supervisor_role

enum<string>

optional

Sets the joining participant as a supervisor for the conference. A conference can have multiple supervisors. "barge" means the supervisor enters the conference as a normal participant. This is the same as "none". "monitor" means the supervisor is muted but can hear all participants. "whisper" means that only the specified "whisper_call_control_ids" can hear the supervisor. Defaults to "none".

Allowed values:

bargemonitornonewhisper

Example:

whisper

whisper_call_control_ids

array[string]

optional

Array of unique call_control_ids the joining supervisor can whisper to. If none provided, the supervisor will join the conference as a monitoring participant only.

Example:

["v2:Sg1xxxQ_U3ixxxyXT_VDNI3xxxazZdg6Vxxxs4-GNYxxxVaJPOhFMRQ","v2:qqpb0mmvd-ovhhBr0BUQQn0fld5jIboaaX3-De0DkqXHzbf8d75xkw"]

connection_id

string

required

The ID of the Call Control App (formerly ID of the connection) to be used when dialing the destination.

custom_headers

array[object (Custom SIP Header) {2}]

optional

Custom headers to be added to the SIP INVITE.

Example:

[{"name":"head_1","value":"val_1"},{"name":"head_2","value":"val_2"}]

name

string

required

The name of the header to add.

Example:

head_1

value

string

required

The value of the header.

Example:

val_1

dialogflow_config

object (Dialogflow Config)

optional

analyze_sentiment

boolean

optional

Enable sentiment analysis from Dialogflow.

Default:

false

Example:

true

partial_automated_agent_reply

boolean

optional

Enable partial automated agent reply from Dialogflow.

Default:

false

Example:

true

enable_dialogflow

boolean

optional

Enables Dialogflow for the current call. The default value is false.

Default:

false

Example:

true

from

string

required

The from number to be used as the caller id presented to the destination (to number). The number should be in +E164 format.

Example:

+18005550101

from_display_name

string

optional

The from_display_name string to be used as the caller id name (SIP From Display Name) presented to the destination (to number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the from field.

Example:

Company Name

link_to

string

optional

Use another call's control id for sharing the same call session id

Example:

ilditnZK_eVysupV21KzmzN_sM29ygfauQojpm4BgFtfX5hXAcjotg==

media_encryption

enum<string>

optional

Defines whether media should be encrypted on the call.

Allowed values:

disabledSRTPDTLS

Default:

disabled

media_name

string

optional

The media_name of a file to be played back to the callee when the call is answered. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file.

Example:

my_media_uploaded_to_media_storage_api

preferred_codecs

string

optional

The list of comma-separated codecs in a preferred order for the forked media to be received.

Example:

G722,PCMU,PCMA,G729,OPUS,VP8,H264

record

enum<string>

optional

Start recording automatically after an event. Disabled by default.

Allowed value:

record-from-answer

Example:

record-from-answer

record_channels

enum<string>

optional

Defines which channel should be recorded ('single' or 'dual') when record is specified.

Allowed values:

singledual

Default:

dual

Example:

single

record_custom_file_name

string

optional

The custom recording file name to be used instead of the default call_leg_id. Telnyx will still add a Unix timestamp suffix.

>= 1 characters<= 40 characters

Example:

my_recording_file_name

record_format

enum<string>

optional

Defines the format of the recording ('wav' or 'mp3') when record is specified.

Allowed values:

wavmp3

Default:

mp3

Example:

wav

record_max_length

integer <int32>

optional

Defines the maximum length for the recording in seconds when record is specified. The minimum value is 0. The maximum value is 43200. The default value is 0 (infinite).

Default:

Example:

1000

record_timeout_secs

integer <int32>

optional

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected when record is specified. The timer only starts when the speech is detected. Please note that call transcription is used to detect silence and the related charge will be applied. The minimum value is 0. The default value is 0 (infinite).

Default:

Example:

100

record_track

enum<string>

optional

The audio track to be recorded. Can be either both, inbound or outbound. If only single track is specified (inbound, outbound), channels configuration is ignored and it will be recorded as mono (single channel).

Allowed values:

bothinboundoutbound

Default:

both

Example:

outbound

record_trim

enum<string>

optional

When set to trim-silence, silence will be removed from the beginning and end of the recording.

Allowed value:

trim-silence

Example:

trim-silence

send_silence_when_idle

boolean

optional

Generate silence RTP packets when no transmission available.

Default:

false

Example:

true

sip_auth_password

string

optional

SIP Authentication password used for SIP challenges.

sip_auth_username

string

optional

SIP Authentication username used for SIP challenges.

sip_headers

array[object (SIP Header) {2}]

optional

SIP headers to be added to the SIP INVITE request. Currently only User-to-User header is supported.

Example:

[{"name":"User-to-User","value":"value"}]

name

enum<string>

required

The name of the header to add.

Allowed value:

User-to-User

Example:

User-to-User

value

string

required

The value of the header.

Example:

value

sip_transport_protocol

enum<string>

optional

Defines SIP transport protocol to be used on the call.

Allowed values:

UDPTCPTLS

Default:

UDP

sound_modifications

object (Sound modifications)

optional

Use this field to modify sound effects, for example adjust the pitch.

Example:

{"octaves":0.1,"pitch":"0.8","semitone":-2,"track":"both"}

octaves

number <double>

optional

Adjust the pitch in octaves, values should be between -1 and 1, default 0

Example:

-0.5

pitch

number <double>

optional

Set the pitch directly, value should be > 0, default 1 (lower = lower tone)

Example:

0.8

semitone

number <double>

optional

Adjust the pitch in semitones, values should be between -14 and 14, default 0

Example:

-10

track

string

optional

The track to which the sound modifications will be applied. Accepted values are inbound or outbound

Default:

outbound

Example:

inbound

stream_bidirectional_codec

enum<string>

optional

Indicates codec for bidirectional streaming RTP payloads. Used only with stream_bidirectional_mode=rtp. Case sensitive.

Allowed values:

PCMUPCMAG722OPUSAMR-WB

Default:

PCMU

Example:

G722

stream_bidirectional_mode

enum<string>

optional

Configures method of bidirectional streaming (mp3, rtp).

Allowed values:

mp3rtp

Default:

mp3

Example:

rtp

stream_bidirectional_sampling_rate

enum<integer>

optional

Audio sampling rate.

Allowed values:

80001600048000

Default:

8000

Example:

16000

stream_bidirectional_target_legs

enum<string>

optional

Specifies which call legs should receive the bidirectional stream audio.

Allowed values:

bothselfopposite

Default:

opposite

Example:

both

stream_codec

enum<string>

optional

Specifies the codec to be used for the streamed audio. When set to 'default' or when transcoding is not possible, the codec from the call will be used. Currently, transcoding is only supported between PCMU and PCMA codecs.

Allowed values:

PCMAPCMUdefault

Default:

default

Example:

PCMA

stream_establish_before_call_originate

boolean

optional

Establish websocket connection before dialing the destination. This is useful for cases where the websocket connection takes a long time to establish.

Default:

false

Example:

true

stream_track

enum<string>

optional

Specifies which track should be streamed.

Allowed values:

inbound_trackoutbound_trackboth_tracks

Default:

inbound_track

Example:

both_tracks

stream_url

string

optional

The destination WebSocket address where the stream is going to be delivered.

Example:

wss://www.example.com/websocket

supervise_call_control_id

string

optional

The call leg which will be supervised by the new call.

Example:

v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg

supervisor_role

enum<string>

optional

The role of the supervisor call. 'barge' means that supervisor call hears and is being heard by both ends of the call (caller & callee). 'whisper' means that only supervised_call_control_id hears supervisor but supervisor can hear everything. 'monitor' means that nobody can hear supervisor call, but supervisor can hear everything on the call.

Allowed values:

bargewhispermonitor

Default:

barge

time_limit_secs

integer <int32>

optional

Sets the maximum duration of a Call Control Leg in seconds. If the time limit is reached, the call will hangup and a call.hangup webhook with a hangup_cause of time_limit will be sent. For example, by setting a time limit of 120 seconds, a Call Leg will be automatically terminated two minutes after being answered. The default time limit is 14400 seconds or 4 hours and this is also the maximum allowed call length.

>= 30<= 14400

Default:

14400

Example:

600

timeout_secs

integer <int32>

optional

The number of seconds that Telnyx will wait for the call to be answered by the destination to which it is being called. If the timeout is reached before an answer is received, the call will hangup and a call.hangup webhook with a hangup_cause of timeout will be sent. Minimum value is 5 seconds. Maximum value is 600 seconds.

Default:

Example:

required

The DID or SIP URI to dial out to. Multiple DID or SIP URIs can be provided using an array of strings

One of

string

array[string]

Example:

+18005550100 or sip:username@sip.telnyx.com

transcription

boolean

optional

Enable transcription upon call answer. The default value is false.

Default:

false

Example:

true

transcription_config

object (Transcription start request)

optional

Example:

{"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d","command_id":"891510ac-f3e4-11e8-af5b-de00688a4901","language":"en"}

client_state

string

optional

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example:

aGF2ZSBhIG5pY2UgZGF5ID1d

command_id

string

optional

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Example:

891510ac-f3e4-11e8-af5b-de00688a4901

transcription_engine

enum<string>

optional

Engine to use for speech recognition. A - Google, B - Telnyx.

Allowed values:

Default:

Example:

transcription_engine_config

optional

transcription_tracks

string

optional

Indicates which leg of the call will be transcribed. Use inbound for the leg that requested the transcription, outbound for the other leg, and both for both legs of the call. Will default to inbound.

Default:

inbound

Example:

both

webhook_url

string

optional

Use this field to override the URL for which Telnyx will send subsequent webhooks to for this call.

Example:

https://www.example.com/server-b/

webhook_url_method

enum<string>

optional

HTTP request type used for webhook_url.

Allowed values:

POSTGET

Default:

POST

Example:

GET

Examples

Responses

🟢200OK

application/json

Successful response with details about a call status that includes recording_id.

Body

data

object (Call With Recording ID)

optional

Example:

{"call_control_id":"v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg","call_duration":50,"call_leg_id":"2dc6fc34-f9e0-11ea-b68e-02420a0f7768","call_session_id":"2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768","client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d","end_time":"2019-01-23T18:11:52.574Z","is_alive":false,"record_type":"call","recording_id":"d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a","start_time":"2019-01-23T18:10:02.574Z"}

call_control_id

string

required

Unique identifier and token for controlling the call.

Example:

v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg

call_duration

integer

optional

Indicates the duration of the call in seconds

Example:

call_leg_id

string

required

ID that is unique to the call and can be used to correlate webhook events

Example:

428c31b6-7af4-4bcb-b7f5-5013ef9657c1

call_session_id

string

required

ID that is unique to the call session and can be used to correlate webhook events. Call session is a group of related call legs that logically belong to the same phone call, e.g. an inbound and outbound leg of a transferred call

Example:

428c31b6-7af4-4bcb-b68e-5013ef9657c1

client_state

string

optional

State received from a command.

Example:

aGF2ZSBhIG5pY2UgZGF5ID1d

end_time

string

optional

ISO 8601 formatted date indicating when the call ended. Only present when the call is not alive

Example:

2019-01-23T18:11:52.574Z

is_alive

boolean

required

Indicates whether the call is alive or not. For Dial command it will always be false (dialing is asynchronous).

Example:

true

record_type

enum<string>

required

Allowed value:

call

Example:

call

recording_id

string <uuid>

optional

The ID of the recording. Only present when the record parameter is set to record-from-answer.

Example:

d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a

start_time

string

optional

ISO 8601 formatted date indicating when the call started

Example:

2019-01-23T18:10:02.574Z

🔴500Server Error

Modified at 2025-06-16 19:14:41

List call events

Start AI Assistant