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

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




Contains the user account ID that started this session.



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.



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



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



This is the GUID representing the unique session identifier.



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 in the beginning of your session to apply this initialText to an empty ask object that you can then disregard:

        "say":[ { "value":"" } ],
        "choices":{ "value":"[ANY]" },



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:


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,
      "parameters": {
          "token": "token_id",
          "action": "create",



The time that the session was started. As an example:


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.



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"



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.



         "x-sbc-cseq":"1 INVITE",
         "CSeq":"2 INVITE",