Voxeo Developers Corner

Would you like to learn more about our recent releases of Prophecy 11 and VoiceObjects 11? In our August 2011 Developer Jam Session I outlined what is new in the new releases of both our core products. You can download the PDF of the slides or the recording of the session from the Jam Session page. You can also watch the session on YouTube:

And if you’d like to try it out yourself, just visit our download page to download a free copy of Prophecy 11 or VoiceObjects 11 for Windows, Linux or Mac OS X.

Flickr credit: kubina

Are you looking to learn how to use VoiceXML to create interactive applications? While we offer all sorts of great documentation and tutorials at www.vxml.org, we also have a series of tutorial blog posts here called “VoiceXML for Web Developers” that walk you through the process of getting started, all in the context of creating an application for a fictional pizza restaurant, “Strato Pizza”.

Here is the series so far:

• VoiceXML for Web developers: Introduction
• VoiceXML for web developers: Hello World
• VoiceXML for Web Developers: Collecting Input
• Collecting touch tone input (VoiceXML for Web Developers)
• Processing Input (VoiceXML for Web Developers)

The VoiceXML files used in those tutorials are all available on our Github account at https://github.com/voxeo/Voicexml-samples.

The first introduction article explains the steps you need to go through to set up a free developer account in our Evolution developer portal if you do not already have an account.

I am going to be continuing the series a bit more, so stay tuned for further installments. And please, do let us know (in the comments to this post or via email) how helpful these type of article series are. We have ideas for a few others like this.

Yes it really is as easy as one-click… check it out in the video below – and then head on over to our Evolution developer portal to give it a try:

If you want more information about our text messaging capabilities – or to find out about availability of SMS numbers in regions where you want to send or receive text messages, please contact us.

Do you want to learn more about how you can use VoiceXML to create voice (and now SMS) applications? If so, we have an incredibly easy URL for you to remember:

www.vxml.org

That’s it. In fact, you can even drop the “www” and just go to “vxml.org“. Simple. Easy.

There on the site you will find tutorials, VoiceXML sample code, a detailed VoiceXML language specification, a handy VoiceXML element reference, and appendices covering everything from VoiceXML best practices to advanced VoiceXML topics.

You can try out all the examples, too, either in our hosted cloud with a free account on our Evolution developer portal or on your own premises with a free download of our Prophecy platform for either Windows, Linux or Mac OS X. In our hosted cloud, you get free inbound telephone numbers and outbound calling, plus Skype and SIP connectivity.

Plus, you can let your VoiceXML applications communicate not just with voice but also via SMS and IM. One app – multiple channels. For free. (Pretty cool, eh?)

And, if you run into trouble or can’t figure out how to do something in VoiceXML, our Customer Obsession Team is standing by at “support@voxeo.com” or in our web forums to answer your questions. (And yes, they gladly answer questions from developers using free accounts!)

This post is part of a series exploring voice applications and VoiceXML through the eyes of a web developer. For the rest of the series, see the index.

If you want to follow along with these examples, you should create a free VoiceXML hosting account in Evolution. Complete instructions were in the first installment of the series.

Today I’m continuing the development of our application for the fictional Strato Pizza. Previously, I asked the caller for their pizza topping preference and their phone number, using both speech recognition and touch tone input. Today I’m going to do something with that input, and repeat the order to the customer.

Within VoiceXML, I can access the values of any fields with <value expr="fieldName$.utterance"/>. This code will return the matched value from my grammar.

Since I want to simply repeat the order and the phone number, I’m going to add a <block> element to my existing form. Inside the block, I’ll add a <prompt> element with the text I want to speak.

    <block>
      <prompt>
        You ordered <value expr="topping$.utterance"/> on your pizza.
      </prompt>
    </block>

When the VoiceXML browser reaches this line, it will speak my text, substituting whatever the caller said in response to the field named topping for topping$.utterance. If the caller asked for ham, the spoken text will be just like if my prompt said, “You ordered ham on your pizza.”

You can use multiple value expressions in a single prompt. I also want to tell the customer that they’ll get a call if there’s a problem with their order. I’ll repeat their phone number to them. Then I’ll thank them for their order and hang up.

    <block>
      <prompt>
        You ordered <value expr="topping$.utterance"/> on your pizza. If we have any questions we will call you at <value expr="phone$.utterance"/>. Thank you for your order.
      </prompt>
    </block>

