Tutorial: Outbound Designer Applications via HTTP

In this tutorial, we will:

Learn how to start Designer sessions on Prophecy with a HTTP request
Write a simple HTML page that triggers the new session
Add custom variables to a designer application by editing configuration files on a premise install

Step 1: Map any Designer project to your token

From our previous tutorials, select any one that you have already posted, if it has a route it has a token, because in Prophecy a route can be used for incoming calls and as tokens for outgoing calls.

Step 2: Manually trigger the application

Now that you have your token, let's manually trigger it to call you. Open up a web browser, and paste in the following URL (be sure to paste your phone number and Token in place of the example ones):



  http://127.0.0.1:9998/SessionControl/VoiceXML.start?

      numbertodial=8001112222&

      tokenid=DesignerRouteName

Replace DesignerRouteName with the route name of your Designer application that you setup in the Management Console.

You may have noticed we're using VoiceXML.start instead of Designer.start. That's because the Designer API generates VoiceXML on the fly, so we can treat it similar to a VoiceXML document when launching it. If you would like to learn about implementing your own CCXML wrapper, we do have a great tutorial here that may interest you.

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.

It may be worth noting here that there are three token API's for outbound applications, they are as follows:

Premise Token API's:

Markup	URL
VoiceXML	http://127.0.0.1:9998/VoiceXML.start?tokenid=[route_id_here]
CCXML	http://127.0.0.1:9999/CCXML10.start?tokenid=[route_id_here]
CallXML	http://127.0.0.1:9999/CALLXML.start?tokenid=[route_id_here]

Hosted Token API's:

Markup	URL
VoiceXML	http://api.voxeo.net/SessionControl/VoiceXML.start?tokenid=[route_id_here]
CCXML	http://api.voxeo.net/SessionControl/CCXML10.start?tokenid=[route_id_here]
CallXML	http://api.voxeo.net/SessionControl/CallXML.start?tokenid=[route_id_here]

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://127.0.0.1:9998/SessionControl/VoiceXML.start"

        method="get" target="_blank">

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

    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 assigned to this application in the Management Console.	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 up to 3 user-defined parameters, and they will be passed along to your Designer application when it is loaded. These are available from within your Designer project as data variables named Parameter 1, Parameter 2 and Parameter 3.



  http://127.0.0.1:9998/SessionControl/VoiceXML.start?

    numbertodial=8001112222&

    tokenid=yourTokenIDhere&

    param1=foo&

   param2=bar&

   param3=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
Your 3 querystring parameters are passed along to your Designer application.

If you are using a premise version of Prophecy you can edit these params in the GlobalVeriables.conf file, thus adding any number of custom values specific to your application. You will find this file at the following location: VOXEO_HOME/designer/config/GlobalVariables.conf. Modifying this file allows you to add custom values, such as myCustomParm, which you can then utilize in your token requests:



  http://127.0.0.1:9998/SessionControl/VoiceXML.start?

    numbertodial=8001112222&

    tokenid=yourTokenIDhere&

    myCustomParm=foo&

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.

What we covered:

Learned how to manually make HTTP requests to start new Designer sessions
Wrote a sample trigger script to make outbound calls
Adding custom variables to your premise install of Prophecy

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Integration - Web Services

| TOC

| Setting Up Telephony