Dial

POST 
/calls

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

application/json

Body

required

Call request

to

object

required

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

oneOf

• MOD1
• MOD2

string

Array [

string

]

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

from stringrequired

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

from_display_name string

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.

connection_id stringrequired

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

audio_url string

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.

media_name string

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.

preferred_codecs string

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

timeout_secs int32

Default value: 30

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.

time_limit_secs int32

Possible values: >= 30 and <= 14400

Default value: 14400

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.

answering_machine_detection string

Possible values: [premium, detect, detect_beep, detect_words, greeting_end, disabled]

Default value: disabled

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.

answering_machine_detection_config

object

Optional configuration parameters to modify 'answering_machine_detection' performance.

total_analysis_time_millis int32

Default value: 3500

Maximum timeout threshold for overall detection.

after_greeting_silence_millis int32

Default value: 800

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

between_words_silence_millis int32

Default value: 50

Maximum threshold for silence between words.

greeting_duration_millis int32

Default value: 3500

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

initial_silence_millis int32

Default value: 3500

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

maximum_number_of_words int32

Default value: 5

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

maximum_word_length_millis int32

Default value: 3500

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

silence_threshold int32

Default value: 256

Minimum noise threshold for any analysis.

greeting_total_analysis_time_millis int32

Default value: 5000

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

greeting_silence_duration_millis int32

Default value: 1500

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

Optional configuration parameters to modify 'answering_machine_detection' performance.

conference_config

object

Optional configuration parameters to dial new participant into a conference.

id uuid

Conference ID to be joined

conference_name string

Conference name to be joined

early_media boolean

Default value: true

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

end_conference_on_exit boolean

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

soft_end_conference_on_exit boolean

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

hold boolean

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

hold_audio_url string

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

hold_media_name string

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

mute boolean

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

start_conference_on_enter boolean

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

start_conference_on_create boolean

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

supervisor_role string

Possible values: [barge, monitor, none, whisper]

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

whisper_call_control_ids string[]

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.

beep_enabled string

Possible values: [always, never, on_enter, on_exit]

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.

Optional configuration parameters to dial new participant into a conference.

custom_headers

object[]

Custom headers to be added to the SIP INVITE.

Array [

name stringrequired

The name of the header to add.

value stringrequired

The value of the header.

]

Custom headers to be added to the SIP INVITE.

billing_group_id uuid

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

client_state string

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

command_id string

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

link_to string

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

media_encryption string

Possible values: [disabled, SRTP]

Default value: disabled

Defines whether media should be encrypted on the call.

sip_auth_username string

SIP Authentication username used for SIP challenges.

sip_auth_password string

SIP Authentication password used for SIP challenges.

sip_headers

object[]

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

Array [

name stringrequired

Possible values: [User-to-User]

The name of the header to add.

value stringrequired

The value of the header.

]

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

sip_transport_protocol string

Possible values: [UDP, TCP, TLS]

Default value: UDP

Defines SIP transport protocol to be used on the call.

sound_modifications

object

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

pitch double

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

semitone double

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

octaves double

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

track string

Default value: outbound

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

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

stream_url string

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

stream_track string

Possible values: [inbound_track, outbound_track, both_tracks]

Default value: inbound_track

Specifies which track should be streamed.

stream_bidirectional_mode Stream Bidirectional Mode (string)

Possible values: [mp3, rtp]

Default value: mp3

Configures method of bidirectional streaming (mp3, rtp).

stream_bidirectional_codec Stream Bidirectional Codec (string)

Possible values: [PCMU, PCMA, G722]

Default value: PCMU

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

stream_bidirectional_target_legs Stream Bidirectional Target Legs (string)

Possible values: [both, self, opposite]

Default value: opposite

Specifies which call legs should receive the bidirectional stream audio.

send_silence_when_idle boolean

Generate silence RTP packets when no transmission available.

webhook_url string

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

webhook_url_method string

