Script Reference

APIdaze Script 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 APIdaze’s REST API ExternalScript objects.

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

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

<document>
 <work>
  <dial>
   <number>0123456789</number>
  </dial>
  <hangup/>
 </work>
</document>

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

<document>
 <work>
  <dial>
   <sipaccount>anyaccount@anysipdomain.com</sipaccount>
  </dial>
  <hangup/>
 </work>
</document>

Route the call to an external number (0123456789) through another carrier (my-carrier). “my-carrier” must be the name attribute of a SIP trunk set up in the REST API, see the SIP Trunk methods in the API Reference section.

<document>
 <work>
  <dial>
   <number>0123456789@my-carrier</number>
  </dial>
  <hangup/>
 </work>
</document>

Route the call to an external number (0123456789) and a sip account (bob@vm.yourdomain.apidaze.voip), with a timeout of 10 seconds. Ring both devices in sequence.

<document>
 <work>
  <dial> 
   <number timeout="10">0123456789</number>
   <sipaccount timeout="10">bob</sipaccount>
  </dial>
  <hangup/>
 </work>
</document>

Route the call to multiple sip accounts or multiple external numbers, in sequence (first example) or at the same time (second example).

<!-- sequential -->
<document>
 <work>
  <dial>
   <sipaccount timeout="10">480</sipaccount>
   <sipaccount timeout="15">490</sipaccount>
  </dial>
  <hangup/>
 </work>
</document>

<!-- simultaneous -->
<document>
 <work>
  <dial timeout="20">
   <sipaccount>480</sipaccount>
   <sipaccount>490</sipaccount>
   <number>0102030408</number>
  </dial>
  <hangup/>
 </work>
</document>

Check a voicemail box 480 (bobmailbox).

<document>
 <work>
  <voicemail>480</voicemail>
  <hangup/>
 </work>
</document>

Route the call to a voicemail box 480 (bobmailbox).

<document>
 <work>
  <dial>
   <mailbox>480</mailbox>
  </dial>
  <hangup/>
 </work>
</document>

Route the call to a sip account (bob@vm.yourdomain.apidaze.voip), play a file to inform Bob that a call is coming, then bridge the two call ends.

<document>
 <variables>
  <callername>Alice</callername>
 </variables>
 <work>
  <dial answer-url="http://www.mydomain.com/incoming-call.php">
    <sipaccount>bob</sipaccount>
  </dial>
  <hangup/>
 </work>
</document>

Here we make use of a variable that we define (callername), and which value has been set by some internal application when the call is placed using the URL of the ExternalScript object.

This variable and its value is passed to the URL at http://www.mydomain.com/incoming-call.php when Bob answers the call.

The XML instructions at http://www.mydomain.com/incoming-call.php :

<document>
 <work>
  <speak>Hi Bob, Alice is calling.</speak>
 </work>
</document>

<answer/>
Description

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

Example

Answer the call, play a sound file, then hangup.
```
<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 <playback/> 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.

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

Example

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 <ringback/> tag is empty, the regular ringback tone is played.

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.

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

Example

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>

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

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 <hangup/> 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 <dial/> tag. Values can be “SUCCESS”, “BUSY”, or “NO_ANSWER”.
dialed_digits : a status variable sent as the result of the <bind/> 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!