Verbs

<Dial>

Connect the caller to another party: a phone number, SIP endpoint, client, conference, queue, or saved application.

Element body

A bare phone number may be used as the body; nouns are the explicit form.

Example

<Response>
  <Dial callerId="+12125550100" timeout="20" record="record-from-answer"
        action="https://app.example.com/after-dial">
    <Number sendDigits="wwww1928">+18005551234</Number>
  </Dial>
</Response>

Attributes

Attribute Default Behaviour
action unset URL requested when the dial completes; the returned VoiceML continues the call. Without an action, execution falls through to the next verb.
method POST HTTP method for the action request: POST or GET.
timeout 30 Seconds the dialled party has to answer.
timeLimit 14400 Maximum bridged-call duration in seconds.
callerId the calling leg's caller ID Caller ID presented to the dialled party. An explicit value must be a number owned by (or verified on) your account — otherwise the leg fails and the action callback carries ErrorCode 21210. Inherited caller IDs are never checked; anonymous is used only when the call has no caller ID at all.
answerOnBridge false true keeps the caller in ringing until the dialled party answers, then both legs answer simultaneously. Default: the caller's leg answers immediately and hears ringback while the far end is dialled.
hangupOnStar false true lets the caller press * to end the bridged leg and return to the document at the verb after <Dial> (the action callback fires with DialCallStatus=completed).
ringTone unset Two-letter country code (us, gb, …) selecting the ringback tone the caller hears while the far end rings.
sequential false On a multi-target <Dial> (several <Number>/<Sip>/<Client> children), false rings all targets simultaneously and the first answer wins; true rings them one at a time in document order until one answers.
record do-not-record Records the bridged call. Values: do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual.
recordingTrack both Which side of the bridge is captured: inbound, outbound, or both.
recordingStatusCallback unset URL that receives recording lifecycle events (same shape as <Record>): in-progress, completed, absent.
recordingStatusCallbackMethod POST HTTP method for recording lifecycle callbacks.
recordingStatusCallbackEvent completed Comma-separated list of lifecycle events to deliver.
events unset Accepted for compatibility and ignored — no effect.
passports unset Accepted for compatibility and ignored — no effect.
referMethod unset Accepted for compatibility and ignored — no effect. Transfers are handled by <Refer>.
referUrl unset Accepted for compatibility and ignored — no effect. Transfers are handled by <Refer>.
recordingConfigurationId unset Accepted for compatibility and ignored — no effect.

Nesting

<Dial> accepts these nested elements:

Callbacks

action request (Number / Sip / Client)

Field Description
DialCallStatus Outcome of the dial: completed, no-answer, busy, or failed.
DialCallSid Unique identifier of the dialled leg.
DialBridged Always sent: true when the parties were bridged (DialCallStatus=completed), false otherwise.
DialCallDuration Seconds the bridged call lasted; sent only when the dial completed.
ErrorCode / ErrorMessage Sent on failed dials caused by a platform refusal (unverified callerId) or an invalid destination number — not on busy or no-answer.
RecordingSid / RecordingUrl / RecordingDuration Present when the bridge was recorded.

action request (Conference)

Field Description
ConferenceSid Identifier of the conference room the participant was in.
DialCallStatus answered on a clean leave, failed on a join error. DialCallDuration is not sent for conferences.

Every callback also carries the standard call parameters (CallSid, AccountSid, From, To, CallStatus) and is signed with your account's API key.

Notes

  • Multi-target dialling: up to 10 <Number>, <Sip>, and <Client> children in one <Dial> ring together (the default) or one after another (sequential="true"). Per-target url, credentials, and header options are rejected on multi-target dials; <Conference>, <Queue>, and <Application> are always single-target.
  • <Sim> (mobile-SIM dialing) is not supported and returns an unsupported-element error.