Skip to content

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://platform.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, that is, 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"]
     }

For specific call Ids

curl --location POST 'https://{{host}}/api/public/bot/{{BotId}}/getSessions?callId={{callId}}' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
    "skip": 0,
    "limit": 100,
    "dateFrom": "2025-03-17",
    "dateTo": "2025-03-19"
}'

Request Body Parameters


(introduced in v8.0)
(introduced in v10.1.3)
PARAMETER REQUIRED/OPTIONAL TYPE DESCRIPTION
userId Optional String The ID of the user whose conversation history to access. Can be a user email id or enterprise assigned unique id.
skip/offset Optional Number The number of messages to be skipped.
limit Optional Number 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.
dateFrom Optional Date Takes the date format yyyy-mm-dd
(or) yyyy-mm-ddThh:mm:ss.msZ
For example, 2019-04-01 (or) 2019-04-01T13:25:58.515Z. If not provided, calculated as 7 days behind dataTo.
dateTo Optional Date Takes the date format yyyy-mm-dd
(or) yyyy-mm-ddThh:mm:ss.msZ
For example, 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.
tags Optional Object Meta tags to filter the conversations.
sessionType Optional String 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
sessionId Optional 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.

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

For specific Call Ids

{
    "total": 1,
    "moreAvailable": false,
    "sessions": [
        {
            "sessionId": "67d97c8fd495b147d9c3xxxx",
            "botId": "st-89cf14ef-145e-5263-994e-5d757325xxxx",
            "channel": "korevg",
            "userId": "u-c3c0b243-becc-5cce-a845-f681a62dxxxx",
            "start_time": "2025-03-18T14:00:47.505Z",
            "end_time": "2025-03-18T14:01:37.518Z",
            "session_lang": [
                "en"
            ],
            "sessionType": "interactive",
            "isDeveloper": false,
            "sessionStatus": "closed",
            "tags": {
                "userTags": [],
                "sessionTags": [
                    {
                        "value": "1",
                        "name": "welcomeMessageTwilio"
                    },
                    {
                        "value": "+1123456789",
                        "name": "callerNumber"
                    },
                    {
                        "value": "1",
                        "name": "voiceAgentTransferStart"
                    },
                    {
                        "value": "1",
                        "name": "audioCodesCallDisconnect"
                    }
                ],
                "altText": []
            },
            "noOfMessagesExchanged": 4,
            "noOfTasksExecuted": 1,
            "containmentType": "agent"
        },
    ]
}

Response Body Parameters

PARAMETER TYPE DESCRIPTION
total Number 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 Boolean 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 Object Contains complete information about the session.
sessions.sessionId String The unique identifier for the session record.
sessions.botId String Bot ID or Stream ID.
sessions.channel String 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 String The user Id of the end user who is having a conversation with the bot.
sessions.start_time Date The start time of the session. (ISO Date format YYYY-MM-DDThh:mm:ss.mmmZ)
sessions.end_time Date The end time of the session. (ISO Date format YYYY-MM-DDThh:mm:ss.mmmZ)
sessions.session_lang Array All the languages in which the conversation happened during the session.
sessions.sessionType String 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 String Used to filter the results based on the type of the session: selfservice, dropOff, or agent.
sessions.isDeveloper Boolean Informs whether the session was initiated by a developer; 1 for Yes, 0 for No.
sessions.sessionStatus String The status of the session – active or closed.
sessions.tags Object Meta tags to filter the sessions.
sessions.tags.userTags Array User tags object; custom tags added to the user’s profile information.
sessions.tags.userTags.value Dynamic Field (Mixed Type) Tag’s value.
sessions.tags.userTags.name String Tag’s name.
sessions.tags.sessionTags Array Session tags object; custom tags added to the conversation session.
sessions.tags.sessionTags.value Dynamic Field (Mixed Type) Tag’s value.
sessions.tags.sessionTags.name String Tag’s name.
sessions.noOfMessagesExchanged Number The number of messages exchanged in the session.
sessions.noOfTasksExecuted Number The number of tasks executed in the session.
invalidSessions Array An array listing session IDs that were not found.