Skip to main content

Dial

The Dial verb transfers an existing call to another destination. Dial will end this new call if: the called party does not answer, the number does not exist, or Telnyx receives a busy signal.

Attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
action Optional URL where TeXML will make a request when the Dial call ends to retrieve a new set of TeXML instructions to continue the call flow. -
method HTTP method to use when requesting the action URL. GET, POST POST
callerId Caller ID that must be a valid E.164 format number. -
fromDisplayName The fromDisplayName string to be used as the caller id name (SIP From Display Name) presented to the destination. The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If omitted, the display name will be the same as the number in the callerId field. -
hangupOnStar The hangupOnStar attribute lets the initial caller hang up on the called party by pressing the '*' key on their phone. Does not apply for the Conference noun. false
timeout The number of seconds to wait for the called party to answer the call. 5 - 120 30
timeLimit The maximum duration of the call in seconds. 60 - 14400 14400
record The record attribute lets you record both legs of a call within the associated Dial verb. It works with the Number and Sip nouns only. If you want to record the conference, please use the record attribute on Conference noun. Recordings are available in two options: single or dual. do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual do-not-record
recordingChannels The number of channels in the final recording. Possible values are: single (for mono) and dual (for stereo). Defaults to single. single, dual single
recordMaxLength Defines the maximum length for the recording in seconds (0 for infinite) 0 - 14400 0
recordingStatusCallback Optional URL that tells Telnyx where to make its GET or POST request when the recording is available. -
recordingStatusCallbackMethod HTTP request type used for recordingStatusCallback. GET, POST POST
recordingStatusCallbackEvent The recording events for which Telnyx should send a webhook. Multiple events are separated by a space. in-progress, completed, absent completed
ringTone The ringback tone played back to the caller. at, au, bg, br, be, ch,cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt,ru, se, sg, th, tw, ve, za, us, us-old, uk us

Child verbs/nouns

NOUN/VERBDESCRIPTION
Number Specifies a phone number to dial.
Sip The Sip noun specifies a SIP endpoint to dial.
Queue The Queue noun allows you to add a call to a queue.

Number Attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
statusCallback A URL for Telnyx to send webhook requests to on each event specified in the statusCallbackEvent attribute for outbound calls only. Inbound Status Callback events can be configured for TeXML the connection settings in the Mission Control Portal. -
statusCallbackEvent The call events for which Telnyx should send a webhook. Multiple events are separated by a space. initiated, ringing, answered, amd, dtmf, completed completed
statusCallbackMethod HTTP request type Telnyx should use when requesting the statusCallback URL. GET, POST POST
url Optional URL to another TeXML document that can contain Gather and Hangup verbs so that the called party can chose to take an action on the incoming call before the two parties are connected. The callee will continue to hear ringback while the url document is executed. -
method HTTP request type used for url. GET, POST POST
sendDigits Specifies DTMF tones to play when the call is answered. The value can include: digits 0-9, #, *, and w. 'w' indicates a 0.5 second pause. -
machineDetection Enables Answering Machine Detection. Note: add AMD event type to statusCallbackEvent list to receive the detection result webhook. Enable, DetectMessageEnd, Disable Disable
detectionMode Sets the Answering Detection mode. Regular, Premium Regular
machineDetectionTimeout Maximum timeout threshold for overall detection, in milliseconds.

500 - 60000

3500

Sip Attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
username Username to use for SIP authentication. -
password Password to use for SIP authentication. -
statusCallback A URL for Telnyx to send webhook requests to on each event specified in the statusCallbackEvent attribute for outbound calls only. Inbound Status Callback events can be configured for TeXML connection settings in the Mission Control Portal. -
statusCallbackEvent The call events for which Telnyx should send a webhook. Multiple events are separated by a space. initiated, ringing, answered, amd, dtmf, completed completed
statusCallbackMethod HTTP request type Telnyx should use when requesting the statusCallback URL. GET, POST POST
url Optional URL to another TeXML document that can contain Gather and Hangup verbs so that the called party can choose to take an action on the incoming call before the two parties are connected. The callee will continue to hear ringback while the URL document is executed. -
method HTTP request type used for url. GET, POST POST
machineDetection Enables Answering Machine Detection. Note: add AMD event type to statusCallbackEvent list to receive the detection result webhook. Enable, DetectMessageEnd, Disable Disable
detectionMode Sets the Answering Detection mode. Regular, Premium Regular
machineDetectionTimeout Maximum timeout threshold for overall detection, in milliseconds.

