XML Scripting Reference

ExternalScripts are a sequence of XML instructions executed when a call is placed to a number of your domain, or when a call is placed from one of your SIP accounts, trunk and from a web page (using our WebRTC/Flash UDP JavaScript API).

ExternalScripts are located in a web server, and their URL can be set/updated through the APIdaze REST API ExternalScript objects.

NOTE: The web server that serves the XML content of your ExternalScript must set the Content-type HTTP header to text/xml.

The "Example Requests" at the bottom of this section define what you will receive when Apidaze receives an inbound call or SMS and sends to your application (external script URL).

 

<dial/>

Description

Place a call to a destination. A destination can be an external number, a SIP account or a voicemail box. Multiple destinations can be dialed simultaneously or in sequence.

Attribute Description Allowed Values Default
timeout The maximum time (in seconds) to ring the call destination. postive integer 60
max-call-duration The maximum time (in seconds) for this call. The corresponding timer starts when the call is answered. postive integer Not set
strategy When dialing multiple destinations, ring them in sequence or simultaneously. simultaneous,sequence simultaneous
action The URL of the external script to fetch when the callee ends the current call. URL URL of the current script
answer-url A URL containing XML instructions to run on the callee side when the callee answers the call, and before establishing the call with the caller. URL Not set
caller-hangup-url A URL containing XML instructions to run on the callee side when the caller hangs up. URL Not set

Examples

Route the call to an external number (1234567890).

<?xml version="1.0" encoding="utf-8"?>
<document>
 <work>
  <dial>
   <number>1234567890</number>
  </dial>
  <hangup/>
 </work>
</document>

Route the call to a SIP URI. Of course, this URI must be valid and reachable.

<?xml version="1.0" encoding="utf-8"?>
<document>
 <work>
  <dial>
   <sipaccount>anyaccount@anysipdomain.com</sipaccount>
  </dial>
  <hangup/>
 </work>
</document>

 

 

<answer/>

Description

Answer the call immediately. Useful if your want to play a sound file using the playback tag.

Example

<document>
 <work>
  <answer/>
  <playback file="http://www.mydomain.com/welcome.wav"/>
  <hangup/>
 </work>
</document>

<playback/>

Description

Play a sound file to the caller, accessible at a URL or locally. The file location can be set as a text enclosed in the tag, or in the “file” attribute. To be accessible locally, the file must have been uploaded using the REST API, see the Media File actions in the API Reference section. The file format must be .wav, sample frequency 8000Hz, 1 channel (mono).

Attribute Description Allowed Values Default
file The file location of the wav file to play URL, filename none

Examples

Answer the call, play the sound file located at http://www.mydomain.com/welcome.wav, then hangup.

<document>
 <work>
  <answer/>
  <playback>http://www.mydomain.com/welcome.wav</playback>
  <hangup/>
 </work>
</document>

Same example, the sound file being set in the “file” tag.

<document>
 <work>
  <answer/>
  <playback file="http://www.mydomain.com/welcome.wav"></playback>
  <hangup/>
 </work>
</document>

Play a sound file previously uploaded at APIdaze. We need low latency here!

<document>
 <work>
  <answer/>
  <playback file="welcome.wav"></playback>
  <hangup/>
 </work>
</document>

<ringback/>

Description

Play a ringback tone or file to the caller. This action is non-blocking, that is, the next XML instrunction will be executed without waiting. This can be useful for example if you want to play a custom file with dialing a number.

If the enclosed text of the tag is empty, the regular ringback tone is played.

The file format must be .wav, sample frequency 8000Hz, 1 channel (mono).

Example

Play the sound file located at http://www.mydomain.com/welcome.wav while calling a SIP account.

<document>
 <work>
  <answer/>
  <ringback>http://www.mydomain.com/welcome.wav</ringback>
  <dial>
   <sipaccount>bob</sipaccount>
  </dial>
  <hangup/>
 </work>
</document>

<echo/>

Description

Echo back received audio to the caller with some delay.

Example

Answer the call and echo the audio back, with a delay of 500 ms.

<document>
 <work>
  <answer/>
  <echo>500</echo>
 </work>
</document>

<hangup/>

Description

Hangup the call immediately. Important note : when a call is not explicitly hanged up, APIdaze will ask for more XML instructions by re-fetching the URL of the external script in case the last instruction has been processed.

Example

Hang up the call without even answering it.

<document>
 <work>
  <hangup/>
 </work>
</document>

<intercept/>

Description

Intercept a channel. The channel is identified by a UUID parameter that must have been stored in some way by your script. You can map this application with a dialing sequence (e.g. : *8) to implement group-pickup or directed-pickup functions.

Example

Intercept the channel identified by f28a3e29-dac4-462c-bf94-b1d518ddbe2d. Guessing the UUID is not that tricky. See a more detailed example here :

