Please do check it out if you are interested in seeing the future of our application platform - and please do send along any comments and feedback that you have. We definitely do appreciate it all.

Technorati Tags: voxeo, prophecy, windows, linux, macosx

ShareThis

First lets get a proper definition for variable scope.  The scope of a variable defines when and where the variable exists and may be accessed. When the VXML browser exits the scope where the variable is defined, the variable is out-of-scope and cannot be accessed. When a variable is in scope, it can be accessed by both VoiceXML and ECMAScript.

Here is a table of the different scope levels of variables in VXML:

Scopes	Declared In	Initialized In	Where accessible	Becomes Unavailable
Session	By the VXML browser	At the beginning of a session	Anytime during the session	At the end of the session
Application	In the root document	When VXML browser loads the root document	Throughout the application	When the VXML browser leaves the root document
document	In the <vxml> document	When the VXML browser loads the document	Within the <vxml> element	When VXML browser leaves the document
dialog	In the <field> element of a <form> or <menu> element	When the VXML browser loads the element	Within the element	When the VXML browser leaves the element
anonymous	In a <block>, <filled> or <catch> element	When the VXML browser begins to interpret the element	Within the element	When the VXML browser leaves the element

Here is an example of document scoped variable.  As you can see it is accessible throughout the current VXML document.

<?xml version=”1.0″?> <vxml version=”2.0″>

<var name = “counter” expr = “0″/>

<form id=”F_1″> <!– additional VXML code –> <filled> <assign name=”counter” expr = “counter + 1″/> </filled> </form>

<form id=”F_2″> <!– additional VXML code –> <filled> <assign name=”counter” expr = “counter + 2″/> </filled> </form>

</vxml>

Here is an example of a dialog scoped document.  In form “F_1″ the value of “counter” after the assign <element> would be 1.  In form “F_2″ the value after the <assign> value would be 2.

<?xml version=”1.0″?> <vxml version=”2.0″>

<form id=”F_1″> <!– additional VXML code –> <filled> <var name = “counter” expr = “0″/> <assign name=”counter” expr = “counter + 1″/> </filled> </form>

<form id=”F_2″> <!– additional VXML code –> <filled> <var name = “counter” expr = “0″/> <assign name=”counter” expr = “counter + 2″/> </filled> </form>

</vxml>

It is also good to know that variable references will match the closest applicable scope. You can prefix a reference with a scope name, such as application.counter, for clarity or to resolve ambiguity.

We hope this clears up a little confusion about VXML variables and where they are defined and when they can accessed.

Jeremy Richmond VXML Certified Developer

ShareThis

Technorati Tags: applications, voice, voip, voicexml, ccxml, voxeo, tutorials

ShareThis

OSCON - Greetings… and a teaser about my talk on voice mashing up with identi.ca 

As I said in the video, I’ll be speaking today at 5:20pm US Pacific time on the topic of “Mashing up Voice and the Web using Open Standards and XML” where I’ll be showing how you can use VoiceXML and CCXML to do interesting connections to “web 2.0″ sites. Needing a site to use for my examples, I decided to this round of demos with identi.ca, the new open source microblogging site (like Twitter, only open source).

Once my talk is over, I’ll post the slide deck here in this blog and also the code to the demos I’ve written. I’m looking forward to it… it should be fun! (If you’re here at OSCON, I will apparently be in room D137 at 5:20pm.)

P.S. You can also follow me on identi.ca at identi.ca/danyork

ShareThis

While you’re utilizing your free Voxeo developer account, you might as well keep the whole shabang free, right? Head on over to x10hosting.com or forwardhosting.com, and register for an account. These are two of the very few hosting companies that will allow you to run cron jobs for free. Now that you are all setup, let’s get into the design aspect, cron job first.

While cron web interfaces will certainly be different, the underlying principal is the same: cron will wait until the system time matches your job time, and then will execute an action. Most web portals to cron jobs will allow you specify minute, hour, day, month, and weekday.

