The 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 element.

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

in it's most basic form the tag will look like:

<Dial>+12225551212</Dial>

Element Attributes

Attribute

Description

action
optional

URL where some parameters specific to will be sent for further processing. The calling party can be redirected here upon the hangup of the B leg caller.

method
optional

Method used to request the action URL.
Valid values: POST, GET
Default value: POST

timeout
optional

Number of seconds call stays on the line while waiting for an answer.
Default value: 60

timeLimit
optional

The duration in seconds a call made through should occur for before ending.
Valid values: integer greater than or equal to 1.
Default value: 14400

callerId
optional

E164 formatted Number to display as calling. Defaults to the ID of the phone being used.
Valid Value: Only within country dialing where enabled.

hideCallerId
optional

Boolean value specifying if the caller ID should be hidden or not.
Valid value: TRUE, FALSE
Default value: FALSE
NOTE: If value is set to TRUE, then caller ID will be hidden

dialMusic
optional

Audio URL to be executed in place of the call ring-tone.
Valid value: .mp3, .wav

callbackUrl
optional

URL requested once the dialed call connects. Note that this URL only receives parameters containing information about the call. The call does not execute XML given as a callbackURL.

callbackMethod
optional

Method used to request the callback URL.
Valid value: POST, GET Default value: POST

confirmSound
optional

Boolean value specifying if a sound should play when dial is successful.
Valid value: TRUE, FALSE
Default value: FALSE

heartbeatUrl
optional

The URL that Ytel API requests every 60 seconds during the call to notify of elapsed time as well as to pass other general information.

heartbeatMethod
optional

Method used to request the hearbeatUrl.
Valid value: POST, GET
Default value: POST

groupConfirmKey
optional

This is the single digit numeric value to be pressed to accept the call.
Allowed Value: digits 0 to 9, #, *
Default Value: 1
NOTE: Use this attribute when you are using multiple to numbers

groupConfirmFile
optional

Audio file URL which can be played after answering the call to accept the call.
Valid Value: any audio file URL with mp3 or wav format.
Default Value: https://storage.googleapis.com/m360/global/press_1.mp3
NOTE: Use this attribute when you are using multiple to numbers

onAnswerPlay
optional

Before the dial action is performed, this plays an audio to leg B of the call (The number being called in the tag). The tag can include either onAnswerPlay or onAnswerSay but not both.
Allowed Value: audio file URL. 8bit mono 8000Hz mu-law .mp3 or .wav format.

onAnswerSay
optional

Before the dial action is performed, this reads text to Leg B to leg B of the call (The number being called in the tag) using a text-to-speech engine. The tag can include either onAnswerPlay or onAnswerSay but not both.
Allowed Value: string

CallerName
optional

A String passed in the SIP header that will display on Softphones.
Allowed Value: string (max 25 chars)

PlayDTMF
optional

A set of DTMF digits that will play when Leg B of the call answers.
Allowed Value: digits 0 to 9, #, *

PlayDTMFDelay
optional

The amount of time in seconds the system will wait before executing PlayDTMF.
Allowed Value: decimal (In half second intervals)

action Attribute Properties

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

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.

heartbeatUrl Attribute Properties

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

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 element can't be nested within any other verbs besides the default element.

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

To make a Group Call, use the 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 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>

Did this page help you?