Tropo is part of CiscoLearn More

session

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.

The JSON is sent to your server with the UTF-8 character encoding.

Fields

accountId

String

Contains the Tropo account ID that this session belongs to. Helpful if you are using the same web application to serve multiple Tropo applications.

Example: "accountId":"33932",

callId

String

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.

Example: "id":"1aa06515183223ec0894039c2af433f2",

from

Object

This contains the elements that identify the origination of the session. This is a Caller ID Object (detailed later on this page).

headers

Object

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

NoteThe initial SIP URI that kicked off the session will be placed in a special header called Request URI

id

String

This is the GUID representing the unique session identifier.

initialText

String

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.

Example: "initialText":When is my appointment?",

parameters

Object

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

String

The time that the session was started, in ISO 8601 format.

Example: "timestamp":"2010-02-18T19:07:36.375Z",

The initial portion is the date, followed by "T" to indicate "Time" is coming next. The time is 19 hours, 7 minutes, 36 seconds, 375 milliseconds, followed by the timezone "Z" (the timezone code for GMT).

to

Object

This contains the elements that identify the destination of the session. This is a Caller ID Object (detailed later on this page).

userType

String

This identifies the type of user that is on the other end of the session. May be HUMAN, MACHINE, or FAX. If answering machine detection is not used in your application, this will return "HUMAN".

Example: "userType":"HUMAN",

Caller ID Object Fields

The to and from properties in the session object both represent a caller and have a number of fields about that call.

id

String

The identifier of the user that initiated the session, typically the Caller ID

Example: "id":"+14075551212",

e164Id

String

When the id is a telephone number, this field represents the full telephone number, converted to e.164 format, with the country code included.

Example: "e164Id":"14075551212",

name

String

The name of the user that initiated the session. Typically only set on SIP calls, although some carriers set this on PSTN calls.

Example: "name":"Adam Smith",

channel

String

Either "VOICE" or "TEXT"

Example: "channel":"VOICE",

network

String

For voice this may be "PSTN" or "VOIP"; for text this can only be "SMS".

Example: "network":"PSTN"

Examples

Example

{
   "session":{
      "id":"1aa06515183223ec0894039c2af433f2",
      "accountId":"33932",
      "timestamp":"2010-02-18T19:07:36.375Z",
      "userType":"HUMAN",
      "initialText":null,
      "callId":"abcdef743e245c265bc2c699b4112345",
      "to":{
         "id":"2125551212",
         "e164Id": "12125551212",
         "name":"unknown",
         "channel":"VOICE",
         "network":"PSTN"
      },
      "from":{
         "id":"4155559999",
         "e164Id":"14155559999",
         "name":"unknown",
         "channel":"VOICE",
         "network":"PSTN"
      },
      "headers":{
         "Content-Length":"247",
         "To":"<sip:2125551212@10.6.61.101:5060>",
         "Contact":"<sip:4155559999@10.6.63.104:5060>",
         "x-sid":"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",
         "From":"<sip:4155559999@10.6.63.104:5060>;tag=0-13c4-4b7d8ff7-1c3c1b82-5d8c"
      }
   }
}