Tropo is part of CiscoLearn More

Starting a Session - WebAPI

Starting a session is a bit different when you're using the WebAPI, as WebAPI works on a request/response model. We'll show a simple JSON example to initially highlight the functionality. This simple script just calls a number and provides an appointment reminder:

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

Replace the sample phone number in the JSON with a valid one - 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 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 app is created, you can then create the session using the REST API:

Request

    URL:

    https://api.tropo.com/1.0/sessions

    Method:

    POST or GET

    Headers:

    Only required when using POST:

    accept:application/json
    
    content-type:application/json
    accept:text/xml
    
    content-type:text/xml
    content-type:application/x-www-form-urlencoded

    Request Body:

    POST:

    {
        "token":"TOKEN"
    }
    <session>
        <token>TOKEN</token>
    </session>
    token=TOKEN
    

GET:

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

Response

    Response Body:

    {
        "success": true,
        "token": "TOKEN",
        "id": "ID"
    }
    <session>
        <success>true</success>
        <token>TOKEN</token>
        <id>ID</id>
    </session>
    success=true&token=TOKEN&id=ID
    

Passing Parameters

If you wanted to pass in parameters with the WebAPI, you'll need to use one of the WebAPI Libraries. The following application uses the PHP library and Limonade.

We're passing numberToDial, customerName and msg, just like we did in the Starting a Session tutorial. The names numberToDial, customerName, and msg are not special names in Tropo. Tropo can accept any variable name, and will send these in your session object.

Note
The values for each variable can be strings only, If you use another data type in JSON (an array, for example), it will be wrapped in quotes to turn it into to a string before passing it to your application.

The variables can be passed in JSON, XML or form-encoded format (when using POST) or added directly into a URL (when using GET). The following information explains how to use each method:

Request

    URL:

    https://api.tropo.com/1.0/sessions

    Method:

    POST or GET

    Headers:

    Only required when using POST:

    accept:application/json
    
    content-type:application/json
    accept:text/xml
    
    content-type:text/xml
    content-type:application/x-www-form-urlencoded

    Request Body:

    POST:

    {
        "token":"TOKEN",
        "customerName":"John Dyer",
        "numberToDial":"4075551212",
        "msg":"the sky is falling."
    }
    <session>
        <token>TOKEN</token>
        <var name="customerName" value="John Dyer" />
        <var name="numberToDial" value="4075551212" />
        <var name="msg" value="the sky is falling" />
    </session>
    token=TOKEN&customerName=John+Dyer&numberToDial=4075551212&msg=the+sky+is+falling
    

GET:

https://api.tropo.com/1.0/sessions?action=create&token=TOKEN&numberToDial=4075551212&customerName=John+Dyer&msg=the+sky+is+falling

Response

    Response Body:

    {
        "success": true,
        "token": "TOKEN",
        "id": "ID"
    }
    <session>
        <success>true</success>
        <token>TOKEN</token>
        <id>ID</id>
    </session>
    success=true&token=TOKEN&id=ID
    

Session Object

With WebAPI, however, these variables get passed into the parameters array of the session object - here's an example:

    {"session": {
            "id": "76b05a0b25127dbf59a4627f6dcd38a7",
            "accountId": "12345",
            "timestamp": "2010-05-05T01:59:19.402Z",
            "userType": "NONE",
            "initialText": null,
            "callId":"092f931c4dddf0124ef426c56d26f98c",
            "parameters": {
                "token": "TOKEN",
                "action": "create",
                "numberToDial": "4075551212",
                "customerName": "John Dyer"
                "msg": "the sky is falling"
            }}
        }

You can use any query string variables you want, they'll all be passed into that parameters array. The following code shows how to extract the JSON out of the application:

    <?php
     
    // Include the Tropo PHP WebAPI Library and Limonade framework
    require 'tropo.class.php';
     
    // Pull in the session information and specific parameters you want to use
    $session = new Session();
    $numberToDial = $session->getParameters("numberToDial");
    $customerName = $session->getParameters("customerName");
    $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->call("+1".$numberToDial, array('network'=>'SMS')); 
    $tropo->say("OMG ".$customerName.", ".$msg."!");
    
    // Render the JSON for the Tropo WebAPI to consume.
    return $tropo->RenderJson();
     
    ?>