Tutorial: Outbound CallXML Applications via HTTP

So you want to make an outbound call from your homepage by clicking on a super-cool swoosh button that you spent three hours designing in JavaButtonFactory 1.4, but HTML just doesn’t seem to have that tag.

CallXML to the rescue.

The ability to initiate new callxml sessions without the need for an originating telephone call is one of the truly cool features of CallXML. Through a normal HTTP request, even your mom can trigger sessions and write code for the telephone. But she still can't make a pot roast that tastes like anything but shoe leather.

Note: This tutorial requires the use of outbound dialing priveleges, which must be provisioned by voxeo support. If you have not contacted us to get these permissions, click here to learn how you can get hooked up with this feature.

Let’s examine some code that "triggers" an outbound call from a very simple HTML web page. This involves three separate files, two of which you have control over. Here is the first file:


<title>Demonstration Session Trigger Application</title>
<form name="SampleForm"  action="http://api.voxeo.net/SessionControl/CallXML.start "  method="POST">
    <input type="hidden" name="tokenid" value="sometoken"> 
 
Phone number to call:<br>
  <input type="text" name="Phone" size="20" maxlength="20" value=""><br><br>

Enter your text to say here:<br>
  <input type="text" name="TTS" size="100" value=""><br><br>
  <input type="reset" value="Clear">
    
  <input type="submit" name="submitMe" value="Give me a call!">
</form>

This is an extremely basic webpage that allows a user to enter a telephone number and a message to read via text-to-speech over the phone. The key to the page is the action attribute of the <form> itself and the following hidden variable:

action="http://api.voxeo.net/SessionControl/CallXML.start "

<input type="hidden" name="tokenid" value= "sometoken">

Here is where we actually call the script that initiates the outbound call (remember I said there were three total pages in this process, but you will only have control over two? This is the page you will always call for initiating sessions via HTTP).

Notice the "tokenid." That will appear just like a phone number in your community.voxeo.com account URL mappings, (look under the header 'linked tokens' in your VAM). You simply need to map a URL that spits out callxml to that token. The HTML form will pass the variables first to the session initiator script and then on to whatever page is mapped to the token in question (in this case, "SOMETOKEN").

In our example, we are using an HTML <form> tag that passes three variables ("Phone," "TTS," and "submit"). Any and all such variables are passed into the session initiator script, and then passed from there into the callxml script. Thus, the telephony events are completely transparent from this, the web side.

The web side of our equation is now complete. Now we need to script the third file in the equation -- the CallXML script itself (again, the session initiator script will call whatever URL is mapped in your account to the tokenid that is passed in via the querystring -- if there is no tokenid present, there will be no session creation):

Note: The Voxeo Webhosting servers do not allow for any form of server side markup. The only file extensions allowable on our free application hosting servers are '.grammar', '.gsl', and '.xml'. As such, you will need to find an appropriate host that supports the markup you intend to use before proceeding with any of the following tutorials.

CALLXML 3.0 ASP EXAMPLE


<?xml version="1.0" encoding="UTF-8"?>  
<callxml version="3.0">
<%
'------------------------------------------------------------------------
' Need to use ASP to grab the variables from the querystring.
'------------------------------------------------------------------------
Phone   = request.querystring("phone") 
Message = request.querystring("TTS")
'----------------------------------------------------------------------------
' Now we will transfer those ASP variables to callxml variables
'----------------------------------------------------------------------------
response.write "<assign var=""Phone""   value=""" & Phone   & """/>"
response.write "<assign var=""Message"" value=""" & Message & """/>"
%>
  <call value="$Phone;" maxtime="30s"/>
  <on event="answer">
    <do label="MessageBlock" repeat="3">
      <say>$Message;</say>
      <wait value="3s"/>
    </do>
  </on>
 
  <on event="callfailure">
    <log value="***** Call failed to connect *****."/>
     
    <sendemail from="MyApp@here.com" 
     to="YourEmail@there.net" type="debug"> 
     We caught an error in our application.  Details follow... 
    </sendemail> 

  </on>
</callxml>

CallXML 3.0 PHP Example


<?php
header('Cache-Control: no-cache');
echo '<?xml version="1.0" encoding="UTF-8"?>';
echo "<callxml version=\"3.0\">";
echo "<assign var=\"Phone\" value=\"" . $_REQUEST["Phone"] ."\" />";
echo "<assign var=\"Message\" value=\"'" . $_REQUEST["TTS"] ."'\" />";
?>

  <call value="$Phone;" maxtime="30s"/>
  <on event="answer">
    <do label="MessageBlock" repeat="3">
      <say>$Message;</say>
      <wait value="3s"/>
    </do>
  </on>

  <on event="callfailure">
    <log value="***** Call failed to connect *****."/>
   
    <sendemail from="MyApp@here.com"
    to="YourEmail@there.net" type="debug">
    We caught an error in our application.  Details follow...
    </sendemail>

  </on>
</callxml>

In this example script, we used ASP or PHP to grab the querystring variables and turn them into callxml variables. This could be done using ColdFusion, Perl, JSP, etc. -- any server-side scripting language will have an easy method of gathering GET/POST variables.

Unlike many CallXML scripts, the first thing we do is place an outbound telephone call using the <call> tag. If someone answers the telephone call (<on event="answer"> event is matched), then we simply read the text message entered on the website. That’s all there is to it. You are now empowered to make snazzy buttons and integrate the web and the phone in ways your children will talk about for years...

CallXML 3.0 source code.

Upload it!

All we need to do now is to upload our two pieces of code to our webserver, and make certain that our token mapping points to our asp file. Then, you can pull up our HTML page, enter a number, and a message, and start annoying all your friends!

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Introduction to Token Calls

| TOC

| Introduction to XPath