Tropo WebAPI Development Guide Home  |  Frameset Home
  Behind the Scenes JSON - Quick Start Example  |  TOC  |  Ruby - Volunteer Opportunities Example  

Sessions and Tokens


Typically, a session is triggered by an incoming phone call, IM or SMS. These sessions are referred to as “inbound sessions” because they were initiated by an incoming communication. Inbound sessions are special in that they begin their life with an active call. Once an inbound session is running, the script is free to make additional calls, send text messages, etc. All that makes it unique is that it started off from an incoming end user communication.

Tropo Session API


There are times, however, when you’ll need to fire off a session based on some external event; when a user clicks on a link on a web site or as part of some larger workflow, for example. That’s where the Tropo Session API comes into play.

The Tropo Session API is a RESTful Web Service used to kick off an “outbound session”. Outbound sessions are a blank slate. Your script can place a call, send an SMS or even call routines available on the Internet – like scheduling a TiVo recording!

It all starts with an application token. A token is a long alphanumeric string that identifies your Tropo application. In other words, it’s used to tell the Tropo Session API where to find the application to run. Getting a token assigned to your app is super easy. Just log in to your Tropo account, display the application configuration screen, and click on the link labeled Add a new token.



If you don’t see a link with that label, chances are you already have one. Once you have a token, keep it to yourself as it allows you to run scripts under your account.

We'll show a simple JSON example to highlight the functionality. This simple script just calls a number and provides an appointment reminder:

{"tropo":[
     {
        "call":{
           "to":[
              "tel:+14075551212"
           ]
        }
     },
     {
        "say":[
           {
              "value":"Remember, you have a meeting at 2 PM",
              "voice":"kate"
           }
        ]
     }
  ]
}


Replace the sample phone number in the JSON with a valid one (line 5 of Figure 3.0; make sure it has the complete country code along with it, which is 1 for the US), then save that script as a .json file on your web server (or on your local hard drive, if you're using Tunnlr or a similar tool) and log into Tropo and create a new WebAPI application. Add your web server URL with the name of the .json file at the end, such as http://example.com/index.json, and click Create Application.

Once the application is available, click on the Add a new token link next to Voice (as shown in the previous screenshot). Once the token has been created, replace the word TOKEN in this URL with the token provided to you:

http://api.tropo.com/1.0/sessions?action=create&token=TOKEN

Then run that URL from the browser of your choice; your browser should return some XML indicating success and the app should call the phone number you provided.

Another element of the Session API is the ability to insert additional variables into your initial session JSON. This URL contains two additional variables - numberToDial and msg:

http://api.tropo.com/1.0/sessions?action=create&token=TOKEN&numberToDial=14075551212&msg=This+is+a+message

These variables get passed into the parameters array of the session object:

{"session": {
        "id": "76b05a0b25127dbf59a4627f6dcd38a7",
        "accountId": "12345",
        "timestamp": "2010-05-05T01:59:19.402Z",
        "userType": "NONE",
        "initialText": null,
        "callId":"092f931c4dddf0124ef426c56d26f98c",
        "parameters": {
            "token": "TOKEN",
            "action": "create",
            "numberToDial": "14075551212",
            "msg": "This is a message"
        }
    }
}

You can use any query string variables you want, they'll all be passed into that parameters array.

You can then extract those parameters via one of the WebAPI Libraries for use in a script, such as an outbound text message. Here's an example using the PHP library and Limonade that sends the contents of 'msg' to 'number' as a text message:

<?php

// Turn off error reporting to prevent markup like 
Warning: Trying to do this with that
 from being sent with the JSON
error_reporting(0);

// Include the Tropo PHP WebAPI Library and Limonade framework
require 'tropo-webapi-php/tropo.class.php';
require 'lib/limonade.php';

// Naming the resource so you can reference it in the URL you define in your application setup
// like this: http://www.example.com/test_app?uri=start
dispatch_post('/start', 'app_start');
function app_start() {
    
    // Pull in the session information and specific parameters you want to use
    $session = new Session();
    $numberToDial = $session->getParameters("numberToDial");
    $msg = $session->getParameters("msg");
    
    // Create new instance of the Tropo object
    $tropo = new Tropo();
    
    // Send the message using the value assigned to msg and numberToDial in the session API URL
    $tropo->message($msg, array('network' => 'SMS', 'to' => $numberToDial));
    
    // Render the JSON for the Tropo WebAPI to consume.
    return $tropo->RenderJson();   
}

// Run the app!
run();  

?>

Each of the next chapters will explain how to use one of the WebAPI Libraries along with a framework; for more info on the PHP Library and Limonade in specific, go to the PHP - Favorite Movie Trilogy example.

A true RESTafarian? (You know who you are!)


Don’t worry, the Tropo Session API supports HTTP POST for full buzzword compliance.

For now, you will need to include <var name="action" value="create"/> even though you're using a POST. This will change in the near future.



Next Step: Ruby - Volunteer Opportunities Example



  ANNOTATIONS: EXISTING POSTS
0 posts - click the button below to add a note to this page

 login
  Behind the Scenes JSON - Quick Start Example  |  TOC  |  Ruby - Volunteer Opportunities Example  
© 2011 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site