Remember that for the phone number field, I allowed the caller to use either voice or touch tone input with a built in grammar like so:

    <field name="phone" type="phone">
      Please say or enter your phone number.
    </field>

When I access this value with <value expr="phone$.utterance"/> it doesn’t matter if the caller used voice or DTMF input. The grammar gives the same result. So when I read back the phone number, they’ll hear the digits of their phone number spoken back to them.

You can get the code for this example and all other examples from Voxeo’s GitHub account. At GitHub, you can fork or download the VoiceXML application thus far.

This post is part of a series exploring voice applications and VoiceXML through the eyes of a web developer. For the rest of the series, see the index.

If you want to follow along with these examples, you should create a free VoiceXML hosting account in Evolution. Complete instructions were in the first installment of the series.

Yesterday, I added the ability for my fictional Strato Pizza order taking application to ask the user what topping they’d like on their pizza. Now I need to ask them for a phone number, in case Strato is out of a topping and needs to call them.

When putting in a phone number, a lot of callers are comfortable with punching in their number on their phone keypads, while others would prefer to simply speak their number. I want my application to behave in the way that’s most comfortable for the caller, so I’m going to handle both methods of input.

First I create my field and validation code:

  <field name="phone">
    Please say or enter your phone number.

    <noinput>
      <reprompt>
    </reprompt>

    <nomatch>
      I didn't understand that. Please try again.
      <reprompt>
    </reprompt>

  </nomatch>

I’m doing something a little different with the UI here when someone doesn’t enter or say anything. Instead of giving an error message and replaying the prompt, I’m simply replaying the prompt. In the case of a phone number where we’re accepting DTMF and voice input, saying “I didn’t hear that” seems a little silly. Just asking for the caller’s phone number a second time should suffice.

For a grammar, I could create a grammar consisting of every digit…

<grammar type="text/gsl">
  [one two three four five six seven eight nine zero]
</grammar>

… and to make it work with touch-tone input, add a grammar for DTMF digits …

<grammar type="text/gsl">
  [dtmf-1 dtmf-2 dtmf-3 dtmf-4 dtmf-5 dtmf-6 dtmf-6 dtmf-7 dtmf-8 dtmf-9 dtmf-0]
<grammar>

… but that will only accept a single digit. Now what? I could try to create a grammar that captures every possible combination of digits. For a ten digit phone number, that means I’d have a grammar with ten billion words in it. That doesn’t sound very practical. Or I could ask the user for every digit of their phone number, one digit at a time. Hardly usable. The easiest way to accomplish this is to use a special built-in grammar provided by VoiceXML that accepts a group of digits.

To use this built-in grammar, I simply add a type attribute to my <field> element and tell it the field is intended to hold digits.

<field name="phone" type="digits">

Now the caller can say or key in any number of digits. Since this is a phone number, I don’t want the caller telling me his phone number is “six” so I want to add some restrictions to that. Strato is in the United States, so the caller should enter at least 7 digits and no more than 10.

<field name="phone" type="digits?minlength=7;maxlength=10">

But what if the caller has an extension number to add? I could ask them a separate question to find out if they have an extension. Or I could use a different built-in grammar, one actually designed for phone numbers that already recognizes any 10 digit phone number, including extensions.

<field name="phone" type="phone">

You can see a list of all built-in grammars and different ways of including them in the Built-In Grammar Types VoiceXML documentation.

Because I’m using a built-in grammar for the phone number, I don’t need an additional grammar here. This means my complete field definition looks like this:

  <field name="phone" type="phone">
    Please say or enter your phone number.

    <noinput>
      <reprompt>
    </reprompt>

    <nomatch>
      I didn't understand that. Please try again.
      <reprompt>
    </reprompt>

  </nomatch>

This XML snippet will be put into my existing form element, right after the toppings field definition.

You can get the code for this example and all other examples from Voxeo’s GitHub account. At GitHub, you can fork or download the VoiceXML application thus far.

Next up, I’ll take the user’s input and do something with it.

This post is part of a series exploring voice applications and VoiceXML through the eyes of a web developer. For the rest of the series, see the index.

If you missed it, in the first installment of this series I created an application on Evolution and assigned it some phone numbers. For the rest of the series, I’ll be using that application to test my VoiceXML apps. If you want to follow along, go create your own Evolution account.

