A central component of the cloud API, the Dial element connects any call with a POTS phone (traditional phone number) or a SIP endpoint. Dial supports the calling of up to 10 phone numbers and 10 SIP endpoints at the same time. Dial multiple users/numbers and bridge the call to whoever answers first.
Call confirm / call screen, background callbacks, outbound caller ID manipulation, and hold music are all features of the Dial element.
The Number and User elements can be nested within the dial element.
The <Dial> element supports the following attributes that enhance its behavior:
|action||The call flow will redirect to this URL using your specified method when the Dial action is complete.||fully qualified URL|
|method||The method used to call the action URL.||POST,GET||POST|
|caller_name||The caller ID name displayed on the outbound call.||A-Z||VoiceAPI|
|caller_id_number||The caller ID number with country code. Ex: 12145551212||0-9||14692145044|
|hold_music_url||The hold music that will be played while the call is ringing.||To use system provided music provide one of the following keywords: classical,funk,relaxed,hiphop,smooth,techno. Alternatively, you can provide your own URL to a WAV or MP3 file.|
|confirm_key||The digit to be pressed by the called party to accept the call. confirm_sound_url must be set.||*,#,0-9|
|confirm_sound_url||The sound file to play to the party answering the call to confirm the call. confirm_key must be set. You can now use the word 'default' to play the default confirm sound, this will automatically set the confirm_key to #.||fully qualified URL WAV/MP3 or keyword 'default'|
|digitsMatch||A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatch parameter (A leg).||*,#,0-9|
|digitsMatchBLeg||A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatchBLeg parameter (B leg).||*,#,0-9|
|callbackUrl||URL that is notified by the cloud when the call is answered, ringing, or hung up. Also used to notify when "digits match". See the callbackUrl parameters below.||fully qualified URL|
|record||Flag to record the call. Use Y to record the entire conversation (may not be legal in some jurisdictions).||Y or N||N|
|redirect||If set to Y the call flow will continue for Aleg when Bleg hangs up. If set to N or left empty both calls will be disconnected when either leg hangs up.||Y or N||N|
|maxDuration||Set the max duration for the call in seconds, after this time has been reached the call will be disconnected. NOTE: If you set the max duration higher than the available credit in your Teleoh account the max duration will default to max based on the funds in your account.||Seconds, such as 60 for one minute.|
|noanswer_timeout||The amount of time in seconds to wait before redirecting A leg to the action Url. Works best when using call confirm since answering machines and voice mail count as a call answered.||10-300|
Once the <Dial> element is finished processing the cloud will request the provided action URL to determine how to continue the call flow. The following parameters will be sent either by POST or GET (depending on which method you specify).
|CallUUID||The unique identifier for the call.||Can be used to manage the call in real-time with the API.|
|CallTo||The number the call is to.||Incoming: The DID number
Outgoing: The number dialed
|CallFrom||The number the call is from.||Incoming: The number calling the DID
Outgoing: SIP username (part before the @)
|CallDirection||The direction of the call.||inbound or outbound|
|CallTime||The time the channel was created, usually the same time billing starts.||year-month-day hour:minute:seconds In CST/CDT Time Zone.|
|API_USER_ID||Your API user ID||Useful if managing multiple accounts for clients.|
|RecordUrl||The full URL where you can access the call recording. "record" attribute must be set to Y.||IMPORTANT: Only returned when the A leg call flow continues (redirect attribute set to Y). If A leg hangs up first the recording will only be posted to the callbackUrl when the DialAction is "hangup" since no further request to the action Url will take place.|
|RecordingID||The recording ID.||The recording ID.|
|RecordingDuration||The recording duration.||MM:SS|
The callbackUrl notifys you of events such as when the called party answers the call or when digits are pressed. If you provide the callbackUrl attribute the cloud will POST the following parameters the callbackUrl provided. NOTE: The cloud will only POST to your callbackUrl, the GET method is not supported.
|DialAction||The action of the call back or event.||answer,ringing,digits or hangup|
|DialALegUUID||The unique identifier for the A leg of the call.|
|DialBLegUUID||The unique identifier for the B leg of the call.||Available only after if DialAction is answer or hangup.|
|DialBLegStatus||The status of the B leg of the call.|
|DialDigitsMatch||The digits pressed by the A leg while on the call.||Will only be posted when DialDigitsMatch is provided.|
|DialDigitsPressedBy||Who pressed the digits that match either DialDigitsMatch or DialDigitsMatchBLeg||aleg or bleg|
|DialBLegFrom||Dial caller number or SIP endpoint for B leg. Only available when DialAction is set to answer, digits or hangup.|
|DialBLegTo||Dial called number or SIP endpoint for B leg. Only available when DialAction is set to answer, digits or hangup.|
|API_USER_ID||Your API user ID|
Using the below example, five numbers and two SIP endpoints will be dialed. When the call is answered all will hear the confirm_message.mp3 audio which will ask them to press 1 to accept the call. The first user to accept gets the call.
<heg> <Response> <Dial action="http://yoururl.com/yourscript.language" method="POST" hold_music_url="relaxed" caller_id_number="14692145044" caller_name="John Doe" confirm_sound_url="http://yoururl.com/confirm_message.mp3" confirm_key="1" callbackUrl="http://yoururl.com/call_back_script.language" digitsMatch="*"> <Number>12145551212</Number> <Number>12145551213</Number> <Number>12145551214</Number> <Number>12145551215</Number> <User>email@example.com</User> <User>firstname.lastname@example.org</User> </Dial> </Response> </heg>
Dial a single number or SIP endpoint without confirmation.
<heg> <Response> <Dial action="http://yoururl.com/yourscript.language" method="POST" hold_music_url="relaxed" caller_id_number="14692145044" caller_name="John Doe"> <User>email@example.com</User> </Dial> </Response> </heg>