500 - 60000

3500

Queue Attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
url Optional URL to another TeXML document that can contain Play, Say, Gather, Pause and Redirect verbs. The document will be executed on the queued call before bridging the calls. -
method HTTP request type used for url. GET, POST POST

Example

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial action="/nextinstructions.php" callerId="+13120001234">+19999999999</Dial>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial action="/nextinstructions.php" callerId="+13120001234">
<Number statusCallback="https://foo.com/my_call_stats" statusCallbackEvent="initiated ringing answered completed">+19999999999</Number>
</Dial>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial action="/nextinstructions.php" callerId="+13120001234" hangupOnStar="true">
<Sip statusCallback="https://foo.com/my_sip_call_stats" statusCallbackEvent="initiated">sip:connection@sip.telnyx.com</Sip>
</Dial>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial action="/nextinstructions.php" callerId="+13120001234">
<Number statusCallback="https://foo.com/my_call_stats" statusCallbackEvent="initiated ringing answered completed amd" machineDetection="Enable" detectionMode="Regular">+19999999999</Number>
</Dial>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial action="/nextinstructions.php" callerId="+13120001234">
<Number statusCallback="https://foo.com/my_call_stats" statusCallbackEvent="initiated ringing answered completed amd" machineDetection="Enable" detectionMode="Regular">+19999999999</Number>
</Dial>
</Response>

Expected callbacks

If action is set the following callback can be expected. when the call is completed. The new set of instructions can be sent as a response to it. The error code and error message field are provided only in case of failed calls. The full list of errors can be found under the link

{
"AccountSid" : "19a75cea-02c6-4b9a-84fa-c9bc8341feb8",
"AnsweredTime" : "2023-09-06T09:05:14.860713Z",
"CallLegId" : "7d87c352-4c94-11ee-99f7-02420a0daa69",
"CallSessionId" : "7bf6178c-4c94-11ee-b679-02420aef02a0",
"CallSid" : "v3:viLNGyAMjOw6H0AAmA3_CL4rbzYWgahKGqeoZ0Eu_TUYPeWs5w3z6w",
"CallSidLegacy" : "v3:viLNGyAMjOw6H0AAmA3_CL4rbzYWgahKGqeoZ0Eu_TUYPeWs5w3z6w",
"ConnectionId" : "2034058542482196149",
"DataLocality" : "USA",
"DialCallDuration" : "11",
"DialCallSid" : "v3:t7KEildpy-HskSZeY78-WjFFcJMAaopsPfnkaH2J3NcByeTzgfVS1A",
"DialCallSidLegacy" : "v3:t7KEildpy-HskSZeY78-WjFFcJMAaopsPfnkaH2J3NcByeTzgfVS1A",
"DialCallStatus" : "completed | busy | no-answer | failed",
"EndTime" : "2023-09-06T09:05:26.720715Z",
"ErrorCode": "10010"
"ErrorMessage": "Destination Number is invalid D11"
"From" : "+13122010094",
"OccurredAt" : "2023-09-06T09:05:26.720715Z",
"OrganizationId" : "19a75cea-02c6-4b9a-84fa-c9bc8341feb8",
"StartTime" : "2023-09-06T09:05:14.080710Z",
"To" : "+12029925624",
"UserId" : "19a75cea-02c6-4b9a-84fa-c9bc8341feb8",
}

If statusCallbackEvent are set you can expect the following webhooks.

initiated

{
"AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
"CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallStatus": "initiated",
"CallbackSource": "call-progress-events",
"From": "+18445931290",
"ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"SequenceNumber": "0",
"Timestamp": "2021-04-28 21:51:13.591099Z",
"To": "+13122010055"
}

ringing

{
"AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
"CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallStatus": "ringing",
"CallbackSource": "call-progress-events",
"From": "+18445931290",
"ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"SequenceNumber": "1",
"Timestamp": "2021-04-28 21:51:13.591107Z",
"To": "+13122010055"
}

