Copy page

OneML reference

Dial

The <Dial> verb connects the current caller to another phone number. Signals bridges the two call legs together, and once the dialed call ends it can request an action URL with the outcome.

Attributes

Name	Type	Default	Description
action	string (uri)	None	URL to request once the dialed call ends. When absent, the next verb in the document runs.
method	string	POST	HTTP method used to request action. GET or POST.
timeout	integer	30	Seconds to wait for the dialed party to answer.
callerId	string	None	Number shown to the dialed party. Must be an eligible number your Signals project owns, or the dial fails with DialCallStatus of failed. When omitted, Signals uses To for inbound calls and From for calls created through the Calls API. The selected number must still be owned and eligible.
answerOnBridge	boolean	false	When true, the caller's leg stays unanswered until the dialed party answers, so the caller hears ringing. When false, the caller's leg is answered before dialing, so the caller usually hears silence until the call connects.
record	string	do-not-record	Whether to record the dialed call: do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual or record-from-start. Any value other than do-not-record records both parties into one audio file. record-from-answer starts when the dialed party answers; record-from-ringing and record-from-start start before the dial, so ringback is captured. The dual variants behave like their base mode and still produce one mixed channel. When recording is on, the action request includes RecordingUrl, and recordingStatusCallback fires when the recording is ready.
recordingStatusCallback	string (uri)	None	URL to notify when the dialed call's recording finishes. Requested once, for the completed event only, with RecordingSource set to DialVerb.
recordingStatusCallbackMethod	string	POST	HTTP method used to request recordingStatusCallback. GET or POST.
timeLimit	integer	14400	Maximum duration of the dialed call, in seconds (four hours by default). When it expires, Signals hangs up the dialed party; a call that connected reports DialCallStatus of completed.
hangupOnStar	boolean	false	Whether the caller can press * to hang up on the dialed party without ending their own call. The document then continues, and action is requested with DialCallStatus of completed. The dialed party's * has no effect.
ringTone	string	None	Country code for the ringback tone the caller hears: us, ca, uk, nz, au, de, it, br, mx, es, pt, fr, in, jp or za. Other values use the carrier's own ringback. Early media from the dialed network takes precedence over the selected tone.
sequential	boolean	false	When false, Signals rings every <Number> at once and bridges the first to answer. When true, it dials them in order, moving to the next only if the previous one does not complete.

Dialed numbers go out through your project's outbound policy and limits. A dialed number that your project or another Signals customer owns is connected on net.

Nesting

<Dial> accepts a phone number as its text content, or one or more <Number> children.

<Number>

Name	Type	Default	Description
sendDigits	string	None	Accepted but not applied. Signals does not send these tones to the dialed party after the call connects.

<Number> contains the phone number to dial as text content.

Action parameters

Name	Type	Description
DialCallStatus	string	Outcome of the dialed call: completed, busy, no-answer, canceled or failed.
DialCallDuration	integer	Duration of the bridged call, in seconds. Present only when the call bridged.
DialCallSid	string	Unique identifier for the dialed leg. Present only when the call bridged.
RecordingUrl	string (uri)	URL of the recording audio on the Calls API. Present only when record was on. Requires your AccountSid and auth token; see Download recording audio.

Examples

A forward to another number:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="+2342013300100">+2348051234567</Dial>
</Response>

A forward with an action that falls back to voicemail when the call does not complete:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial action="/dial-complete" callerId="+2342013300100" timeout="20">
    <Number>+2348051234567</Number>
  </Dial>
</Response>

A recorded forward:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>This call may be recorded for quality purposes.</Say>
  <Dial callerId="+2342013300100" record="record-from-answer" recordingStatusCallback="/recording-status">
    +2348051234567
  </Dial>
</Response>

The /dial-complete handler, complete and runnable:

See also

• Forwarding calls
• Record
• Redirect
• OneML overview