I’m going to start simple with my first application – just answer and speak some text, then hang up. This way we can get a look at the syntax needed for VoiceXML. Throughout this series, I’ll be building an application for Strato Pizza, a fictional pizza chain. My application here is simply a greeting played when someone calls the chain’s phone number.

As the name implies, VoiceXML is written in XML. So I start with an XML declaration and tell the browser what character encoding to use, just like any other XML document. Then I create a <vxml> element that will hold the application.

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

</vxml>

Inside this element I need a couple of structural elements. <form> is a container that separates different areas of input and output, sort of like different HTML forms and pages. <block> is a container that allows you to conditionally execute code. Although I’m not creating separate inputs and outputs or trying to conditionally execute code, these elements are still needed, since the next elements I’m going to create are required to be inside a <block> and a block must be inside a <form>. Since I’m not using them for anything, I don’t have to worry about any attributes right now.

Now my VoiceXML document looks like this:

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

    </block>
  </form>
</vxml>

Great, now the basic structure is in place and I can put in the meat of the application. All I want to do is say something and hang up, so my application is pretty simple. I can say something by using a <prompt> element and the VoiceXML browser will perform text to speech and say whatever I typed.

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >
  <form>
    <block>
    <prompt>
      Thanks for calling Strato Pizza.
    </prompt>
    </block>
  </form>
</vxml>

That’s it. The whole document. I upload the document to my web server at the URL that I configured my application with in Evolution. When I call this application using the Skype number supplied in Evolution, a text to speech (TTS) engine speaks my text.

This post is part of a series exploring voice applications and VoiceXML through the eyes of a web developer. For the rest of the series, see the index.

I’ll admit it. Before joining Voxeo, I wasn’t much of a voice guy. I’m a web guy. I was pretty sure that voice applications were created through witchcraft. Turns out, there’s no magic involved, just some standards and markup languages. If you can create a web app, you can create a voice app. Voxeo has some great developer documentation and detailed tutorials available through Evolution, our developer portal. Over the next few weeks, I’ll be walking through some examples as I learn, from the perspective of a web developer, VoiceXML, CCXML, and Voxeo’s own CallXML.

I’ll start with VoiceXML. VoiceXML is a W3C standard, just like HTML is. Like HTML, your code is executed in a browser, but instead of a visual browser on a computer screen, in this case it’s a voice browser that you use over the telephone. To test out any of the samples I’m going to create, I’m going to need a VoiceXML browser attached to the telephone network. Voxeo provides developers with free accounts and a phone number so you can build and test your app. You’ll also need a web server to host your XML file, but Voxeo will provide some hosting space for you for free if you’d like.

Go over to Evolution and create an account. Then go to the Application Manager.

Create a new application and call it anything you’d like. Then decide how you want your app to work. For now, I’m only using voice, so I don’t need text messaging. I can always add it in the future if I change my mind.

I need to tell Evolution where my VoiceXML file is at by providing a URL for it. Since I’m going to create a Hello World application and host it on my own server, I’m putting in the URL I intend to use for my VoiceXML file. Again, I can change this later if I decide on a different file name or path.

After I create my app, I have a new tab at the top of the page that gives me some phone numbers I can use to call my application.

Clicking on that tab reveals a local number, a toll-free number, and numbers to call from Skype, SIP, and iNum providers. I can also add a dedicated local number if I’d like. Since I’m going to test with Skype, I don’t need a local number, but if you’re testing from your phone, grab one.

And that’s it. I now have a VoiceXML browser hooked up to the telephone network that I can use to test my application. In my next post a couple of days from now, I’ll create my first app.

Do you want a really simple way to create voice apps? Are you looking for something simpler to write in than VoiceXML?

Throughout this Voxeo Developer’s Corner blog as well as our other blogs, we have tended to focus most of the attention on developing applications using the open standards of VoiceXML or CCXML (Call Control XML). There’s a reason for this… we are huge advocates of open standards and the need to avoid “vendor lock-in” – and we’ve deployed the most standards-compliant VoiceXML implementation out there. We want you to use our voice application platform and stay with us because of our extreme support and outstanding platform… not because we are forcing you to do so.

But recently as I’ve noticed people out there on the Internet seeking something simpler than VoiceXML, it’s become clear that we are not talking enough about the other XML language we support – our own CallXML.