Let’s assume you have to call your wife every Friday night at 5 pm to let her know that you’re coming straight home from work. We’ll set minute to “00″, the hour to “17″, the weekday to “4″, and the rest to “*”. This will make the cron job execute on Fridays at 1700. You may need to adjust the time on your cron job to account for differences between system time and your time. For example, the x10hosting box on which my cron job runs is set to US central time. For the cron job command, use the Unix command “curl” like so:

curl http://api.voxeo.net/SessionControl/CCXML10.start?tokenid=dd5a1d7f44e97f49856eb6e894c9c669d152e89a571f6201eb3b265045b7a1d2bb52ff8d9856fbbbbbbbbbba\&numdial=5551231234

This command sends an http request to api.voxeo.net for our CCXML 1.0 token. The request also contains the variable “numdial.”

( Please note that the backslash is used in cron to escape the ampersand. This request will not work properly from a browser window )

Now for the XML part:

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

<var name="state0" expr="'init'"/>
<var name="callid_out1"/>
<var name="callid_out2"/>
<var name="pin"/>
<var name="holdMusicDlg"/>

<eventprocessor statevariable="state0">

  <transition state="init" event="ccxml.loaded">
    <createcall dest="'tel:+15555555555'" connectionid="callid_out1" callerid="'1112223333'" timeout="'30s'"/>
  </transition>

  <transition state="init" event="connection.connected">
    <assign name="callid_out1" expr="event$.connectionid"/>
    <assign name="state0" expr="'enterpin'"/>
    <dialogstart src="'null://?termdigits=#&text=Press 1 and then pound if you want to dial' + session.values.numdial"&
    type="'application/x-fetchdigits'"/>
  </transition>

  <transition state="enterpin" event="dialog.exit">
    <log expr="'PIN = [' + event$.values.digits + ']‘”/>
    <if cond=”‘1′ != event$.values.digits”>
      <exit/>
    <else/>
      <assign name=”pin” expr=”event$.values.digits”/>
    </if>

    <assign name=”state0″ expr=”‘calling’”/>
    <dialogstart src=”‘holdingPattern.vxml’” type=”‘application/xml+vxml’” namelist=”pin” dialogid=”holdMusicDlg”/>
    <createcall dest=”‘tel:+1′ + session.values.numdial” connectionid=”callid_out2″ callerid=”‘5555555555′”/>

  </transition>

  <transition state=”calling” event=”connection.failed”>
    <assign name=”state0″ expr=”‘callfailed’”/>
    <dialogterminate dialogid=”holdMusicDlg”/>
  </transition>

  <transition state=”callfailed” event=”dialog.exit”>
    <assign name=”state0″ expr=”‘playingCallFailed’”/>
    <dialogstart src=”‘callFailure.vxml’” type=”‘application/xml+vxml’” connectionid=”callid_out1″/>
  </transition>

  <transition state=”playingCallFailed” event=”dialog.exit”>
    <disconnect/>
  </transition>

  <transition state=”calling” event=”connection.connected”>
    <if cond=”event$.connectionid == callid_out1″>
      <exit/>
    <else/>
      <assign name=”state0″ expr=”‘beforeBridging’”/>
      <dialogterminate dialogid=”holdMusicDlg”/>
    </if>
  </transition>

  <transition state=”beforeBridging” event=”dialog.exit”>
    <send name=”‘pause’” target=”session.id” delay=”‘200ms’”/>
  </transition>

  <transition state=”beforeBridging” event=”pause”>
    <assign name=”state0″ expr=”‘bridged’”/>
    <join id1=”callid_out1″ id2=”callid_out2″/>
  </transition>

  <transition event=”error.conference.join”>
    <log expr=”‘*** ERROR DURING JOIN ***’”/>
    <exit/>
  </transition>

  <transition event=”error.*”>
    <log expr=”‘an error has occured (’ + event$.reason + ‘)’”/>

    <voxeo:sendemail to=”‘yourEmail@there.com’”
      from=”‘myApp@here.com’”
      type=”‘debug’”
      body=” ‘generic error detected ! ‘ “/>
    <exit/>
  </transition>
</eventprocessor>
</ccxml>

This application has a fairly simple flow. It calls 1-555-555-5555, and then asks the callee to press 1 and then # to connect to whatever number was passed in via the http request (in this case numdial=5551231234).

