FYI, a new version of Prophecy was released last Thursday. Version 8.0.198.0 is now available for download. The very detailed release notes go into all the many changes and fixes. Enjoy…
This is a guest post from Mark Headd, a voice application developer who was one of the first 10,000 users of our platform, and was originally published on his Vox Populi blog on May 6, 2008.
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
If you use SIP to connect to your voice appliction, one of the very nice things about CCXML is that you have full access to the underlying SIP headers that were sent as part of the SIP connection. With access to the SIP headers, you can then record information or make decisions in your code based on the contents of those headers.
First, let’s take a look at a typical SIP INVITE message that begins a call between two parties:
INVITE sip:1234@company2.com SIP/2.0 Via: SIP/2.0/UDP proxy.company2.com:5060;branch=z9hG5bK21ghi7ab34 Via: SIP/2.0/UDP sip.company1.com:5060;branch=z9hG4bKnashds7 To: sip:1234@company2.com From: sip:dan@company1.com;tag=451248 Call-ID: 324817637683475998ababcc10 CSeq: 1 INVITE Contact: sip:dan@company1.com Max-Forwards: 50 P-Asserted-Identity: "Dan York" <sip:dan@company2.com>
In CCXML, any and all of those headers are available to you using the following syntax:
event.connection.protocol.sip.headers['To']
You can use this information in a conditional statement, in a variable, or in a log statement such as this:
<log expr="'*** The SIP To header is ' + event$.connection.protocol.sip.headers['To']“/>
Note that for the headers whose names do not include a dash in them, there is also a shorter style:
<log expr="'*** The SIP From header is ' + event$.connection.protocol.sip.headers.to"/>
If the header names do include a dash in them, then they do need to be enclosed in brackets and single quotes. Here are some more examples of accessing the SIP headers from a connection object:
event.connection.protocol.sip.headers['To'] event.connection.protocol.sip.headers['P-Asserted-Identity'] event.connection.protocol.sip.headers.from
Let’s take a look at where you might see this code (shown in red) appear within a (admittedly VERY basic and not very useful) CCXML file:
<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
<eventprocessor>
<transition event=”connection.alerting”>
<log expr=”‘*** The calledID is ‘ + event$.connection.local”/>
<log expr=”‘*** The caller ID is ‘ + event$.connection.remote”/>
<log expr=”‘*** The SIP From header is ‘ + event$.connection.protocol.sip.headers.from”/>
<accept/>
</transition>
<transition event=”connection.connected”>
<log expr=”‘*** Call was accepted ***’”/>
<disconnect/>
</transition>
<transition event=”connection.disconnected”>
<log expr=”‘*** Call was disconnected ***’”/>
<exit/>
</transition>
<transition event=”connection.failed”>
<exit/>
</transition>
</eventprocessor>
</ccxml>
Now here all we did was access the SIP header and then log one piece of information. Next time we’ll take a look at a more involved example where we use the SIP headers to change the actions inside the CCXML application.
If you would like to try out this code in a working environment head on over to www.voxeo.com/free and either join our (free) hosted development platform or download our (free) Prophecy software.
Technorati Tags:
applications, ccxml, sip, voxeo, prophecy, voice, voip
This is a guest post from Mark Headd, a voice application developer who was one of the first 10,000 users of our platform, and was originally published on his Vox Populi blog on April 25, 2008.
<var name="playAudio" expr="true"/>
It’s default setting is true, and this can be changed to false to prevent these files from playing. The typical method for checking a variable like this one to determine if an audio file should be played looks something like this:
<if cond="playAudio"> <audio src="myFile.wav"/> </if>
There isn’t anything wrong with this, and since there isn’t a “cond” attribute on the <audio/> tag there aren’t very many good alternatives. There is one alternative method that I rather fancy that uses the JavaScript conditional operator to distill this to a single line of code:
<audio expr="playAudio ? 'myRealAudioFile.wav' : 'myFakeAudioFile.wav'"/>
This shortcut allows us to assign a value to the audio file reference via the “expr” attribute, instead of using an explicit URI to the location of an audio file. The way the operator behaves is to first evaluate the condition on the far left side — if it evaluates to true then the first expression is assigned as the URI of the audio file. If it evaluates to false, then the second expression is used.
The trick here is that the second expression resolves to a bogus audio file — it doesn’t exist. This will not cause a fatal error in your application, it will simply cause Prophecy not to play an audio file (it can’t because the file doesn’t exist).
The JavaScript conditional operator can come in very handy in CCXML as well. For example, there are times in CCXML where I want to use <dialogterminate/> to end a call, but I may not be certain which dialog a caller is in — the JavaScript conditional operator can come in handy here:
<dialogterminate dialogid="loggedIn ? voiceMailDialog : loginDialog"/>
Since the “dialogid” attribute is an expression, we can use the JavaScript conditional operator to check and see if a caller has logged into a voice mail system to retrieve their voicemail. If there loggedIn status is true, we assume that they are in the voiceMailDialog and yank them from that. Otherwise, we assume they are in the first dialog and yank from there.
There are surely other ways to do these things, but in my humble opinion the JavaScript conditional operator deserves some attention as a powerful shortcut for doing things in CCXML or VoiceXML using the Voxeo Prophecy platform.
Technorati Tags:
voicexml, ccxml, voxeo, prophecy, javascript, mark headd, voice, applications
This is a guest post from Mark Headd, a voice application developer who was one of the first 10,000 users of our platform, and was originally published on his Vox Populi blog on April 17, 2008.
I decided to whip up a simple application that would allow a caller to search for E85 and Bio-diesel fuel stations in their state. Some of the specific goals that I had in mind when I got started were:
The fruits of one weekend of labor can be downloaded here. To set up and test this application, you will need the following:
Sign Up With StrikeIron:
Create an account with StrikeIron and sign up for the Super Data Pack Web Service. This is a collection of web services that allow for up to 10,000 hits / month at no charge (where are you going to get a better deal than that?). You’ll also want to sign up for the Global SMS Pro Web Service – this is the service that is used to send SMS messages from the GreenPhone application. Note – this service is priced quite differently than the Super Data Pack Web Service – only 10 free hits before you start paying. If you want to use this service for anything more than just testing out how to send an SMS message from Voxeo Prophecy, you’ll need to get your wallet out.
Make note of the user ID (email address) and password used to create your StrikeIron account – these will be needed momentarily.
Download and install Voxeo Prophecy:
Download and install the Voxeo Prophecy software. Follow all of the instructions for installing and obtaining a license – a two-port license (which will support 2 concurrent phone calls) is free. Right now, prophecy only runs on Windows, but a Linux version is in the pipeline.
Download and Configure GreenPhone:
Download the GreenPhone application and extract it to a new directory under c:\{Prophecy install path}\www\. (For example, on my Windows machine I’ve extracted to c:\Program Files\Voxeo\www\GreenPhone\). You don’t have to run the GreenPhone application on the same machine as Prophecy – if you decide to deploy it on another machine, it must support PHP 5 – GreenPhone makes use of the PHP SOAP and SimpleXML extensions.
Once this is complete, navigate to the directory where you just extracted the GreenPhone application files. Go to the directory called “php”, and open the file called common.php. At the top of this file, enter the credentials from your StrikeIron account. Save and close the file.
Creating a Call Route for GreenPhone:
Open the Prophecy Management Console in your web browser (http://127.0.0.1:9995/mc.php) – the default user ID and password are admin/admin. Click on the “Call Routing” option on the left hand menu – this is where you will set up a call route to the GreenPhone application.
Pick one of the numbered route Ids (e.g., Route 1 ID) and make the following changes:
Making a test call:
Now that Prophecy is installed, fire up the SIP Phone that it is bundled with – you should see the Prophecy icon in your system tray. Click on it, and select “SIP Phone” from the menu. When the SIP Phone launches, select Options. In the SIP Proxy / Registrar Options section, enter your cell phone number in the Local Username field (e.g., 2125551234). Click OK, and restart your SIP Phone. This last step allows your cell phone number to be delivered as the caller ID (or ANI) on the test call you are about the make, even though your initiating the call from a SIP phone.
GreenPhone is built to use ANI to look up E85 and Bio-Diesel stations in the caller’s home state. We do this by invoking the U.S. Area Code Information Web Service that is part of the StrikeIron Super Data Pack to determine which state a caller is calling from. There are additional web services in the StrikeIron Super Data Pack that we can invoke to locate Bio-Diesel stations and E85 Stations — the methods invoked on these last two services require us to identify the state we want a listing of stations for.
The caller’s ANI is also used to send the details on a particular E85 or Bio-Diesel station via text message to the caller’s phone – so if you enter your cell phone number in the Voxeo SIP Phone as described above, you can get details on a station that may be near you sent directly to your cell phone.
As an aside, you’ll notice that a single phone call can result in up to 4 web service invocations — not really sure if that’s “too many” but there are probably some opportunities for caching that I’ll be discussing in the next couple of posts on this, as I describe in more detail how to interact with web services via Voxeo Prophecy.
Now you are ready to place a test call. When your SIP Phone restarts, go to the field called Dial String and enter “sip:green@127.0.0.1” (without the quotes). Click dial and you are now interacting with the GreenPhone application!
You’ll notice (and hopefully enjoy) the unique sounds I’ve tried to used throughout the application. All of them were obtained from the FreeSound Project and modified to conform to the Prophecy standard for audio files with Audacity.
There are some obvious limitations to how this application currently works, and the VUI clearly needs some refinement (DTMF only at this point).
In the next several posts, I’ll point to this application to discuss examples on how to accomplish things in VoiceXML and CCXML using the Voxeo Prophecy Platform.
Have a happy Earth Day on 4/22!!
Just a brief update on my piece about how to use voice with Google’s App Engine… I now have been invited into the preview of Google’s App Engine, so I’ve created a second application on our Evolution platform with this one pointing to my shiny new GAE app at:
http://voicexmltest2.appspot.com/
For now, it’s the same (lame) python code, but the app does have it’s own phone numbers:
Direct Local # (857) 362-8430 PIN Access (800) 289-5570 then PIN: 9996075378 PIN Access (407) 386-2174 then PIN: 9996075378 Skype VoIP +99000936 9996075378 FWD VoIP **86919996075378 SIP VoIP sip:9996075378@sip.voxeo.net
Why didn’t I simply modify the original Evolution application? Well, I could have, but I figured this way I can also still experiment with the AppDrop.com application as well.
The nice thing with a true Google App Engine account is that I can use “appcfg.py” to automagically update the files up on the App Engine site, which is very slick. (Thanks, Google, for the invite!) Next week, my intent is to work with the python code to get it actually manipulating the XML… stay tuned… (and check my original article if you would like to experiment with voice and Google App Engine, too).
Technorati Tags:
application platforms, applications, google, appengine, google appengine, , voxeo, voicexml, python, xml, voice, voice apps, voice applications
What if you could use a phone number as a “geotag” to identify a location and get directions? What if you could call into a service, enter in a phone number of where you want to go and then your current phone number - and get directions?
In this video episode of Voxeo Talks, Moshe Yudkowsky discusses his “phone 2 directions” voice mashup that lets you call in, enter in a phone number and get directions spoken to you based on the location associated with that phone number. Here’s the video:
If you want to try it out, just call
+1-312-252-1758
enter in your phone number and you will receive driving directions from your location to the eComm 2008 conference next week in Silicon Valley (where this app will be discussed). And yes, it will give you directions from clear across the country.
Note that there is an obvious caveat with this service - if you use a phone number that’s with a cell phone, a VoIP service or in a different region through Local Number Portability, it probably won’t work.
More information about this voice mashup is available at:
www.phone2directions.com/
For those of you developing apps, Moshe has made the source code available for those who want to create your own mashups at:
p2dir.sourceforge.net
I’ve not yet looked at it myself but Moshe indicates that he’s showing folks how to connect to MapQuest and StrikeIron (source of reverse number address lookups) in his PHP code. Since the code is open source, I’ll be curious to see what else people do with it. Note that Moshe built it for ifbyphone using their developer API. (Ifbyphone is a partner of Voxeo who is providing very cool services to small and medium-size businesses.)
You can, of course, develop your own voice mashups for free using either our hosted Evolution platform or download our Prophecy premise platform at:
www.voxeo.com/free
Meanwhile, enjoy the video, call the demo (1-312-252-1758) and let us know what you think! (And if you are out at eComm you’ll be able to see this demo and talk to both us and folks from Ifbyphone.)
Technorati Tags:
applications, voip, voxeo, mashups, phone mashups, voice mashups, open source, geotags, geotagging, location
You are currently browsing the archives for the Prophecy category.
RSS Feed