Possible values: [POST, GET]

Default value: POST

HTTP request type used for webhook_url.

record string

Possible values: [record-from-answer]

Start recording automatically after an event. Disabled by default.

record_channels string

Possible values: [single, dual]

Default value: dual

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

record_format string

Possible values: [wav, mp3]

Default value: mp3

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

record_max_length int32

Default value: 0

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

record_timeout_secs int32

Default value: 0

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

record_track string

Possible values: [both, inbound, outbound]

Default value: both

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

record_trim string

Possible values: [trim-silence]

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

record_custom_file_name string

Possible values: non-empty and <= 40 characters

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

enable_dialogflow boolean

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

dialogflow_config

object

analyze_sentiment boolean

Enable sentiment analysis from Dialogflow.

partial_automated_agent_reply boolean

Enable partial automated agent reply from Dialogflow.

transcription boolean

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

transcription_config

object

transcription_engine string

Possible values: [A, B]

Default value: A

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

language

object

oneOf

• Google transcription engine list of languages
• Telnyx transcription engine list of languages

Language to use for speech recognition

string

Possible values: [af, sq, am, ar, hy, az, eu, bn, bs, bg, my, ca, yue, zh, hr, cs, da, nl, en, et, fil, fi, fr, gl, ka, de, el, gu, iw, hi, hu, is, id, it, ja, jv, kn, kk, km, ko, lo, lv, lt, mk, ms, ml, mr, mn, ne, no, fa, pl, pt, pa, ro, ru, rw, sr, si, sk, sl, ss, st, es, su, sw, sv, ta, te, th, tn, tr, ts, uk, ur, uz, ve, vi, xh, zu]

Language to use for speech recognition

string

Possible values: [en, zh, de, es, ru, ko, fr, ja, pt, tr, pl, ca, nl, ar, sv, it, id, hi, fi, vi, he, uk, el, ms, cs, ro, da, hu, ta, no, th, ur, hr, bg, lt, la, mi, ml, cy, sk, te, fa, lv, bn, sr, az, sl, kn, et, mk, br, eu, is, hy, ne, mn, bs, kk, sq, sw, gl, mr, pa, si, km, sn, yo, so, af, oc, ka, be, tg, sd, gu, am, yi, lo, uz, fo, ht, ps, tk, nn, mt, sa, lb, my, bo, tl, mg, as, tt, haw, ln, ha, ba, jw, su, auto_detect]

interim_results boolean

Whether to send also interim results. If set to false, only final results will be sent. Applies to google engine only.

enable_speaker_diarization boolean

Enables speaker diarization. Applies to google engine only.

min_speaker_count int32

Default value: 2

Defines minimum number of speakers in the conversation. Applies to google engine only.

max_speaker_count int32

Default value: 6

Defines maximum number of speakers in the conversation. Applies to google engine only.

client_state string

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

transcription_tracks string

Default value: inbound

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.

command_id string

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

200: Successful response with details about a call status.

application/json

• Schema
• Example (from schema)

Schema

data

object

record_type stringrequired

Possible values: [call]

call_session_id stringrequired

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

call_leg_id stringrequired

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

call_control_id stringrequired

Unique identifier and token for controlling the call.

is_alive booleanrequired

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

client_state string

State received from a command.

call_duration integer

Indicates the duration of the call in seconds

{
  "data": {
    "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
    "call_leg_id": "2dc6fc34-f9e0-11ea-b68e-02420a0f7768",
    "call_session_id": "2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768",
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "is_alive": false,
    "call_duration": 50,
    "record_type": "call"
  }
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Request samples

• cURL

---

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

Response samples

• 200
• default

---

{
  "data": {
    "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
    "call_leg_id": "2dc6fc34-f9e0-11ea-b68e-02420a0f7768",
    "call_session_id": "2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768",
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "is_alive": false,
    "call_duration": 50,
    "record_type": "call"
  }
}

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}