That’s it. To make this work for you, you need to change four values:

1. token ID in http request 2. numdial variable in http request 3. “5555555555″ is found twice in the CCXML file - both instances should be changed to your number 4. sendemail “to” and “from” in CCXML file

Good luck with your development - mix in a little MySQL and PHP action to make adding more cron jobs easier.

Till next time,

Jeremy McCall Voxeo Network Operations

ShareThis

The first round of changes adds several new features including: message categories, filtering, easy reversing and a new black color theme.

The first thing you will now notice is that when you login you will see a tool bar at the top with a bunch of checkboxes in it:

These boxes don’t do much until you run a search but once you search for something you will start to see some of the power of what it can provide. 

To start with lets run a search for a session and see what we get:

As you can see you get the full set of log messages here. Whats is new here is that you now can see that we have colorizing of the log messages making it easer to pick out the important messages in the log stream. 

The first thing you might want to try doing is clicking on one of the filters and see what happens. For example if you click “Playback” you will filter out everything but the browser playback messages:

The next thing you might want to try is clicking on the “User Filter” button to filter stuff down to only being user facing log messages:

Another new feature is the new button to easily reverse the results to be in chronological order instead of most recent first. This can make it a lot easer to read things like session logs where you are trying to understand the flow of what happened. Do be aware however that if your search spans a large amount of time it may take longer to display the initial search results in this mode since we need to search over the entire time block and gather all the results before we display them in the UI:

Lastly one other thing you may like to try is switching to the “black” theme we now include. To enable this open your preferences dialog and select VoxeoBlack on the theme menu on the General tab:

You will then get your UI rendered in proper old school programer colors:

 Hopefully these improvements will help make the tool more useful.  As always we are looking for feedback on ways we can improve our offerings so please leave us feedback either in the comments below or in our LogSearch feedback forum on the Evolution developer site. 

ShareThis

Technorati Tags: prophecy, voxeo, voicexml, ccxml

ShareThis

* Pre-compiled Statistical Language Model grammars * Leveraging TargusInfo services for advanced recognition accuracy

However, the IVR project requirements dictate what we can, and can’t do as developers, so in some cases, we have to try and whip out a user grammar that takes alpha, or alpha-numeric input. As mentioned in our last blog entry, there are a few things we can do to stack the deck to try and squeeze more accuracy out of these grammars so that we don’t end up with frustrated callers, but the plain truth is that we will never, ever be able to write a grammar that accepts alphabetical characters to be 100% accurate using todays recognition technology. What we will do today is twofold:

(1) Craft an SRGS+SISR subgrammar for alphabetical, and numeric characters

(2) Plug this grammar into a mixed-initiative form dialog that will minimize (but not fully address!), the possibility for mis-recognitions.

Those developers who have the need for such a grammar and dialog within their production-grade applications are advised to take this basic framework as a starting point, and then expand on it by:

(a) Test carefully with a broad range of users, and to fully flesh out alternate utterance values for alphabetic characters

(b) Apply item weighting to specific characters based on the probability of a given character versus another like-sounding character - this will depend greatly on the specific usage of the grammar

(c) Track results by using w3c-compliant utterance recording, and logging all shadow variables, so that these results can be used to further tune and tweak our grammar for maximum accuracy

(d) Consider using n-best post-processing as an additional confirmation step to ensure that the results we receive are indeed accurate

For today’s entry, lets assume that we need to track a three digit zip code, which are prevalent in Canadian locales. Our predefined format for utterance values are “Alpha Digit Alpha”, and luckily, not all alpha characters are applicable: Instead of trying to recognize 26 letters accurately, we only need to recognize 16, which helps a lot!

We won’t dig into the specifics of a mixed-initiative form dialog, as we have already done so in our mixed-initiatve tutorial, but the gist is that this feature of VoiceXML allows us to fill multiple fields with a single utterance, and breaking up each alpha and numeric character into it’s own recognition field greatly cuts down on disambiguation problems that can occur.

For the purposes of brevity, what we have below is a stripped-down version of our fully fleshed-out grammar, but you may download the full grammar, and the mixed-initiative dialog right here, which contains lots more inline notations.