in-progress

{
"AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
"CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallStatus": "in-progress",
"CallbackSource": "call-progress-events",
"From": "+18445931290",
"ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"SequenceNumber": "2",
"Timestamp": "2021-04-28 21:51:15.532975Z",
"To": "+13122010055"
}

completed

{
"AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
"CallDuration": "2",
"CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallStatus": "completed",
"CallbackSource": "call-progress-events",
"From": "+18445931290",
"HangupSource": "",
"ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"RecordingDuration": "5",
"RecordingUrl": "https://recording.com/your-recording-url",
"SequenceNumber": "3",
"Timestamp": "2021-04-28 21:51:18.731479Z",
"To": "+13122010055"
}

failed

{
"AccountSid": "6106a32e-75c8-4c72-9d56-26d2e34ddf46",
"CallSid": "",
"CallSidLegacy": "",
"CallStatus": "failed",
"CallbackSource": "call-progress-events",
"ConnectionId": "1776656324537354013",
"ErrorCode": "10010",
"ErrorMessage": "Destination Number is invalid D11",
"ParentCallSid": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
"ParentCallSidLegacy": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
"SequenceNumber": "0",
"Timestamp": "2024-10-25 09:50:56.718456Z",
"To": "+111"
}

busy

{
"AccountSid": "6106a32e-75c8-4c72-9d56-26d2e34ddf46",
"CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallStatus": "busy",
"CallbackSource": "call-progress-events",
"ConnectionId": "1776656324537354013",
"ParentCallSid": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
"ParentCallSidLegacy": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
"SequenceNumber": "0",
"Timestamp": "2024-10-25 09:50:56.718456Z",
"To": "+13122010055"
}

no-answer

{
"AccountSid": "6106a32e-75c8-4c72-9d56-26d2e34ddf46",
"CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallStatus": "no-answer",
"CallbackSource": "call-progress-events",
"ConnectionId": "1776656324537354013",
"ParentCallSid": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
"ParentCallSidLegacy": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
"SequenceNumber": "0",
"Timestamp": "2024-10-25 09:50:56.718456Z",
"To": "+13122010055"
}

amd

{
"AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
"AnsweredBy": "machine_start|human|fax|machine_end_beep|machine_end_other|unknown",
"CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
"MachineDetectionDuration": "23357"
}

If recordingStatusCallbackEvent is set you can expect the following webhooks.

in-progress

{
"AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
"CallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"CallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"From": "Defaultj35z6@sip.telnyx.com",
"RecordingChannels": "1",
"RecordingSource": "DialVerb",
"RecordingStatus": "in-progress",
"To": "+12132045020"
}

completed

{
"AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
"CallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"CallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
"From": "Defaultj35z6@sip.telnyx.com",
"RecordingChannels": "1",
"RecordingDuration": "5",
"RecordingSid": "35094891-3290-4142-b2c2-b2eda57534cf",
"RecordingSource": "DialVerb",
"RecordingStatus": "completed",
"RecordingUrl": "https://recording.com/your-recording-url",
"To": "+12132045020"
}

Status callback HTTP attributes

The attributes contained in the statusCallback request to your URL.

ATTRIBUTEDESCRIPTION
AccountSidA unique identifier for the account generating this call.
CallSidA unique identifier for this call, generated by Telnyx.
ParentCallSidA unique identifier for the parent call.
CallStatusA descriptive status for the call. The value is one of initiated, ringing, in-progress, completed, no-answer, busy, failed or canceled.
TimestampThe timestamp when the event was fired, given as UTC in RFC 2822 format.
CallbackSourceA string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always call-progress-events.
FromThe outbound caller number.
ToThe inbound callee number.
RecordingDurationRecording duration in seconds.
RecordingUrlUrl where the recording can be downloaded from.
RecordingSidA unique identifier for the recording, generated by Telnyx.
RecordingChannels1 for mono-channel, 2 for dual-channel
RecordingStatusThe status for the recording. The value is one of in-progress, completed or absent.
SequenceNumberA sequence number ordering the multiple callbacks received. The first callback has the lowest, and the last callback the highest.