CallXML was created back in 1999 when Voxeo was founded and has gone through several generations of development since that time (the most recent version is CallXML 3.0). It is very simple to use yet also cable of creating very complex applications. It’s also highly scalable with one customer of ours using CallXML for an application that is literally making thousands of simultaneous calls.

So I’m going to spend some time writing here about CallXML and showing how incredibly easy it is to build voice applications using it. You’re welcome to follow along… of course, you don’t have to wait for me… there’s a detailed set of CallXML tutorials and also an Element Summary if you just want to dive into the CallXML elements themselves and start coding.

All you need is a free developer account on our Evolution developer portal or to download a free copy of our premise Prophecy software (and remember that the beta of Prophecy 9 is on Mac OS X and Linux in addition to Windows). Note that I recently posted a step-by-step tutorial of creating an XML application in Evolution and assigning it a phone number that you may find useful.

So with that, let’s stop talking and start writing code…

Let’s start with the very basic program that simply says “Hello, world”. That is accomplished through the <say> element. Here’s how the program looks:

<?xml version="1.0" encoding="UTF-8"?> 
<callxml version="3.0">
    <say>Hello World</say>
</callxml>

Yep, that’s it. Create it in your Evolution account, assign it a free direct-dial US phone number or call it via SIP or Skype. Ta da… you’ve written a CallXML app.

Now if you have come from the world of VoiceXML, you may be more familiar with the <prompt> element and CallXML 3.0 now offers that as well. At first glance it looks very much like the <say> element:

<?xml version="1.0" encoding="UTF-8"?> 
<callxml version="3.0">
    <prompt>Hello World</prompt>
</callxml>

But the <prompt> element also includes some other fun things you can do, such as this:

<?xml version="1.0" encoding="UTF-8"?> 
<callxml version="3.0">
    <prompt repeat="3">Hello World</prompt>
</callxml>

Which, as you might expect, repeats the text three times.

There is a great amount more you can do with the <prompt> element, but I’m going to leave this simple example here and pick up with some more ideas in the next post. Those of you who want to dive in deeper right away can of course look at the examples on the <prompt> element documentation page.

Have fun with it and I’ll dive a bit deeper in Part 2…

Technorati Tags: voxeo, callxml, voicexml, applications, development, voice, xml

The default CCXML wrapper that quietly powers many VoiceXML applications on Voxeo’s Prophecy platform is certainly sufficient for many simple applications. So why should I bother diving into yet another markup language to do re-invent the wheel? Because your application isn’t that simple and you’re a control freak. Or maybe I am. Who knows.

Typically, we can handle post-call cleanup in VoiceXML easily enough by using the <submit> or <data> elements to our server-side cleanup scripts.

  <catch event="connection.disconnect">
     <submit next="cleanup.php" method="POST"/>
  </catch>

While this is a valid way to handle this, VoiceXML requires that we either transfer control to another document(<submit>) or respond with valid XML(<data>). Instead, we can leverage the disconnect event and any other portion of the application that we’d like the call to end to send this data back to our CCXML handler and let it do all the work asynchronously. The bonus here is we can have unfettered control of our voice applications. Once we have this in place, it’s simple work to leverage CCXML to control call duration, pre/post-processing and more.

When using a custom CCXML wrapper to handle post-call cleanup, our VoiceXML disconnect handler will look something like this:

  <catch event="connection.disconnect">
     <exit namelist="my_var1 my_var2 my_var3"/>
  </catch>

Here we’re using the namelist attribute of <exit> to send back our values back to CCXML. We can now handle this inside our CCXML wrapper with a dialog.exit transition:

  <transition event="dialog.exit">
    <log expr="'**** DIALOG COMPLETE - SENDING POST CALL CLEANUP'"/>
    <assign name="dialog_active" expr="false"/>
      <log expr="'my_var1 = ' + event$.values.my_var1"/>
      <log expr="'my_var2 = ' + event$.values.my_var2"/>
      <log expr="'my_var3 = ' + event$.values.my_var3"/>
      <assign name="my_var" expr="event$.values.my_var1"/>
      <!-- sends a POST to our cleanup script -->
    <disconnect connectionid="conn_id"/>
      <send name="'user.call.cleanup'" target="'cleanup.php'" targettype="'basichttp'" namelist="my_var1"/>
  </transition>

