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

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

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`

You can use multiple <Number> and <Sip> nouns within a <Dial> verb to dial multiple phone numbers and SIP addresses at the same time. The first person to answer the call will be connected to the caller, while the rest of the call attempts are hung up:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Number>+18775551212</Number>
    <Sip>sip:connection@sip.telnyx.com</Sip>
    <Number>+18771234567</Number>
  </Dial>
</Response>

Examples

<?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 is set the following callbacks are expected.

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.