VoiceXML 2.1 Development Guide

Home | Frameset Home

Nbest Lesson

| TOC

Mixed Initiative Dialogs

Tutorial: Outbound VoiceXML Applications via HTTP

This tutorial requires that you have a VoiceXML TokenID provisioned to your developer account. As VoiceXML tokens are still technically not open to all community developers (Shhhh...), you may not be a member of the special Illuminati TokenHoldersTM club yet. If not thusly privileged for both, please contact Voxeo Community Support, and specify your account credentials and the flavor of token (CallXML/VoiceXML/CallControlXML), that you'd like provisioned.

In this tutorial, we will:

learn how to start VoiceXML sessions on Voxeo.Net with a HTTP request
write a simple HTML page that triggers the new session

Step 1: map any voicexml application to your tokenid

From our previous tutorials, select any one that you have already posted, and map it to the tokenid in your account. Or, you can use this example:



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

<vxml version = "2.1">



<form id="MyForm">



  <field name="MyField" type="digits?minlength=1;maxlength=2">



  <prompt>

    How old are you?

  </prompt>



  <filled>

      You said <value expr="MyField"/>

  </filled>



  </field>

</form>

</vxml>

Step 2: manually trigger the application

Now that you have your tokenid mapped to a valid application, let's manually trigger it to call you. In your voxeo account manager, copy the tokenid in your account to your computer's clipboard. This tokenid is a long alpha-numeric string of characters (very hard to miss). Here is an example:

3a544c162fc80442b58af315a219336c64ad8675e554...

Now open up a web browser, and paste in the following URL (be sure to paste your phone number and TokenID in place of the example ones):



  http://api.voxeo.net/SessionControl/VoiceXML.start?

      numbertodial=8001112222&

      tokenid=yourTokenIDhere

You can also click on the token mapping itself, in the right hand side of the application manager to launch the token:

Then, you can simply enter the destination number in the pop-up box, and click "execute token":

In theory, your phone should ring and you should hear the application that you mapped on the other end! Alternatively, you may have just "accidentally" called your ex-roommate with this lame application to annoy him. Really, the choice is up to you.

Step 3: creating a HTML page to do the work for you

So, who wants to type all that stuff into a browser every time you need to make an outbound VoiceXML call? Not me, thats for sure. Using HTML forms, we can create a simple script that will do all that hard work for us.



<html>

  <head>

    <title>My first token app</title>

  </head>



  <body>

    <form action="http://api.voxeo.net/SessionControl/VoiceXML.start" 

        method="get" target="_blank">

      <input type="hidden" name="tokenid" value="insertYOURtokenIDhere">

    Phone Number:<input type="text" name="numbertodial"><br>

      <input type="submit" value="submit">

  </form>

  </body>

</html>

Save this little page and load it up in your web browser. You should be able to simply enter the phone number you wish to have called, and click the "submit" button. How cool is it to receive a phone call by clicking a button on a web page? It's like butter!

Step 4: advanced token handling

As Vader said in Empire, "All too easy." Of course, the Sith Lord underestimated his son, so don't you make the same mistake. Our Rebel Forces have engineered a few more "special" parameters that you can pass to the token triggering script. The complete list is as follows:

Variable	Description	Notes
tokenid	The token ID assigned to this application by community support.	Required
numbertodial	The phone number to dial for this session initiation request	Required
callerid	Value to which the callerID will be set for the outbound call. This should be a 10 digit number	Defaults to the BN (billing number) for the telecommunications circuit.
calltimeout	Number of seconds to wait for an outbound call to be answered before the call is considered not answered.	Defaults to 35 seconds. Maximum value is 120.

Also note that you can send any user-defined parameters that you want to http://api.voxeo.net, and they will be passed along to your ColdFusion, (or whatever), document upon execution. So, assuming that our CF script was coded to act on these extra user-defined parameters, the following would be perefctly valid:



  http://api.voxeo.net/SessionControl/VoiceXML.start?

    numbertodial=8001112222&

    tokenid=yourTokenIDhere&

    MyVar1=foo&

   MyVar2=bar&

   MyVar3=gronk

So that magic happens like this...

You make a HTTP request to VoiceXML.start
The token routing script attempts to call the number specified
All the querystring parameters that you sent along with the intial request will be passed through to the application, (assuming that your server side logic catches the querystring parameters).

Here is the list of possible returned values by the VoiceXML.start token router:

Result Value	Description
No answer	The call was not answered
Busy	The line is busy
Call number is bad	The number provided was not a validly formatted number (stop that!)
Invalid token	The token provided was not a valid token.
Internal error	There was an error in the token initiation
Not specified	An error occurred with no specific reason given