<?xml version= "1.0"?><grammar xmlns="http://www.w3.org/2001/06/grammar" xml:lang="en-US">

<rule id="canadianZip" scope="public">

<one-of>

<!-- ALL THREE FIELDS FILLED -->

<item>

<item>

<ruleref uri="#alphaRule1"/>

<tag>out.alphaSlot1=rules.alphaRule1.alphaSlot1;</tag>

</item>

<item>

<ruleref uri="#numRule"/>

<tag>out.numSlot=rules.numRule.numSlot;</tag>

</item>

<item>

<ruleref uri="#alphaRule2"/>

<tag>out.alphaSlot2=rules.alphaRule2.alphaSlot2;</tag>

</item>

</item><!-- ONLY TWO FIELDS FILLED -->

<item>

<item>

<ruleref uri="#alphaRule1"/>

<tag>out.alphaSlot1=rules.alphaRule1.alphaSlot1;</tag>

</item>

<item>

<ruleref uri="#numRule"/>

<tag>out.numSlot=rules.numRule.numSlot;</tag>

</item>

</item>

<item>

<item>

<ruleref uri="#numRule"/>

<tag>out.numSlot=rules.numRule.numSlot;</tag>

</item>

<item>

<ruleref uri="#alphaRule2"/>

<tag>out.alphaSlot2=rules.alphaRule2.alphaSlot2;</tag>

</item>

</item>

<item>

<item>

<ruleref uri="#alphaRule1"/>

<tag>out.alphaSlot1=rules.alphaRule1.alphaSlot1;</tag>

</item>

<item>

<ruleref uri="#alphaRule2"/>

<tag>out.alphaSlot2=rules.alphaRule2.alphaSlot2;</tag>

</item>

</item>

<!-- ONLY ONE FIELD FILLED  -->

<item>

<ruleref uri="#alphaRule1"/>

<tag></tag>

</item>

<item>

<ruleref uri="#numRule"/>

<tag>out.numSlot=rules.numRule.numSlot;</tag>

</item>

</one-of>

</rule>

<rule id="alphaRule1" scope="public">

<one-of>

<item weight="1.0">

<one-of>

<item> ex</item>

<item> ax</item>

<item> x </item>

</one-of>

<tag>out.alphaSlot1="X"; </tag>

</item>

</one-of>

</rule>

<rule id="numRule" scope="public">

<one-of>

<item> one <tag>out.numSlot="1"; </tag>  </item>

</one-of>

</rule>

<rule id="alphaRule2" scope="public">

<one-of>

<item weight="1.0">

<one-of>

<item> ay</item>

</one-of>

<tag>out.alphaSlot2="A"; </tag>

</item>

</one-of>

</rule>

</grammar>

In brief, our top-level rule assumes that we can have any of the following entries:

"X1A""X"

"X1"

"XA"

"1"

"1A"

And in the event that we get one or two characters matched in our utterance, the VoiceXML mixed-initiative logic will then take over, and prompt the caller to fill in any “blanks” remaining.

A few things of note about the grammar defined below is that in the event that we receive only a single alpha utterance, we will assume that it is the first character, not the last. Additionally, when we construct a grammar that contains multiple slot returns, it is required that we explicitly define the slot values all the way up the chain: if we didn’t define the “out.[slotname]=rules.[rulename].[subslot]” within the context of the top-level rule, the last slot value would overwrite all others, meaning that we would only get a value for “alphaSlot2″ within the VoiceXML dialog. To illustrate even further, the below snippet for a top-level return would make this a reality:

<item> 
<ruleref uri="#alphaRule1"/>

<ruleref uri="#numRule"/>

<ruleref uri="#alphaRule2"/>

</item>

You’ll also see that each possibility for character recognition is specified within the top-level rule, so in the event that we get 1, 2 or 3 character strings, we can pipe the return value back to the VoiceXML, and let the mixed-initiative dialogs then access the sub-rules (alphaRule1/2 and numRule), individually as needed.