The values of our VXML variables are stored in the object event$.values. We can then grab them from the event$.values object by referencing them as event$.values.variablename – in this case, event$.values.my_var1. Since our VoiceXML dialog is complete, we’re ready to end the call. We issue a disconnect to the caller’s connectionid and send our post call cleanup. CCXML’s <disconnect>, unlike VoiceXML’s, physically disconnects the call leg. So now the call leg is ended, we’re free to handle our post-processing without paying to keep that call leg up. Brilliant!

Now that we’ve shot off our post-processing request, we can handle the send.successful event and close the session out, right? Well, we could do that, but how do we know the request was received successfully? Note, this next portion is a Voxeo specific extension and is not part of the W3C spec and requires the Voxeo namespace - <ccxml version=”1.0″ xmlns:voxeo=”http://community.voxeo.com/xmlns/ccxml”>.

Instead of assuming everything went swimmingly with our post-processing, we can be sure by having our server-side send back an event to the CCXML browser if we format the body of the response like this:

  user.cleanup.successful
  my_var1=foo
  my_var2=bar

Note that we can inject not only an event here, but name/value pairs, though they are entirely optional. Now that my server side has responded, with an event, I’ll need to handle this in my CCXML:

  <transition event="user.cleanup.successful">
    <log expr="'**** POST CALL CLEANUP COMPLETED SUCCESSFULLY'"/>
    <log expr="'**** EXITING SESSION'"/>
     <exit/>
  </transition>

Last, but very definitely not least, we will want to ensure our session does not stay alive after the call leg has disconnected. Since we are doing a little post-processing, we don’t want to end the session immediately, as we’ll want to give that time to process. So, we’ll simply shoot off a delayed user event to kill the session 60 seconds after a disconnect and prevent the zombie apocalypse.

  <transition event="connection.disconnected">
     <!-- send to unconditionally end a runaway session -->
     <send name="'user.kill.unconditional'" target="session.id" delay="'60s'"/>
  </transition>

  <transition event="user.kill.unconditional">
     <log expr="'**** UNCONDITIONAL KILL - EXITING SESSION'"/>
       <exit/>
  </transition>

That’s it. Find the complete CCXML below.

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

      <meta name="author" content="Dustin Hayre"/>
      <meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<!-- how long to wait before assuming a session is a runaway and tearing it down -->
<var name="conn_id"/>
<var name="dialog_id"/>
<var name="my_var"/>

<eventprocessor>
  <transition event="connection.alerting">
    <assign name="conn_id" expr="event$.connectionid"/>
    <accept connectionid="conn_id"/>
  </transition>

  <transition event="connection.connected">
    <log expr="'**** STARTING DIALOG TO CONNECTION ID ' + conn_id"/>
     <!-- edit SRC attribute to point to VXML dialog -->
     <dialogstart src="'dialog.vxml'" connectionid="conn_id" dialogid="dialog_id"/>
  </transition>

  <transition event="dialog.exit">
    <log expr="'**** DIALOG COMPLETE - SENDING POST CALL CLEANUP'"/>
      <log expr="'event$.values.my_var1 = ' + event$.values.my_var1"/>
      <assign name="my_var" expr="event$.values.my_var1"/>
      <!-- sends a POST to our cleanup script -->
      <send name="'user.call.cleanup'" target="'cleanup.php'" targettype="'basichttp'" namelist="foo"/>
  </transition>

  <transition event="user.cleanup.successful">
    <log expr="'**** POST CALL CLEANUP COMPLETED SUCCESSFULLY'"/>
    <log expr="'**** EXITING SESSION'"/>
     <exit/>
  </transition>

  <transition event="error.*">
    <log expr="'**** ERROR - REASON: ' + event$.reason"/>
      <exit/>
  </transition>

  <transition event="connection.disconnected">
     <!-- send to unconditionally end a runaway session -->
     <send name="'user.kill.unconditional'" target="session.id" delay="'60s'"/>
  </transition>

  <transition event="user.kill.unconditional">
     <log expr="'**** UNCONDITIONAL KILL - EXITING SESSION'"/>
       <exit/>
  </transition>

  <transition event="connection.failed">
    <log expr="'**** CONNECTION FAILED - REASON: ' + event$.reason"/>
      <exit/>
  </transition>

</eventprocessor>
</ccxml>

Feel free to comment with any questions or suggestions.

-Dustin