So there you have it. You are now empowered to make groovy buttons and integrate the web and the phone in ways your Aunt Beru never thought possible. Impressive. Most impressive.

Download the Code!

Motorola source code

What we covered:

learned how to manually make HTTP requests to start new VoiceXML sessions
wrote a sample trigger script to make outbound calls

ANNOTATIONS: EXISTING POSTS

rapts

6/8/2006 5:38 PM (EDT)

For an outbound call with tokenid, I want to pass some user defined variable to the startURL and want the application to take it and read it during the prompt. For example, I add user defined variable called accountNumber to the start URL, will the snippet given below work:

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

<meta name="maintainer" content="YOUREMAILADDRESS@HERE.com"/>

<form>
<block>
<prompt>
Your account number is <var expr="'<%requestst.getParameter("accountNumber")%>'"/>
</prompt>
</block>

</form>
</vxml>

mikethompson

6/8/2006 7:33 PM (EDT)

Hi Vangipuram,

It seems to me like you want to use some server-side scripting to make your applications more dynamic! This is definitely possible on the Voxeo platform, and we actually have great documentation on how to do this. You can find out all about passing variables into the querystring here: http://docs.voxeo.com/voicexml/2.0/qs_vars.htm

This shows you how to retrieve the parameters from the querystring with php/jsp/asp/coldfusion/etc...

Hope this helps,
Mike Thompson
Voxeo Extreme Support

santy1976

8/17/2006 11:06 AM (EDT)

Hi Guys,

I am a newbie on VXML stuff, but have gone thru the hello world traditional examples stuff on this site. This site really rocks for newbies .I'm in the process of writing usecases for my project and theres an reqt where in I have to initiate the IVR App whenever the user tries to send a SMS(Short Message Service)(i.e The user requests for a transaction).The IVR would actually call back the userand would narratew the transaction summary which he has been called for.How do I initiate the IVR App in case of SMS ??Please do let me know ASAP.

Thanks in Advance....

Cheers
Santy

mikethompson

8/17/2006 4:59 PM (EDT)

Santy,

I am glad to see you are liking our documentation sets! :)