<document>
 <work>
  <answer/>
  <intercept>f28a3e29-dac4-462c-bf94-b1d518ddbe2d</intercept>
  <hangup/>
 </work>
</document>

<speak/>

Description

Say the text enclosed in the tag.

Attribute Description Allowed Values Default
lang The language this text will be spoken en-US,fr-FR,it-IT,es-ES en-US

Example

Answer the call, say a text in French, wait for 5 seconds, and loop for ever.

<document>
 <work>
  <answer/>
  <speak lang="fr-FR">Bonjour et bienvenue chez APIDAIZE. Vous pouvez patienter, mais n'oubliez pas de raccrocher.</speak>
  <wait>5</wait>
 </work>
</document>

<bind/>

Description

Get the digits dialed, and take an action. Digits are accepted, and regular expressions too, the XML text must then start with ~. The bind tag is a sub-tag of the playback and speak tags.

NOTE: Once the digits match a bind statement they are passed as URL parameter "dialed_digits" to the URL specified in the action attribute of your code.

Attribute Description Allowed Values Default
action The URL to fetch if the digit matches URL none

 

Examples

 

Answer the call, ask the caller to enter a digit, and provide a new sequence of XML instructions according to the choice of the caller. The timeout for gathering the digit is set to 5 seconds (5000 ms). If the timer expires, the current set of XML instructions if fetched again.

<document>
 <work>
  <answer/>
  <speak input-timeout="5000">
   Press one to or two, or any digit, and we'll handle your call, or not.
   <bind action="http://www.mydomain.com/get_digits.php?bind=1">1</bind>
   <bind action="http://www.mydomain.com/get_digits.php?bind=2">2</bind>
   <bind action="http://www.mydomain.com/get_digits.php?bind=other">~[3-9]</bind>
  </speak>
 </work>
</document>

Example with regex matching 4 to 10 digits

<speak input-timeout='20000'>
  Please enter your PIN
  <bind action='https://anyurl'>~[0-9]{4,10}</bind>
</speak>

<wait/>

Description

Suspend the execution for a while

Example

Answer the call, say a text in french, wait for 5 seconds, and loop for ever.

<document>
 <work>
  <answer/>
  <speak lang="fr-FR">Bonjour et bienvenue chez APIDAIZE. Vous pouvez patienter, mais n'oubliez pas de raccrocher.</speak>
  <wait>5</wait>
 </work>
</document>

<conference/>

Description

Join an audio conference

Example

Join the audio conference named “my_meeting_room”.

<document>
 <work>
  <speak>You will now be placed into the conference</speak>
  <conference>my_meeting_room</conference>
 </work>
</document>

<record/>

Description

Record the call.

Attribute Description Allowed Values Default
name The name you want to give to your recording file. NOTE: There is no suffix in your filename, it is automatically suffixed with ".wav" filename uuid of call
on-answered Starts recording when the call is answered true, false false
aleg Record the A-leg of the call.. caller to callee true, false true
bleg Record the B-leg of the call.. callee to caller true, false true

Example

<document>
 <work>
  <answer/>
  <wait>2</wait>
  <speak lang="en-US">
   Please leave a message.
  </speak>
  <record name='example1' />
  <wait>60</wait>
  <hangup/> 
 </work>
</document>

Example Requests

These are example requests for an inbound call and an inbound SMS that Apidaze will send to YOUR application (external script URL).

APIdaze Script Parameters

Each call triggers an HTTP request to your script, and HTTP parameters are the keys that let you handle your calls. Your script is fetched at the beginning of the call, and also when the call ends (with the “exiting” parameter set to “true”). The main parameters that you’ll find are :

  • session_id : a UUID like (RFC 4722) string that identifies the current channel that placed the call.
  • destination_number : the number dialed by the caller.
  • caller_id_number : the phone number, or SIP address, or any string that identifies the caller.
  • caller_username : the name that identifies the caller, if available.
  • url : the URL of the fetched script.

Calls can come from the PSTN, SIP accounts under your domain, SIP trunks and the web using our WebRTC/Flash UDP JavaScript API. Depending on the source of the call, various parameters can be sent along with each HTTP request to help you process the call :

  • exiting : a variable set to true when the set of XML instructions of the current script is exhausted. Note that if the is not explicitly called, the script will be fetched again to call for a new set of XML instructions.
  • bridge_status : a status variable sent as the result of the tag. Values can be “SUCCESS”, “BUSY”, or “NO_ANSWER”.
  • dialed_digits : a status variable sent as the result of the tag that contains the digits entered by the caller.

Also note that if someone places a call from the web, any parameter set in the JavaScript API is passed to your script, therefore allowing full control over your web calls!