Teleoh Cloud XML Docs


<Dial>

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.



Attributes

The <Dial> element supports the following attributes that enhance its behavior:

Parameter Description Allowed Default
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


Action Request Parameters

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).

Parameter Description Details
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


callbackUrl POST Parameters

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.

Parameter Description Details
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


Ring group with confirmation

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>23892389378@mysipaddress.com</User>
         <User>48934843833@mysipaddress.com</User>
      </Dial>
   </Response>
</heg>


Simple dial

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>48934843833@mysipaddress.com</User>
      </Dial>
   </Response>
</heg>