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:
call.initiatedcall.answeredorcall.hangupcall.machine.detection.endedifanswering_machine_detectionwas requestedcall.machine.greeting.endedifanswering_machine_detectionwas requested to detect the end of machine greetingcall.machine.premium.detection.endedifanswering_machine_detection=premiumwas requestedcall.machine.premium.greeting.endedifanswering_machine_detection=premiumwas requested and a beep was detectedstreaming.started,streaming.stoppedorstreaming.failedifstream_urlwas set
Request
- application/json
Body
required
Call request
Array [
]
Array [
]
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
The DID or SIP URI to dial out to. Multiple DID or SIP URIs can be provided using an array of strings
The from number to be used as the caller id presented to the destination (to number). The number should be in +E164 format.
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.
The ID of the Call Control App (formerly ID of the connection) to be used when dialing the destination.
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.
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.
The list of comma-separated codecs in a preferred order for the forked media to be received.
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 120 seconds.
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.
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.
Default value: 3500
Maximum timeout threshold for overall detection.
Default value: 800
Silence duration threshold after a greeting message or voice for it be considered human.
Default value: 50
Maximum threshold for silence between words.
Default value: 3500
Maximum threshold of a human greeting. If greeting longer than this value, considered machine.
Default value: 3500
If initial silence duration is greater than this value, consider it a machine.
Default value: 5
If number of detected words is greater than this value, consder it a machine.
Default value: 3500
If a single word lasts longer than this threshold, consider it a machine.
Default value: 256
Minimum noise threshold for any analysis.
Default value: 5000
If machine already detected, maximum timeout threshold to determine the end of the machine greeting.
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.
Conference ID to be joined
Conference name to be joined
Whether the conference should end and all remaining participants be hung up after the participant leaves the conference. Defaults to "false".
Whether the conference should end after the participant leaves the conference. NOTE this doesn't hang up the other participants. Defaults to "false".
Whether the participant should be put on hold immediately after joining the conference. Defaults to "false".
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".
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".
Whether the participant should be muted immediately after joining the conference. Defaults to "false".
Whether the conference should be started after the participant joins the conference. Defaults to "false".
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".
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".
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.
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.
The name of the header to add.
The value of the header.
Custom headers to be added to the SIP INVITE.
Use this field to set the Billing Group ID for the call. Must be a valid and existing Billing Group ID.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore others Dial commands with the same command_id.
Use another call's control id for sharing the same call session id
Possible values: [disabled, SRTP]
Default value: disabled
Defines whether media should be encrypted on the call.
SIP Authentication username used for SIP challenges.
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.
Possible values: [User-to-User]
The name of the header to add.
The value of the header.
SIP headers to be added to the SIP INVITE request. Currently only User-to-User header is supported.
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.
Set the pitch directly, value should be > 0, default 1 (lower = lower tone)
Adjust the pitch in semitones, values should be between -14 and 14, default 0
Adjust the pitch in octaves, values should be between -1 and 1, default 0
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.
The destination WebSocket address where the stream is going to be delivered.
Possible values: [inbound_track, outbound_track, both_tracks]
Default value: inbound_track
Specifies which track should be streamed.
Generate silence RTP packets when no transmission available.
Use this field to override the URL for which Telnyx will send subsequent webhooks to for this call.
Possible values: [POST, GET]
Default value: POST
HTTP request type used for webhook_url.
Possible values: [record-from-answer]
Start recording automatically after an event. Disabled by default.
Possible values: [single, dual]
Default value: dual
Defines which channel should be recorded ('single' or 'dual') when record is specified.
Possible values: [wav, mp3]
Default value: mp3
Defines the format of the recording ('wav' or 'mp3') when record is specified.
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).
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).
Possible values: [trim-silence]
When set to trim-silence, silence will be removed from the beginning and end of the recording.
The custom recording file name to be used instead of the default call_leg_id. Telnyx will still add a Unix timestamp suffix.
Enables Dialogflow for the current call. The default value is false.
dialogflow_config
object
Enable sentiment analysis from Dialogflow.
Enable partial automated agent reply from Dialogflow.
Responses
200: Successful response with details about a call status.
- application/json
default: Unexpected error
- application/json