Sessions History API¶

This API retrieves the conversation sessions created. It returns information such as session metadata, user and bot identifiers, session duration, language, status, and other relevant metrics.

Method	POST
Endpoint	`https://{{host}}/api/public/bot/{{BotID}}/getSessions?containmentType={{containmentType}}` and `https://{{host}}/api/public/getSessions?containmentType={{containmentType}}`for BAC
Content Type	`application/json`
Authorization	`auth: {{JWT}}` See How to generate the JWT Token.
API Scope	Bot Builder: Bot Sessions ORAdmin Console: Bot Analytics > Bot Sessions

Path Parameters¶

PARAMETER	DESCRIPTION
host	Environment URL, for example, https://bots.kore.ai
BotID	Bot ID or Stream ID. You can access it from the General Settings page of the bot.
containmentType (introduced in ver9.0)	Use to filter the results based on the type of the session i.e Self-service vs. Drop-off vs. Agent Transfer \ Valid values: dropOff, selfService, agent.

Sample Request¶

Without a body

curl --location --request POST 'https://{{host}}/api/public/getSessions?containmentType={{containmentType}}' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw

With a body

curl --location --request POST 'https://{{host}}/api/public/getSessions?containmentType={{containmentType}}' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "skip" : 0,                          
        "limit" : 100,                      
        "dateFrom" : "2020-02-11",
        "dateTo" : "2020-02-12"
     }

For a specific bot

curl --location --request POST 'https://{{host}}/api/public/bot/{{BotId}}/getSessions?containmentType={{containmentType}}' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "skip" : 0,                          
        "limit" : 100,                      
        "dateFrom" : "2020-02-11",
        "dateTo" : "2020-02-12"
     }

For specific session Ids

curl --location --request POST 'https://{{host}}/api/public/bot/{{BotId}}/getSessions' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "sessionId": ["6465cf6e4769ed4e822b82a1","6465cf6e47Q9ed4e822b82a1"]
     }

Request Body Parameters¶

PARAMETER	DESCRIPTION	REQUIRED/OPTIONAL
userId	The ID of the user whose conversation history to access. Can be a user email id or enterprise assigned unique id.	Optional
skip/offset	The number of messages to be skipped.	Optional
limit	The number of messages to be shown on each page. The latest sessions are returned first; the sessions are returned in descending order of start time.	Optional
dateFrom	Takes the date format yyyy-mm-dd (or) yyyy-mm-ddThh:mm:ss.msZ eg:2019-04-01 (or) 2019-04-01T13:25:58.515Z. If not provided, calculated as 7 days behind dataTo.	Optional
dateTo	Takes the date format yyyy-mm-dd (or) yyyy-mm-ddThh:mm:ss.msZ eg:2019-04-01 (or) 2019-04-01 T13:26:05.598Z. If not provided, calculated as 7 days from dateFrom. If dateFrom is also not provided then set to Today. The dateTo or dateFrom parameter accepts the YYYY-MM-DD date format. The time format is considered as a GMT zone in the API endpoint via Sessions API. When retrieving the data from the bot builder > dashboard, the local time zone (IST) is used; the time is converted from GMT to IST format, and then the data is retrieved.	Optional
tags	Meta tags to filter the conversations.	Optional
sessionType (introduced in v8.0)	Type to filter the conversations – can be: non-interactive – sessions that have bot messages presented without any message from the user interactive – sessions that include one or more messages from the user	Optional
sessionId (introduced in v10.1.3)	An array of session IDs to filter the conversations. It can have a maximum of 50 session IDs. (Duplicate session IDs are ignored, but they are counted.) Note: If you use ‘sessionId’ in the Body, other parameters/filters are ignored.	Optional

Note

The duration between dateTo and dateFrom should be less than 7 days, else an error will be thrown.

Sample Response¶

For dropOff sessions

{
  "total": 1,
  "moreAvailable": false,
  "sessions": [
   {
     "sessionId": "xxxxaxxexxxaxexdxxxdxxxe",
     "botId": "st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx",
     "channel": "rtm",
     "userId": "u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx",
     "start_time": "2021-04-26T11:27:25.977Z",
     "end_time": "2021-04-26T11:27:26.145Z",
     "session_lang": [
       "en"
      ],
     "sessionType": "interactive",
     "containmentType": "dropOff",
     "isDeveloper": false,
     "tags": {
       "userTags": [
        {
         "value": "newuser",
         "name": "regular"
        }
      ],
      "sessionTags": []
     },
     "noOfMessagesExchanged": 1,
     "noOfTasksExecuted": 0
   }
  ]
]

For selfService sessions

