Passing in parameters via token string

Note: This tutorial requires the enabling of outdial privileges on the Voxeo network, and the provisioning of a alphanumeric token string to your application. In order to get hooked up with all these neat features, check our Support Guide for all the juicy details.

Virtually everyone in the business of building commercial IVR applications requires the ability to pass parameters into their applications. In most cases, the process to grab these parameters is quite cumbersome and requires the addition of server-side capabilities. In the newest CCXML version, 1.0 W3C, there is a pretty nifty session variable that we can reference in order to grab parameters from the initial querystring. Let's say we have the following token-initiated outbound call:

http://api.voxeo.net/SessionControl/CCXML10.start?tokenid=abc123

Now, let's also say we need to pass in two parameters which are critical to the application. We'll call them 'foo' and 'bar.'

http://api.voxeo.net/SessionControl/CCXML10.start?tokenid=abc123&foo=123&bar=456

This, in turn, tacks on foo and bar to the actual start URL of your application.

http://myserver.com/myApp.jsp?foo=123&bar=456

In the past, we've had to enlist the help of server-side scripting to grab the parameters from the querystring. However, in CCXML 1.0 W3C, we don't need server-side... that could get ugly. There's actually a built-in session variable which allows us to reference this directly in the application code itself.

session.values

This session variable is an Associative Array containing a list of session parameters that are passed upon the creation of the session.

So, going back to our foo and bar example, if we wanted to log these in a transition, here's how it's done. We'll use the connection.alerting transition in this case, and throw in some conditional logic just to spice things up a bit.


<transition event="connection.alerting">
  <log expr="'*** foo is equal to: ' + session.values.foo"/>
  <log expr="'*** bar is equal to: ' + session.values.bar"/>
  <if cond="session.values.foo == '123'">
    <!-- accept the incoming call if foo equals 123 -->
    <accept/>
  <elseif cond="session.values.bar == '456'"/>
    <!-- accept the incoming call if bar equals 456 -->
    <accept/>
  <else/>
    <!-- otherwise we reject the incoming call -->
    <reject/>
  </if>
</transition>

In this case, foo is equal to 123, so we accept the call and the user moves on through the application. Need a more robust example? Not to worry, the next one will show a functionality that many novice and commercial IVR developers utilize.

This example will require passing a phone number into the application, which in turn makes an outbound call to that number. Additionally, the "spoofed" caller ID is passed in the same way.

The token string

http://api.voxeo.net/SessionControl/CCXML10.start?tokenid=abc123&phonenum=14075551122&cid=4071112222

The CCXML application

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml">

<meta name="author" content="Jeff Menkel"/>
<meta name="copyright" content="2008 Voxeo Corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<var name="phonenum" expr="session.values.phonenum"/>
<var name="cid" expr="session.values.cid"/>

  <eventprocessor>
    <transition event="ccxml.loaded">
     <log expr="'*** placing call ***'"/>
     <createcall dest="'tel:+' + phonenum" callerid="cid"/>
    </transition>

    <transition event="connection.connected">
      <log expr="'***** CONNECTION.CONNECTED: OUTBOUND *****'"/>
      <dialogstart src="'MyDialog.xml'" type="'application/voicexml+xml'"/>
    </transition>

    <transition event="dialog.exit">
      <log expr="'***** DIALOG EXITING *****'"/>
      <exit/>
    </transition>
  </eventprocessor>
</ccxml>

The VoiceXML dialog


<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >

  <form>
    <block>
    <prompt>
      Congratulations!  You have successfully passed in parameters to your application!
    </prompt>
    </block>
  </form>
</vxml>

As you can see, this nifty little feature is an important cornerstone of the new CCXML language. It really sets CCXML apart from it's CallXML and VoiceXML counterparts. So, what are you waiting for? Download the source code and try it out yourself!

ANNOTATIONS: EXISTING POSTS

mheadd

8/11/2008 4:52 PM (EDT)

Can you provide a little more infomation on the difference between using "session.values" and "session.external" when injecting values into a CCXML script?

Is one preferable over the other? Is one more compliant with the spec than the other?

Thanks!

voxeojeff

8/11/2008 5:27 PM (EDT)

Hello Mark,

The way that our current implementation of CCXML 1.0 works is that, both the session.values and session.external arrays return the same values. They are, in actuality, aliases of one another. You can use whichever you wish, since the end result is in fact the same. I hope this helps to clarify things, please let me know if you have any more questions.

Regards,

Jeff

VoxeoDante

8/11/2008 5:33 PM (EDT)

Hello Mark,

As a follow up to Jeff's earlier post. Session.external is no longer part of the CCXML spec. For that reason I would suggest moving forward using the session.values. As far as our platform is concerned you can use either, but to make the XML more compliant session.values would be the preferred choice.

All the best,
Dante Vitulano

G: Send Element & HTTP requests

| TOC

| Passing Variables to VXML