Tropo is part of CiscoLearn More

How It Works

We'll utilize a slightly more complex JSON example to better exemplify the way WebAPI works. This particular example would use three JSON documents - index.json, the_answer.json and the_wrong_answer.json. The first resource, index.json, will instruct Tropo to request a caller's 5 digit account number; the_answer.json is used if the caller inputs a valid response, the_wrong_answer.json would be used if the user inputs an invalid response. A pure JSON application cannot interpret logic, so it can't determine where to go if a user says a particular response - only if it's a valid or not, a yes/no, true/false type of function. You'd need a library for logic (like if/then/else), which we'll go into in more detail in the various Quickstarts.

Step 1 - Session

Any time a user calls or sends a message to your application configured on Tropo, the Tropo WebAPI will POST a JSON document (see '1' in the diagram above) in the body of the HTTP request to the specified resource on your HTTP server. You specify the resource(s) in the “What powers voice calls to your app” and “What powers SMS/messaging calls to your app” fields in the Tropo UI:

The JSON document contains the 'session' object and will look something like this:

Figure 1.0

{"session":{
     "id":"0-13c4-4b79de7f-dcedd0c-4f8f-1d104f50",
     "accountId":"43670",
     "timestamp":"2010-02-15T23:53:35.963Z",
     "userType":"HUMAN",
     "initialText":null,
     "to":{
        "id":"9991429500",
        "name":"unknown",
        "channel":"VOICE",
        "network":"PSTN"
     },
     "from":{
        "id":"username",
        "name":"unknown",
        "channel":"VOICE",
        "network":"PSTN"
     },
     "headers":[
        {
           "key":"x-sbc-from",
           "value":"username<sip:0000123456@192.168.14.100>;tag=a037367f"
        },
        {
           "key":"x-sbc-allow",
           "value":"BYE"
        },
…additional SIP headers…            
}

This initial message contains a wealth of information. It has a unique id, which represents the session and can be used for tracking; your accountId, which is useful if you have a multi-tenant application handling multiple accounts; the to and from blocks, which give you all the network information concerning who they are and what phone number they called into / what username they sent a text or IM to; and a block of headers, which is provided to allow for increased flexibility, since some carriers send custom headers that can help you route the call appropriately. You don’t need to use the SIP headers at all, however; they’re just provided in case you want them. There will typically be significantly more headers than just the two displayed in the example; we trimmed it down for easier viewing.

Step 2 - Response to Tropo

Once you receive the session and determined the next step in your application, respond with an HTTP 200 and include a JSON document in the body that asks the user for input (any other HTTP status will likely result in an error). An example of a possible response document is below; the same ask can be used for voice or text to collect input from the user:

Figure 1.1

{"tropo":[
     {
        "on":[
           {
              "event":"continue",
              "next":"the_answer.json"
           },
           {
              "event":"incomplete",
              "next":"the_wrong_answer.json"
           }
        ]
     },
     {
        "ask":{
           "bargein":true,
           "required":true,
           "timeout":30,
           "say":[
              {"value":"Please enter your account number"}
           ],
           "choices":
               {"value":"[5 DIGITS]"},
           "name":"account_number"
        }}
  ]}

The tropo Object

Every response will begin with the tropo object. This is the root element for a JSON payload sent from your application to the Tropo WebAPI. It can take its elements in an Array or Object.

Events

The reference to on determines the events your application will handle; this determines where the application should look for further instructions, based on the success or failure of a request. In the above example, there are two events defined - continue and incomplete. If a user successfully enters in a five digit account number, the continue event will fire and will look to the_answer.json on your web server for the instructions. If the user fails to enter in a correct amount of digits, or doesn't enter in anything at all, the incomplete event will fire and look to the_wrong_answer.json for the next set of instructions. Not all applications will need events to be defined; if your application isn't collecting any information from the caller, just sending a text message for example, you won't need to define further steps. Check out the API Reference page for on for more information.

Note that you can use PHP, C#, Python, Ruby or any other language to generate the JSON (using one of our libraries or roll your own), so the file extension doesn't have to be .json. As long as you can read and write JSON to and from our servers, you’re good to go.

Step 3 - Tropo Result

Once Tropo has executed your request and asked the user for input, it will return the information as a result JSON document to the resource specified in your on event trigger (lines 3 through 11 of Figure 1.1).

Figure 1.3

{"result":{
     "sessionId":"3FA7C70A1DD211B286B7A583D7B46DDD0xac106207",
     "state":"ANSWERED",
     "sessionDuration":1,
     "sequence":1,
     "complete":true,
     "error":null,
     "actions":{
        "name":"account_number",
        "attempts":1,
        "disposition":"SUCCESS",
        "confidence":100,
        "interpretation":"12345",
        "utterance":"1 2 3 4 5"
     }
  }
}

Step 4 - Reply and Hangup

The app will then move to the next resource, defined by the on event in Step 2 (lines 3 through 11 of Figure 1.1). In this resource, we have a say followed by an explicit hangup. You can also return an HTTP 200 with no body and Tropo will hangup automatically.

Figure 1.4

{"tropo":[
     {
     "say":
         [
           {"value":"Awesome, thanks"}
         ]
     },
     {"hangup":null}
  ]}

Feel like you're good to move on to more specific examples? Move on to the Quickstarts.