<Dial>

The <Dial> element starts an outgoing dial from the current call. Once the dial is complete, the next element in the InboundXML document will be processed unless the action attribute is set. In that case, the result of the dial is submitted as a GET or POST (depending on the method attribute) to the action URL, and the call continues using the InboundXML of that URL.

By default the outgoing call will timeout if it is not answered after 60 seconds. However, the timeout attribute can be used to set a custom time. The length of the call is limited by the timeLimit attribute which is 4 hours (14400 seconds) by default.

The callerId attribute can be set to any number and will default to the caller ID of the original caller. The number to be dialed should be nested within the <Dial> element.

All numbers should be E164 formatted. for US numbers this would be the format +1XXXYYYZZZZ

in it's most basic form the <Dial> tag will look like this:

<Dial>+12225551212</Dial>

Element Attributes

Attribute	Description
`action` optional	URL where some parameters specific to will be sent for further processing.
`method` optional	Method used to request the action URL. Valid values: POST and GET Default value: POST
`timeout` optional	The number of seconds should wait during silence before ending. Valid value: integer greater than or equal to 1 Default value: 5
`finishOnKey` optional	The key a caller can press to end the recording. Valid values: digits from 0 to 9, #, or * Default value: #
`maxLength` optional	The maximum length in seconds a recording should be. Valid value: integer greater than or equal to 1 Default value: 3600
`playBeep` optional	Boolean value specifying if a beep should be played when the recording begins. Valid value: true, false Default value: false
`fileFormat` optional	The recording file format. Can be mp3 or wav. Valid value: mp3, wav Default value: mp3
`background` optional	Begin recording the call while continuing the execution of any other present InboundXML in the background (true) or block the execution of subsequent InboundXML until the record element finishes (via finishOnKey or timeout). Note that the timeout, finishOnKey, and playBeep attributes have no effect when the background is set to true. Valid value: true, false Default value: true
`trimSilence` optional	Trims all silence from the beginning of the recording. Any other value will default to "false". Valid value: true, false

Action Attribute Properties

In addition to the default voice request attributes, these dial-specific attributes are also forwarded to the callback URL and action URL.

Attribute	Description
`CallSid`	The callSid string value for the call object.
`AccountSId`	The unique identifier for the Ytel API account.
`From`	The phone number that initiated the outbound call.
`To`	The phone number that was dialed/received the call.

Heartbeat URL Attribute Properties

In addition to the default voice request attributes, these attributes are also forwarded to the heartbeatUrl.

Attribute	Description
`CallSid`	The callSid string value for the call object.
`AccountSid`	The unique identifier for the Ytel API account.
`From`	The phone number that initiated the outbound call.
`To`	The phone number that was dialed/received the call.
`Direction`	The direction of the call, either inbound or outbound.
`CallInitiate`	The datetime value for when the call began.
`CallStartTime`	The datetime value for when the call connected.
`Status`	The status of the call, any one of in-queue, dialing, in-progress, user_busy, no_answer, insufficient_funds, unallocated_numbers, or completed

Nesting

The <Dial> element can't be nested within any other verbs besides the default <Response> element.

<Response>
  <Dial action="http://your-url.com/"
    callerid="+1949XXXYYYY">+1714XXXYYYY
  </Dial>
</Response>

To make a Group Call, use the <Dial> element. Use a comma ( , ) to separate the E164 formatted numbers to be dialed. The attributes of groupConfirmKey and groupConfirmFile are required for group calls.

🚧
Group Call Limitation Warning
The maximum number of To numbers that a Group Call can initiate is 10. Multiple numbers can be passed in the To field by separating them by a comma ( , ). You may also mix digits and SIP numbers within the <Dial> tag.
+19495551212,sip:[email protected],+19495551414,sip:[email protected]

<Response>
   <Dial action="http://your-url.com/"  callerid="+1949XXXYYYY" groupconfirmkey="1"
    groupconfirmfile="https://storage.googleapis.com/m360/global/press_1.mp3">+1949XXXYYYY,+1949XXXYYYY,+1714XXXYYYY
  </Dial>
</Response>