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 |
|
| API Scope |
OR |
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
|
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.
|
Optional |
| tags | Meta tags to filter the conversations. | Optional |
| sessionType (introduced in v8.0) |
Type to filter the conversations – can be:
|
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:
|
| 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. |