Before I dive into this I just want to be clear, any SMS functionality needs to be taken care of outside of the VoiceXML application context. That is, you need to have your own seperate web application which handles the SMS and callerID information. When your web app receives this information, it needs to fire off an HTTP requested token call (check out token calls here: http://docs.voxeo.com/voicexml/2.0/t_15.htm). You will also need to send along any callerID information as a parameter.

This token will fetch your invoking application, which should then pull the callerID value of the SMS sender from the querystring, and fill the call value from within the application.

Hope this helps explain things...

Best,
Mike Thompson
Voxeo Corporation

cmarko

8/18/2006 4:14 PM (EDT)

When placing an outbound call over HTTP with VoiceXML.start, it is mentioned that the token router returns results on whether "No answer", "Busy", "Invalid token", etc. How are these results actually pulled back from HTTP and fed back to the HTML or exposed to the web application?

Thanks,
Chris

Michael.Book

8/24/2006 12:05 AM (EDT)

Hi Chris,

The result of a token initiation request is returned as the body of the return itself - as form data. How to access the 'errorcode' would, of course, depend on what method and server-side scripting language you used to make the HTTP request.

I hope this helps to get you started. If you would like a specific example for your favorite flavor of server-side scripting, just let us know. We'll gladly pull an example out for you...

Cheers,

~ Michael

mallen

1/10/2007 10:54 AM (EST)

Is there a way to pass to http://session.voxeo.net/VoiceXML.start a Skype ID instead of a phone number? How do I get my app to call someone via Skype?

mikethompson

1/10/2007 1:01 PM (EST)

Hi Mallen,

Sadly, there is no way for us to send outbound calls to Skype IDs. The only use of Skype on our platform is through inbound calls to the Skype numbers in your application manager. We would like to be able to one day include outbound calls to Skype as a feature, but we are waiting on Skype to allow such functionality.

Best,
Mike Thompson
Voxeo Corporation

bruce_zhang

2/6/2007 2:25 AM (EST)

I tried many phone numbers(available US phone number) to outbound my voice applications and I always receive a failure message: "failure: Call number is bad".

Can you tell me the possible reason?

Thanks
Bruce

jbassett

2/6/2007 4:42 AM (EST)

Hello,

Go ahead and give this a try again. I have enabled the correct setting for outbound US calling onto your account.

Let me know if you still have problems.

Thanks
Jesse Bassett
Voxeo Support

fayyazkl

2/21/2007 12:57 AM (EST)

Hi,

when i make an outbound call through tokens via http request, can i play a .wav file to the listener. Actually, i dont require to be able to talk to calle. Instead i only need to play an audio file to him and act according to his responses. Is it possible using voiceXML? or for that matter CCXML etc. Please give some directions.

Thank you.

Fayyaz

jbassett

2/21/2007 3:28 AM (EST)

Hello,

You would probably want to use CCXML for the calling out itself and then transition to a vXML document to handle the playing of audio and handling the user repsonse.

This is probably where you would want to start.
http://docs.voxeo.com/ccxml/1.0/createcall.htm

Let me know if you have any other questions. If you try some of this and run into some problems, feel free to open a support ticket.

Thanks
Jesse Basse

rapts

2/26/2007 10:33 PM (EST)

Hi,

How do I get call duration in a token-initiated outbound call. Is there a shadow variable in this type of call, which contains call duration.

Thanks.

mikethompson

2/27/2007 12:40 PM (EST)

Hi there,

VoiceXML does not have a simple shadow variable available to log the duration of the call, unless you are using <transfer>. This being said, if you'd like to determine how long your VoiceXML outbound call has been, simply use ECMA Script to grab the time as needed. For example:
_______________________________________________________________________________________

<var name="dateUnixEpoch" expr="new Date().getTime()"/>
<log expr="'*** Milliseconds since the Unix Epoch (January 1 1970 00:00:00 GMT) is: [' + dateUnixEpoch + '] ***'"/>

<var name="dateRFC2822" expr="new Date()"/>
<log expr="'*** RFC 2822 formatted date is: [' + dateRFC2822 + '] ***'"/>

<var name="timeVar" expr="new Date().getHours() + ':' + new Date().getMinutes() + ':' + new Date().getSeconds() + ':' + new Date().getMilliseconds()"/>
<log expr="'*** The current time is: [' + timeVar + '] ***'"/>

<var name="MyVar2" expr="new Date().getTimezoneOffset()"/>
<log expr="'*** THE GMT OFFSET IS: ' + MyVar2 + ' ***'"/>

<var name="MyVar3" expr="new Date().getTime() + (new Date().getTimezoneOffset() * 1000)"/>
<log expr="'*** THE TIME WITH GMT OFFSET IS: ' + MyVar3 + ' ***'"/>

________________________________________________________________________________________

This site was helpful in explaining why some browsers (like our VXML browsers) return the year as '106'.

http://www.quirksmode.org/js/introdate.html

Here is my BeginTime code.

<var name="BeginTime" expr="(new Date().getMonth()+1) + '/' + new Date().getDate() + '/' + (new Date().getYear()+1900) + ':' + new Date().getHours() + ':' + new Date().getMinutes() + ':' + new Date().getSeconds() + ':' + new Date().getMilliseconds()"/>

Hope this helps,
Mike Thompson
Voxeo Corporation

tf8252

3/16/2007 8:12 AM (EDT)

My VXML application will initiate calls to an existing IVR (OpenWave Voice Mail platform) via an http request.
The application needs to "listen" for the first few words of the far end speech to verify that the IVR is playing.

Can I use the record element to do this? If so can I cut off the recording after the first few words rather than force the app to "listen" to the entire greeting?

VoxeoBrian

3/17/2007 10:30 AM (EDT)

Hello,

You would be able to utilize the record element to implement what you are trying to do. Here is a snippet from our docs using the record element and limiting the time with the maxtime attribute.

<record name="R_1" maxtime="20s" finalsilence="5s">

I hope this helps to answer your question, if you have any others don't hesitate to ask.

Regards

Brian

adarsh

6/8/2007 5:18 AM (EDT)

Hello there,

we would like to use our community developer account to provide commercial application to our clients like "HTTP initiated phone applications " to thewebsite of our clients:
>open community developer account>get tokenid and outbound previlages for this account>insert this code in webpage>
<form action="http://session.voxeo.net/VoiceXML.start" method="get" target="_blank">
<input type="hidden" name="tokenid" value="insertYOURtokenIDhere"><input type="submit" value="Call Sales Person"></form>
there will be free 500 outdial minutes per month any usage over this limit usually indicates commercial traffic, billable at $0.18 per minute.

we would like to take your permission,what do you say ? how shall we go abt it can you plz guide us.
also
in calling via HTTP what are the call charges and who will have to pay the charges and how ?

adarsh

6/8/2007 6:16 AM (EDT)

Hello there,

we would like to use our community developer account to provide commercial application to our clients like "HTTP initiated phone applications " to thewebsite of our clients:
>open community developer account>get tokenid and outbound previlages for this account>insert this code in webpage>
<form action="http://session.voxeo.net/VoiceXML.start" method="get" target="_blank">
<input type="hidden" name="tokenid" value="insertYOURtokenIDhere"><input type="submit" value="Call Sales Person"></form>
there will be 500 outdial minutes per month any usage over this limit usually indicates commercial traffic, billable at $0.18 per minute.

we would like to take your permission,what do you say ? how shall we go abt it can you plz guide us.
also
in calling via HTTP what are the call charges and who will have to pay the charges and how ?

voxeojeff

6/8/2007 11:01 AM (EDT)

Hi there,

Unfortunately, we limit our developer accounts to 100 minutes per month of outdial access, and we do not allow commercial traffic to be run through our Staging development environment. However, we do have these limitations in our Production environment. If this is something you would be interested in, please feel free to contact sales@voxeo.com and a sales team member will gladly contact you with all the details.

Best regards,

Jeff Menkel
Voxeo Corporation

kumbhamd

9/21/2007 11:10 AM (EDT)

Hello There,

we are trying to test some outbound calls. I see we can use token to initiate the call using http://session.voxeo.net/VoiceXML.start, my questions is there any other way to initiate the call using the prophecy 8.x software locally?

Regards,
dk

mikethompson

9/21/2007 1:56 PM (EDT)

Hello,

If you would like to spawn outbound call in Prophecy, you can do so via similar methodology:

http://127.0.0.1:9998/VoiceXML.start?tokenid=MyRouteID&numbertodial=YourNumber

As you can see, the only change is the host address and the tokenID is associated with the route ID of the application, not a long string such as in hosted.

Hope this helps,
Mike Thompson
Voxeo Corporation

itgrakesh

2/6/2008 3:43 PM (EST)

We are looking for a published web service where we can post VoiceXML to place IVR calls. And there should be some mechanism to get the response and details of the placed calls.

Also I want to know what are Call Start Tokens (Outbound Dialing Tokens) and how to write or use these tokens. The intend is to your system to test our prototype application

mikethompson

2/6/2008 4:04 PM (EST)

Hi Rakesh,

I'd like to answer your last question first, as I think this will help clarify things...

A call start token is a unique string which you tie to an application mapped in your Voxeo Application Manager. It's a means of launching your VoiceXML/CallXML/CCXML applications without having to dial into them first. In order to do this, you simply need to send the token ID to the following servlet:

http://api.voxeo.net/SessionControl/4.5/VoiceXML.start?tokenid=YourTokenIDHere

This will ultimately find the application tied to that token, and begin processing the output. I should mention VoiceXML.start brings up a stock CCXML script under the covers to launch the outbound call. Then, when the call is answered, it launches your VoiceXML application as a dialog. This being said, when using VoiceXML.start, you need to pass in your destination phone number with the numbertodial parameter. So again, we should have something like this:

http://api.voxeo.net/SessionControl/4.5/VoiceXML.start?tokenid=YourTokenIDHere&numbertodial=4075551234

Both CallXML and CCXML are capable of sending out calls by themselves, so when using CallXML.start and CCXML10.start, you'll need to hard code the destination in your actual start document, instead of passing in numbertodial like the VoiceXML servlet.

All this being said, you should not need a web-service to launch these calls. You can code a simple PHP script which uses CURL to send a request to api.voxeo.net and launch the script. On a large scale deployment, you could tie this server-side code into a database and dynamically generate calls to destinations pulled from a database.

Hope this helps,
Mike Thompson
Voxeo Corporation

ragjeff

2/21/2008 10:12 AM (EST)

Hello,

I see that in a previous post you mention how to spawn an outbound call using Prophecy locally, described here:

If you would like to spawn outbound call in Prophecy, you can do so via similar methodology:

http://127.0.0.1:9998/VoiceXML.start?tokenid=MyRouteID&numbertodial=YourNumber

I may be missing something really obvious, but what is the route ID, and where do I find it for an application?

Also, if I eventually use a telephony card to use my own phone lines to run this application, is this how I would initiate an outbound call, or is there another way to initiate using a local phone line?

mikethompson

2/21/2008 5:08 PM (EST)

Hello,

The RouteID is the name you give our route when in the call routing section of the Prophecy Administration Page. You can name it whatever you want.

As for your other question, this would be how you spawn an outbound call over a regular phone line. Of course, Prophecy will need to be fully configured with your hardware in order to do this effectively. For instance, have a dialogic card installed on the server which is used in conjunction with Paraxip (SIP gateway software).

Hope this helps,
Mike Thompson
Voxeo Corporation

mike.j.stein

2/29/2008 4:08 PM (EST)

Hello,

I'm having trouble with a simple "Hello World" test on outbound dialing, with my community developer account.

I've got a token for my account, and I've mapped my .vxml file correctly (when I call the skype number for the account, I hear my hello world test).

But when I try the outbound call, I get the following error:
event: name="error.dialog.notstarted", callid="3fd11e63619c10ae544b4f0786cc60cc", error="no dialog target available", reason="no dialog target available", dialogid="3fd11e63619c10ae544b4f0786cc60cc"

Has anybody else had this problem, and any ideas for a solution?

Thanks,
Mike

VoxeoDustin

2/29/2008 5:05 PM (EST)

Hey Mike,

I took a quick look at your account and does not appear you have a token nor are you setup for outbound dialing. If you're interested in setting this up, please open a support ticket and we can provide you with further details.

Thanks,
Dustin

mikejstein

2/29/2008 5:23 PM (EST)

Hi Dustin,

I realized that there was some confusion because I've actually wound up with two accounts : "mike.j.stein", which I initally posted on, and "mikejstein", which does have a token.

I'm posting under the correct account, where I've been having the trouble with dialing tokens. It's the problem as described in my previous post - getting the no dialogue found error.

Thanks,
Mike

mikethompson

2/29/2008 6:00 PM (EST)

Hello,

There is currently an issue with sending outbound calls via token in Prophecy 8 VoiceXML staging. Specifically, there is a configuration issue in the environment, which needs to be corrected. In speaking with my Platform Operations team, the issue should be fixed during this weekend's maintenance window. As such, come Monday, your applications will successfully launch out of Prophecy 8 VoiceXML in staging.

Best,
Mike Thompson
Voxeo Corporation

eraldo

4/10/2008 9:35 PM (EDT)

Is there a way to pass to http://session.voxeo.net/VoiceXML.start a SIP number instead of a phone number? I mean something like: http://api.voxeo.net/SessionControl/VoiceXML.start?
numbertodial=sip:17473083562!198.65.166.131@sbc-staging-internal&
tokenid=yourTokenIDhere

VoxeoDustin

4/10/2008 11:42 PM (EDT)

Hey,

That will work just fine, though you can probably leave off the country code and simply pass it as [b]sip:4075551212!66.77.88.99@sbc-staging-internal[/b]

Cheers,
Dustin

eraldo

4/11/2008 10:24 AM (EDT)

Thanks a lot

eraldo

4/11/2008 12:20 PM (EDT)

i'm testing an outbound vocicemail application via http, i entered this line in my web browser: http://api.voxeo.net/SessionControl/VoiceXML.start?numbertodial=sip:17473083562!198.65.166.131@sbc-staging-internal&tokenid=hereIputMyTokenID
and then i receive a call in my internet phone(gizmo), but when i
answer it there's no voice, there's nothing, and it was supposed to be a voice saying:Hello World. This is my first telephone application.

my Starturl application is:
<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >

<form>
<block>
<prompt>
Hello World. This is my first telephone application.
</prompt>
</block>
</form>
</vxml>

i don`t know why i don`t hear anything. Maybe i need to add some extra code in my application. PLEASE HELP ME!!!.

voxeojeremyr

4/11/2008 12:37 PM (EDT)

Hi eraldo,

To further investigate as to what is exactly happening in your application, I would like to see the application logs. If you would open a support ticket and attach a copy of the log after you initiate the outbound call, I would be happy to take a look at why this is happening.

If you have any questions, please let me know.

Thanks,
Jeremy

eraldo

4/17/2008 12:24 AM (EDT)

Hi,
I would like to know how can we get the values returned by the VoiceXML.start token router when placing an outbound call over HTTP with VoiceXML.start? because i was trying to find some voxeo docs that maybe could help me but i couldn't get it.And other question, is it possible to send the results of token router, like 'busy', 'no answer',etc..., to a servlet instead of a jsp file?

Thanks...

mikethompson

4/17/2008 3:18 PM (EDT)

Hello,

Would you be so kind as to provide me with an example of what you're looking to do? Are you simply looking to pull the parameter values into your application? If this is the case, you'll need to use server-side scripting in your invoked script to pull the parameters from the querystring. We happen to have some good documentation on this very feature here:

http://docs.voxeo.com/voicexml/2.0/qs_vars.htm

As for your second question, you can grab the result of the token request by grabbing the message body from the HTTP response header. This can be done easily via server-side as well.

Hope this helps,
Mike Thompson
Voxeo Corporation

Nbest Lesson

| TOC

Mixed Initiative Dialogs