{"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:

  1. User calls a Tropo WebAPI application.
  2. Tropo sends session JSON to the defined web server, asking for instructions.
  3. Web server application responds telling Tropo to play an audio file to the caller.
  4. 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.

Fields

accountId
Data Type: 
String
Default: (none) Optional

Contains the user account ID that started this session.

callId
Data Type: 
String
Default: (none) 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, typically the Caller ID
  • "name" - The name of the user that initiated the session
  • *channel* - Either "VOICE" or "TEXT"
  • *network* - For voice this may be "PSTN" or "VOIP"; for text this can only be "SMS".
headers
Data Type: 
Object
Default: (none) Optional

This contains the Session Initiation Protocol (SIP) Headers for the current session. This is advanced network information.

id
Data Type: 
String
Default: (none) Optional

This is the GUID representing the unique session identifier.

initialText
Data Type: 
String
Default: (none) Optional

When the channel is of a type "TEXT", this field contains the initial text of the message from the SMS 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: (none) 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=407...

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: (none) 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; this will typically be the Called ID
  • "name" - The name of the user that receiving the session; only applies to SIP
  • *channel* - Either "VOICE" or "TEXT"
  • *network* - For voice this may be 'PSTN" or "VOIP"; for text this can only be "SMS"
userType
Data Type: 
String
Default: (none) Optional

This identifies the type of user that is on the other end of the session; currently, this will always return "HUMAN" as answering machine detection has not yet been implemented in Tropo.

Examples

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"
      }
   }
}