We also illustrated in brief how one can define multiple like-sounding utterance values that return the same interpretation value, and defined an for our alphaRule1 entry simply to show how this can be done: The task of taking this framework, and turning it into a grammar that satisfies any given project rests in the hands of you, the capable IVR developer.

=^)

Till next time,

Matthew Henry Director of Customer Support Voxeo Corporation

Useful Links

• AlphaNumeric Grammar and Mixed-Init Code download
• SISR specification
• SRGS Grammar Specification: Grammar weighting
• SISR Default Slot Assignments
• VXML 2.0 specification: Mixed-Initiative Dialogs

Technorati Tags: voicexml, voxeo, srgs, sisr, grammars, ivr, applications, tutorials

ShareThis

First, some vocabulary. In a “state machine”, there are a series of “states“, such as being “on” or “off”. There are then “events” that cause there to be a “transition” between states.

Now to illustrate this, let’s take the typical action hero film (such as any one of the James Bond movies) and describe it as a series of “states”:

1. Hero is relaxing on a beach with a drink in some exotic locale.

2. Hero is preparing for mission (getting briefing, gadgets, etc.)

3. Hero is hunting for evil villain.

4. Hero is fighting evil villain and his minions.

5. Hero is relaxing on a beach in some other exotic locale in the company of rescued beautiful woman.

There are obviously other “states” that occur in an action movie, many of which involve beds, but in an effort to: a) keep this blog “safe for work”; and b) keep our example simple, we’ll reduce it to this list. Graphically, we could depict this as something like:

The hero can remain in any one of these “states” indefinitely (and in some films it seems like the hero does!) until there is some event that triggers a “transition” between the states. Let’s look at our list again and add in some events:

1. Hero is relaxing on a beach with a drink in some exotic locale.

   • Receives visit from courier who says his assistance is needed immediately. (Alternatively and more exciting for a movie, a team of assassins attempts to kill him.)

2. Hero is preparing for mission (getting briefing, gadgets, etc.)

   • Receives final briefing, heads to airport, etc.

3. Hero is hunting for evil villain.

   • Finds evil villain (or is found by evil villain).

4. Hero is fighting evil villain and his minions.

   • Blows up villain and his lair, saves world, rescues beautiful woman.

5. Hero is relaxing on a beach in some other exotic locale in the company of rescued beautiful woman.

At a 10,000 foot level, you can describe most action movies in this pattern. A series of states where events trigger transitions between those states.

So what does this have to do with CCXML, eh?

Well, you could take the basic successful inbound call to a CCXML application and describe it in the following states and events:

1. CCXML application is waiting for connections.

   • Call is received.

2. Application enters “Alerting” state to decide what to do with the call.

   • Application accepts call.

3. Application is connected to incoming call and performs actions such as playing dialogs, accepting input, etc..

   • Application finishes - or caller hangs up.

4. Application is disconnected from call and performs any final actions.

   • Application finishes post-call activity and exits.

5. Application returns to waiting for connections.

Graphically, we could illustrate it like this:

Conceptually, this is what it looks like. I would, though, note, that the “waiting” state I’ve shown here is not typically a part of the actual CCXML application but rather is part of the application platform on which your CCXML application is housed. For instance, the “platform” could be our Evolution hosted platform or a copy of our Prophecy premise platform running on your network. When a call is received by either Evolution or Prophecy, your CCXML application is loaded and (in this example) the “connection.alerting” event is sent which triggers the transition into the “Alerting” state.

You can think of this in a similar fashion to a web server. Your Apache (or other) web server is sitting there waiting for connections. When it receives a connection, it loads the appropriate page which may contain an application which is then executed. CCXML works in a similar fashion (and yes, there are exceptions… remember, I’m trying to keep this tutorial simple!).

In any event, let’s see what this looks like in CCXML code:

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <eventprocessor>
    <transition event=”connection.alerting”>
    <log expr=”‘*** Incoming call from Caller ID: ‘ + event$.connection.remote”/>
    <accept/>
    </transition>
    <transition event=”connection.connected”>
      <log expr=”‘*** Call was accepted ***’”/>
      <disconnect/>
    </transition>
    <transition event=”connection.disconnected”>
      <log expr=”‘*** Call was disconnected ***’”/>
      <exit/>
    </transition>
  </eventprocessor>
