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
ATTRIBUTE | DESCRIPTION | OPTIONS | DEFAULT |
---|---|---|---|
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/VERB | DESCRIPTION |
---|---|
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
ATTRIBUTE | DESCRIPTION | OPTIONS | DEFAULT |
---|---|---|---|
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. |
| 3500 |
Sip Attributes
ATTRIBUTE | DESCRIPTION | OPTIONS | DEFAULT |
---|---|---|---|
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. |
| 3500 |
Queue Attributes
ATTRIBUTE | DESCRIPTION | OPTIONS | DEFAULT |
---|---|---|---|
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.
ATTRIBUTE | DESCRIPTION |
AccountSid | A unique identifier for the account generating this call. |
CallSid | A unique identifier for this call, generated by Telnyx. |
ParentCallSid | A unique identifier for the parent call. |
CallStatus | A descriptive status for the call. The value is one of initiated , ringing , in-progress , completed , no-answer , busy , failed or canceled . |
Timestamp | The timestamp when the event was fired, given as UTC in RFC 2822 format. |
CallbackSource | A 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 . |
From | The outbound caller number. |
To | The inbound callee number. |
RecordingDuration | Recording duration in seconds. |
RecordingUrl | Url where the recording can be downloaded from. |
RecordingSid | A unique identifier for the recording, generated by Telnyx. |
RecordingChannels | 1 for mono-channel , 2 for dual-channel |
RecordingStatus | The status for the recording. The value is one of in-progress , completed or absent . |
SequenceNumber | A sequence number ordering the multiple callbacks received. The first callback has the lowest, and the last callback the highest. |