CallXML 3.0 Development Guide Home  |  Frameset Home
  Introduction to Token Calls  |  TOC  |  Introduction to XPath  

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
saurin
6/30/2009 12:14 PM (EDT)
This is a good technique for generating outbound call, but this solution requires the two pages to be uploaded to your webserver and then there is a third file (that we have no control on) which maps the tokenid and initiates the call through voxeo.

How could we implement similar outbound call on stand alone Prophecy system?

Regards,

Saurin
VoxeoDante
6/30/2009 12:26 PM (EDT)
Hello,

You will want to define a route in the call routing tab of the management console to point to the Application.jsp

http://docs.voxeo.com/prophecy/8.0/callrouting.htm

Then you would have the Web application point to the token for the application.  So it would make an HTTP request to

http://127.0.0.1/callxml.start/(routeID)

This would then make a call to the HTTP address in the route (Application.jsp) and pass along any query string parameters to the Application.jsp.

The prophecy server would then invoke the callxml application returned by the JSP.

I hope that makes sense.

Please let me know if there is anything else I can do to clarify.

Cheers,
Dante Vitulano
Voxeo Corporation
saurin
7/1/2009 7:37 AM (EDT)

saurin
7/1/2009 8:57 AM (EDT)
Dear Dante,

Got it working with following url

http://[ip of server]:9999/CallXML.start?tokenid=[route ID]

Thanks,

Saurin
voxeojeremyr
7/1/2009 9:09 AM (EDT)
Hello,

That is great news.  We are glad that you were able to get it working.  Please let us know if you have any additional questions.

Regards,
Jeremy Richmond
Voxeo Support
grajeev72
10/6/2011 1:51 PM (EDT)
Hi,

How is token mapping points to our asp file i.e. where we should write the code to map the Token to our .asp file.

Regards,
Rajeev
VoxeoDustin
10/6/2011 4:03 PM (EDT)
Hey Rajeev,

Your application URL is the Voice URL option under your application settings in Application Manager. The token assigned to that application will launch the Voice URL assigned to it when invoked.

Regards,
Dustin Hayre
Technical Account Lead
Voxeo Corporation

login
  Introduction to Token Calls  |  TOC  |  Introduction to XPath  
© 2012 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site