{
  "total": 2,
  "moreAvailable": false,
  "sessions": [
   {
     "sessionId": "xxxxaxxexxxaxexdxxxdxxxe",
     "botId": "st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx",
     "channel": "rtm",
     "userId": "u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx",
     "start_time": "2021-04-26T11:27:25.977Z",
     "end_time": "2021-04-26T11:27:26.145Z",
     "session_lang": [
       "en"
      ],
     "sessionType": "non-interactive",
     "containmentType": "selfService",
     "isDeveloper": false,
     "tags": {
       "userTags": [
        {
         "value": "newuser",
         "name": "regular"
        }
       ],
       "sessionTags": []
     },
     "noOfMessagesExchanged": 6,
     "noOfTasksExecuted": 0
    },
   {
     "sessionId": "xxxxaxxexxxaxexdxxxdxxxe",
     "botId": "st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx",
     "channel": "rtm",
     "userId": "u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx",
     "start_time": "2021-04-26T11:27:25.977Z",
     "end_time": "2021-04-26T11:27:26.145Z",
     "session_lang": [
       "en"
      ],
      "sessionType": "non-interactive",
      "containmentType": "selfService",
      "isDeveloper": false,
     "tags": {
       "userTags": [
         {
          "value": "newuser",
          "name": "regular"
        }
      ],
     "sessionTags": []
     },
     "noOfMessagesExchanged": 8,
     "noOfTasksExecuted": 0
    }
  ]
}

For agent sessions

{
  "total": 1,
  "moreAvailable": false,
  "sessions": [
   {
     "sessionId": "xxxxaxxexxxaxexdxxxdxxxe",
     "botId": "st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx",
     "channel": "rtm",
     "userId": "u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx",
     "start_time": "2021-04-26T11:27:25.977Z",
     "end_time": "2021-04-26T11:27:26.145Z",
     "session_lang": [
       "en"
      ],
     "sessionType": "interactive",
         "containmentType": "agent", 
     "isDeveloper": false,
     "tags": {
        "userTags": [],
        "sessionTags": []
     },
     "noOfMessagesExchanged": 7,
     "noOfTasksExecuted": 2
    }
  ]
}

**For one or more session Ids

{
    "total": 1,
    "moreAvailable": false,
    "sessions": [
        {
            "sessionId": "6465cf6e4769ed4e822b82a1",
            "botId": "st-dc600cf5-b1c5-581e-a2c3-eb81fe39c927",
            "channel": "rtm",
            "userId": "u-8c4ca335-3152-5622-9cbb-51c6daf6c12f",
            "start_time": "2023-05-18T07:10:38.695Z",
            "end_time": "2023-05-18T07:10:39.201Z",
            "session_lang": [
                "en"
            ],
            "sessionType": "interactive",
            "isDeveloper": false,
            "sessionStatus": "closed",
            "tags": {
                "userTags": [],
                "sessionTags": []
            },
            "noOfMessagesExchanged": 3,
            "noOfTasksExecuted": 1,
            "containmentType": "selfService"
        }
    ],
    "invalidSessions": [
        "6465cf6e47Q9ed4e822b82a1"
    ]
}

Response Body Parameters¶

PARAMETER	DESCRIPTION
total	The total number of records identified as per the API request parameters. The response will include a maximum of X records. If more than X records are identified, then the ‘moreAvailable’ field in the response will have the value as ‘True’. It is recommended to programmatically iterate the request by dynamically updating the values of the ‘skip’ and ‘limit’ parameters in the request.
moreAvailable	Indicates if the API has returned all the records or if more are available, based on the pagination criteria. True if more records are available. False if there are no more records to be retrieved.
sessions	Contains complete information about the session.
sessions.sessionId	The unique identifier for the session record.
sessions.botId	Bot ID or Stream ID.
sessions.channel	The channel in which the end user is having the conversation: sms, email, rtm, slack, skype, twitter, msteams, api, kore, facebook, or skypeforbusiness.
sessions.userId	The user Id of the end user who is having a conversation with the bot.
sessions.start_time	The start time of the session. (ISO Date format YYYY-MM-DDThh:mm:ss.mmmZ)
sessions.end_time	The end time of the session. (ISO Date format YYYY-MM-DDThh:mm:ss.mmmZ)
sessions.session_lang	All the languages in which the conversation happened during the session.
sessions.sessionType	The type to filter the conversations: non-interactive – sessions having only bot messages, no message from the user. interactive – sessions having one or more messages from the user.
sessions.containmentType	Used to filter the results based on the type of the session: selfservice, dropOff, or agent.
sessions.isDeveloper	Informs whether the session was initiated by a developer; 1 for Yes, 0 for No.
sessions.sessionStatus	The status of the session – active or closed.
sessions.tags	Meta tags to filter the sessions.
sessions.tags.userTags	User tags object; custom tags added to the user’s profile information.
sessions.tags.userTags.value	Tag’s value.
sessions.tags.userTags.name	Tag’s name.
sessions.tags.sessionTags	Session tags object; custom tags added to the conversation session.
sessions.tags.sessionTags.value	Tag’s value.
sessions.tags.sessionTags.name	Tag’s name.
sessions.noOfMessagesExchanged	The number of messages exchanged in the session.
sessions.noOfTasksExecuted	The number of tasks executed in the session.
invalidSessions	An array listing session IDs that were not found.