</ccxml>

That’s it. The <transition> tag indicates what actions should be taken when the event included in the “event” attribute occurs. Conceptually this is a transition between states. So when the event “connection.alerting” is received by this application the code in the first <transition> is executed. At the end of that block you can see the <accept/> command which is the action that causes a new event (”connection.connected“) to occur. Likewise, <disconnect/> and <exit/> in later states signal that a new event has occurred and a transition needs to occur.

Your task, then, is to write the actions that occur in each state since this code above does really nothing except accept and then hangup a call (and generate log entries). During the “alerting” state, for instance, maybe there are some phone numbers from which you do not want to accept calls. You may have some conditional logic there that rejects calls from some numbers and then accepts calls from all others. In the “connected” state, obviously, is where the meat of your application goes. What are you going to do with the caller?

With this framework in mind, you can now dive into the “Learning CCXML” section of our CCXML documentation and see the examples there that flesh out the very simple outline I’ve given here.

I should note, of course, that my simple example doesn’t even closely illustrate all the “states” in CCXML. What happens if a call fails in some way other than just a disconnect? What if there are errors in your application? How about outbound calls where the “alerting” concept doesn’t make sense? We go into the different states in our documentation and the actual CCXML specification from the W3C also has this nice diagram (click on the image to see it larger):

(Hint: For an outbound call, the initial state equivalent to “alerting” is “progressing“.) This, too, does not show all the states, but does provide a richer view of the flow of a typical CCXML application. As you’ll see in the documentation, there’s a lot more you can do with states in CCXML. You can create your own events that you us the <send> command to trigger a transition to a new state. There are a range of pre-defined states as well, that both our documentation and the W3C CCXML specification describe in more detail.

Again, it is all about the CCXML application describing a series of “states” and what actions occur during that state. Events trigger transitions between states.

Got it? Ready to start actually building applications? If so just head over to www.voxeo.com/free and sign up for either a free developer account on our Evolution hosted platform or download our free Prophecy premise platform to run on your own server. Figure out your states and away you go…

P.S. If you are really intrigued by all the theory around state machines, you might want to check out the “Semantics” section of another W3C draft language called SCXML (”State Chart XML”) which dives into the theory around Harel State Tables and much more. The aim of the (draft) SCXML effort is to create a more generic state machine language which is not tied to telephony as CCXML is. If all you want to do is write voice applications, feel free to skip these links entirely!

Technorati Tags: applications, state machines, ccxml, scxml, w3c, voxeo, programming, xml, voip, voice, voice mashups, phone mashups

ShareThis

A few weeks ago, I posted about accessing web services from CCXML using PHP. This post will demonstrate how to do the same thing, only from VoiceXML. We’ll be using Voxeo Prophecy and PHP for this example. We’ll also be referring to the GreenPhone project — available free for download — for the sample code.

Before we dive in, its important to keep in mind that there are a number of different techniques for getting information from web services into a VoiceXML dialog. This is just one method — there are many others. Voxeo even has its own platform-specific way of accessing SOAP web services via JavaScript. Ultimately, the method you employ needs to be a good fit for the environment your working in and the requirements of your project.

Using the greenSoapClient Class

In the last post on this topic, I demonstrated how to use a simple PHP class as a way to access multiple SOAP-based web services from CCXML. This class forms the basis of our method for accessing web services from VoiceXML as well. However, in this instance, instead of using the CCXML <send/> element, we’ll use a VoiceXML subdialog.

Subdialogs in VoiceXML are typically used to create reusable dialog components for capturing common types of input, like a series of digits (e.g., credit card numbers, account numbers, etc). They can also be used to compartmentalize complex interactions with a caller and provide a simple interface for accessing results. By way of example, this is how the OSDMs from Nuance work, as well as the Targus service from Voxeo. We’ll borrow this approach to access a web service from StrikeIron that will send the details of an E85 or bio-diesel station to a cell phone via SMS.

Setting up our Subdialog

In order to send an SMS message with details on an E85 or bio-diesel station, we’ll need 2 things; the station details, and a cell phone number to send it to.

