<Dial>
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>
Updated almost 2 years ago