Skip to main content
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, POSTPOST
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 - 12030
timeLimit The maximum duration of the call in seconds. 60 - 1440014400
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-dualdo-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, dualsingle
recordMaxLength Defines the maximum length for the recording in seconds (0 for infinite) 0 - 144000
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, POSTPOST
recordingStatusCallbackEvent The recording events for which Telnyx should send a webhook. Multiple events are separated by a space. in-progress, completed, absentcompleted
sendRecordingUrl Defines if the recording URL is sent in the callbacks. true
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, ukus

​
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, completedcompleted
statusCallbackMethod HTTP request type Telnyx should use when requesting the statusCallback URL. GET, POSTPOST
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, POSTPOST
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, DisableDisable
detectionMode Sets the Answering Detection mode. Regular, PremiumRegular
machineDetectionTimeout Maximum timeout threshold for overall detection, in milliseconds. 500 - 600003500

​
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 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, completedcompleted
statusCallbackMethod HTTP request type Telnyx should use when requesting the statusCallback URL. GET, POSTPOST
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, POSTPOST
machineDetection Enables Answering Machine Detection. Note: add amd event type to statusCallbackEvent list to receive the detection result webhook. Enable, DetectMessageEnd, DisableDisable
detectionMode Sets the Answering Detection mode. Regular, PremiumRegular
machineDetectionTimeout Maximum timeout threshold for overall detection, in milliseconds. 500 - 600003500

​
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, POSTPOST

​
Simultaneous dialing

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, a callback is sent when the dialed call ends. See Dial Action Callback for the full payload reference. The error_code and error_message fields are provided only in case of failed calls. The full list of errors can be found under the API Errors page. If statusCallbackEvent is set, the following webhooks are sent based on configured events:
EventCallback Reference
initiatedCall Initiated
ringingCall Ringing
answeredCall Answered
completedCall Completed
If machineDetection is enabled, an AMD callback is sent to amdStatusCallback. See AMD Callback for the full payload reference. If recordingStatusCallbackEvent is set, the following webhooks are sent:
EventCallback Reference
in-progressRecording In Progress
completedRecording Completed