In order to send the details on a station from VoiceXML to PHP, we’ll pack it up in a pipe-delimited string called “detailsToSend” (I won’t go into too much detail about how this is done in this post — to learn more, refer to the GreenPhone Project code). The cell phone number we are sending to is obtained from the caller ID of the calling party, stored in a variable named “ani”. Details on how to access caller ID are given in a previous post.

Our subdialog call will look like this:

<form id="sendDetails">
<catch event="error.badfetch">
<prompt>
There was a problem sending the station details to your phone.
<break strength="weak"/>
</prompt>
<goto next="#goodbye"/>
</catch>

<subdialog name="sendSMS" src="../php/sendStationDetails.php" namelist="ani detailsToSend">
<prompt>
Sending the station details to
<say-as interpret-as="telephone"><value expr="ani"/></say-as>
</prompt>
<filled>
<if cond="sendSMS.result==0">
<prompt>Your message has been sent.<break strength="weak"/></prompt>
<else/>
<prompt>
There was a problem sending the station details to your phone.
<break strength="weak"/>
</prompt>
</if>
<goto next="#goodbye"/>
</filled>
</subdialog>
</form>

We use the attributes on the <subdialog> element to give our subdialog a name (which we’ll use to access the results sent back from PHP), to specify where to POST our variables to and also to specify which variables to POST.

You’ll also notice that we have set up a handler here for an “error.badfetch” event. This is a good habit to get into whenever you set up a request to an external resource (like a PHP script). If the script isn’t there or has problems, an “error.badfetch” event will get returned and unless you specified a handler for this event, your day will not end well.

Additionally, we’ve set up logic in our filled block to inspect the result of the subdialog call. We access the result as a property of the subdialog, using the name we set up in the <subdialog> element and the dot notation (”.”) familiar to JavaScript.

<if cond=”sendSMS.result==0″>

… code logic goes here …

</if>

With this in mind, our PHP script needs to send back a variable called “result”. How do we do this? Lets take a look at the PHP script:

A Simple Subdialog using PHP

The subdialog that we want to render is extremely simple — we only need to render enough VoiceXML to declare a variable called “result” and return it to the parent dialog. We’ll do this after we make our web service call to send the SMS message.

There are two pieces of information returned from the StrikeIron web service that we are interested in; a string that holds the response message from the service (i.e., “success”, “failure”, etc.) and a number indicating the outcome of the web service call.

We’ll take these two bits if information and assign them to PHP variables:

$result = $xml->soapHeader->ResponseInfo->ResponseCode;
$message = $xml->soapHeader->ResponseInfo->Response;

Now, we want to write out these variables in a simple VoiceXML subdialog:

<?xml version="1.0" encoding="utf-8"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
<form id="F_1">
<log>*** SMS response message was: <?php echo $message; ?>. ***</log>
<block>
<var name="result" expr="<?php echo $result ?>"/>
<return namelist="result"/>
</block>
</form>
</vxml>

As discussed above, this creates just enough VoiceXML to instantiate a variable and return it to the parent dialog. For good measure, we’ll write out the web service string (contained in the PHP variable $message) as a log statement, in case it contains information we want to look at later.

Why This Approach?

Using this technique for accessing web services from VoiceXML provides a couple of advantages. First, it allows us to completely separate the presentation layer (the VoiceXML) from the logic used to invoke the web service. This is a fairly standard design practice that makes creating the dialog much easier for a developer that does not necessarily know a whole lot about web services. With this approach, they don’t really need to — they only need to know that the subdialog call will return a variable called “result” whose value can be inspected to determine what to do next.

Additionally, because the parent dialog is just static VoiceXML it may be possible to cache it. Since the parent dialog isn’t dynamic, it can be cached for fast access, while the subdialog — which must be dynamic — is the only component sent from the web server to the VoiceXML platform each time a caller accesses the application. Careful design can yield additional caching opportunities that can make your applications more efficient and less bandwidth intensive.

In the next post, we’ll explore one additional method for accessing web service from VoiceXML. Stay tuned…

Technorati Tags: voicexml, tutorials, php, voip, applications, phone, voxeo

ShareThis