Tropo WebAPI Development Guide

{"session":} object

Session is the payload sent as an HTTP POST to your web application when a new session arrives. It includes all the data regarding how the application was launched, including parameters passed to the app (if any), channel that was used (voice or text), the datetime, etc.

For example:

User calls a Tropo WebAPI application.
Tropo sends session JSON to the defined web server, asking for instructions.
Web server application responds telling Tropo to play an audio file to the caller.
Tropo plays the audio file and disconnects the call, relaying result JSON back to the web server with final details.

Note that any encoded data, like accented characters, will be passed to your app as ISO-8859-1 encoded in the JSON.

usage

{ "session": {
    "accountId": String,
    "callId": String,
    "from": Object,
    "headers": Object,
    "id": String,
    "initialText": String,
    "parameters": Object,
    "timestamp": String,
    "to": Object,
    "userType": String } }

fields

accountId	Data Type: String	Default: "" (undefined)	Optional
	Contains the user account ID that started this session.
callId	Data Type: String	Default: "" (undefined)	Optional
	This contains the ID of the call itself; this is not the caller ID or called ID, this is a value that identifies the actual call.
from	Data Type: Object	Default: (none)	Optional
	This contains the elements that identify the origination of the session. There are four keys present in from: "id" - The identifier of the user that initiated the session. In the case of a "VOICE" channel this will be their Caller ID, in the case of a "TEXT" session their username "name" - The name of the user that initiated the session channel - For voice this may be 'PSTN" or "VOIP" network - For text this may be "AIM", "GTALK", "JABBER", "MSN", "SMS", "YAHOO" or "TWITTER". Note that in order to send to one of these networks, you need to have the network mapped in your app. For example, if you try to send to AIM when you don't have an AIM username included in your app, your app would fail. Example: `"from":{"id":"john@gmail.com","name":"unknown", "channel":"TEXT", "network":"GTALK"}`
headers	Data Type: Object	Default: "" (undefined)	Optional
	This contains the Session Initiation Protocol (SIP) Headers for the current session. This is advanced network information.
id	Data Type: String	Default: "" (undefined)	Optional
	This is the GUID representing the unique session identifier.
initialText	Data Type: String	Default: "" (undefined)	Optional
	When the channel is of a type "TEXT", this field contains the initial text of the message from the SMS or instant message that the user sent when initiating the session. Note that the initialText field will be saved and used for the first ask object. To have your text application disregard this field, you can use the following code to store the initialText (and remove it from the queue): `{"tropo":[{"ask":{"say":[{"value":""}],"choices":{"value":"[ANY]"},"name":"initial_text_capture"}}]}`
parameters	Data Type: Object	Default: "" (undefined)	Optional
	If you utilize a token launch via the Session API to start your application, parameters will include: `token:token_id` `action:create` Where `token_id` is your actual 88 character Token. Parameters can also include additional variables passed when you use a URL to launch the Session API. In this URL... http://api.tropo.com/1.0/sessions?action=create&token=token_id&myNum=4075551212 ...myNum would be passed to `parameters`. Here's an example of the session JSON generated by that URL: {"session": { "id": "76b05a0b25127dbf59a4627f6dcd38a7", "accountId": "12345", "timestamp": "2010-05-05T01:59:19.402Z", "userType": "NONE", "initialText": null, "callId":"092f931c4dddf0124ef426c56d26f98c", "parameters": { "token": "token_id", "action": "create", "myNum":"4075551212" } } }
timestamp	Data Type: String	Default: "" (undefined)	Optional
	The time that the session was started. As an example: 2012-02-21T16:09:33.891Z The initial portion is the date, followed by "T" to indicate "Time" is coming next. The time is 16 hours, 9 minutes, 33 seconds, 891 milliseconds, followed by "Z" which stands for "Zulu" and really means GMT.
to	Data Type: Object	Default: (none)	Optional
	This contains the elements that identify the destination of the session. There are four keys present within this object: "id" - The identifier of the user receiving the session. In the case of a "VOICE" channel this will be the Called ID, in the case of a "TEXT" session their username "name" - The name of the user that receiving the session; only applies to SIP channel - For voice this may be 'PSTN" or "VOIP" network - For text this may be "AIM", "GTALK", "JABBER", "MSN", "SMS", "YAHOO" or "TWITTER". Note that in order to send to one of these networks, you need to have the network mapped in your app. For example, if you try to send to AIM when you don't have an AIM username included in your app, your app would fail. Example: `"to":{"id":"jane@gmail.com","name":"unknown", "channel":"TEXT", "network":"GTALK"}`
userType	Data Type: String	Default: "" (undefined)	Optional
	This identifies the type of user that is on the other end of the session; it can be set to 'HUMAN', 'MACHINE' or 'FAX'.

code samples

Example

{
   "session":{
      "id":"1aa06515183223ec0894039c2af433f2",
      "accountId":"33932",
      "timestamp":"2010-02-18T19:07:36.375Z",
      "userType":"HUMAN",
      "initialText":null,
      "callId":"abcdef743e245c265bc2c699b4112345"
      "to":{
         "id":"9991427645",
         "name":"unknown",
         "channel":"VOICE",
         "network":"PSTN"
      },
      "from":{
         "id":"jsgoecke",
         "name":"unknown",
         "channel":"VOICE",
         "network":"PSTN"
      },
      "headers":{
         "x-sbc-from":"\"jsgoecke\"<sip:0000123456@192.168.34.202>;tag=2a648c6e",
         "x-sbc-allow":"BYE",
         "x-sbc-user-agent":"sipgw-1.0",
         "x-voxeo-sbc-name":"10.6.63.104",
         "x-sbc-contact":"<sip:0000123456@192.168.34.202:16000>",
         "Content-Length":"247",
         "To":"<sip:9991427645@10.6.61.101:5060>",
         "x-voxeo-sbc":"true",
         "Contact":"<sip:jsgoecke@10.6.63.104:5060>",
         "x-voxeo-to":"<sip:990009369991427645@66.193.54.18:5060>",
         "x-sbc-request-uri":"sip:990009369991427645@66.193.54.18:5060",
         "x-sbc-call-id":"OWE0OGFkMTE1ZGY4NTI1MmUzMjc1M2Y3Y2ExMzc2YjE.",
         "x-sid":"39f4688b8896f024f3a3aebd0cfb40b2",
         "x-sbc-cseq":"1 INVITE",
         "x-sbc-max-forwards":"70",
         "x-voxeo-sbc-session-id":"39f4688b8896f024f3a3aebd0cfb40b2",
         "CSeq":"2 INVITE",
         "Via":"SIP/2.0/UDP 66.193.54.18:5060;received=10.6.63.104",
         "x-sbc-record-route":"<sip:195.46.253.237:5061;r2=on;lr;ftag=2a648c6e>",
         "Call-ID":"0-13c4-4b7d8ff7-1c3c1b82-7935-1d10b080",
         "Content-Type":"application/sdp",
         "x-sbc-to":"<sip:990009369991427645@66.193.54.18:5060>",
         "From":"<sip:jsgoecke@10.6.63.104:5060>;tag=0-13c4-4b7d8ff7-1c3c1b82-5d8c"
      }
   }
}

additional links

none

ANNOTATIONS: EXISTING POSTS

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