Conversation History API¶
To fetch the conversational messages between the bot and user in reverse chronological order. This API supports pagination. You can provide offset/skip and limit to get a certain number of messages at a time.
| Method | GET and POST |
| Endpoint | This API has two versions for GET and POST methods. The v1 of the API includes messages associated with all tasks, and it has a maximum limit of 100 messages per request. The v2 of the API does not include the messages related to Alert and Action tasks, and it has a maximum limit of 10,000 messages per request.
GET Method Version 1:
Version 2:
Note: The GET method shows the RTM interactions by default. To get the channel-specific interaction, use the channelType parameter in the GET method. For the channelType parameter values, see Request Body Parameters section. POST Method Version 1:
Version 2:
|
| accept-encoding | gzip, deflate, br
This allows the server to compress the response using any of these algorithms (gzip, deflate, or Brotli) before sending it back, which makes the response size smaller and faster to transmit over the network, thereby improving the overall performance of the API communication. Note: We recommend using this header element in v2 of the GET and the POST methods. |
| Content Type | application/json
|
| Authorization | auth: {{JWT}}
|
| API Scope |
|
Path Parameters¶
| PARAMETER | REQUIRED/OPTIONAL | DESCRIPTION |
| host | required | Environment URL, for example, https://bots.kore.ai |
| botId | optional | Bot ID or Stream ID. You can access it from the General Settings page of the bot. |
Sample Request¶
Sample Request for GET Method
Version 1:
curl -X GET \
'https://{{host}}/api/public/bot/{{botId}}/getMessages?userId={{userId}}&limit=10&dateFrom=2023-05-20&dateTo=2023-05-25' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'
Version 2:
curl -X GET --compressed --location \
'https://{{host}}/api/public/bot/{{botId}}/getMessagesV2?userId={{userId}}&limit=10&dateFrom=2023-05-20&dateTo=2023-05-25' \
--header 'accept-encoding: gzip, deflate, br' \
--header 'Content-Type: application/json' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'
Sample Request for POST method
Version 1:
curl -X POST \
'https://{{host}}/api/public/bot/{{botId}}/getMessages' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
"userId" : "u-xxxx-xxxxx-xxxx",
"skip" : 0,
"limit" : 100,
"dateFrom" : "2019-04-01",
"dateTo" : "2019-04-01",
"channelType" : "rcs",
"sessionId" : ["5eadxxxxxxxxxxxxx","5ebxxxxxxxxxxxxxxx"],
"includeTraceId" : "true"
"tags" : {
"and" : [
{
"name" : "tagname",
"values" : ["tagvalue1","tagvalue2"],
"type" : "tagtype"
},
{
"name" : "tagname",
"values" : ["tagvalue1","tagvalue2"],
"type" : "tagtype"
}
]
}
}'
Version 2:
curl -X POST --compressed --location \
'https://{{host}}/api/public/bot/{{botId}}/getMessagesV2' \
--header 'accept-encoding: gzip, deflate, br' \
--header 'Content-Type: application/json' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--data '{
"userId" : "u-xxxx-xxxxx-xxxx",
"skip" : 0,
"limit" : 100,
"dateFrom" : "2019-04-01",
"dateTo" : "2019-04-01",
"channelType" : "rcs",
"sessionId" : ["5eadxxxxxxxxxxxxx","5ebxxxxxxxxxxxxxxx"],
"includeTraceId" : "true"
"tags" : {
"and" : [
{
"name" : "tagname",
"values" : ["tagvalue1","tagvalue2"],
"type" : "tagtype"
},
{
"name" : "tagname",
"values" : ["tagvalue1","tagvalue2"],
"type" : "tagtype"
}
]
}
}'
Request Query Parameters¶
| PARAMETER | REQUIRED/OPTIONAL | DESCRIPTION |
| userId | required for GET
optional for POST |
The ID of the user whose conversation history to access. Can be user email id or enterprise assigned unique id. |
| skip/offset | optional | The number of messages to be skipped. |
| limit | optional | The number of messages to be shown on each page. |
| channelType | optional | Channel type name for which you want to see the interactions; the default is “rtm” .
Accepted channel types are:
|
| dateFrom | optional | Accepts the yyyy-mm-dd date format.
(or) yyyy-mm-ddThh:mm:ss.msZ eg:2019-04-01 (or) 2019-04-01T13:25:58.515ZIf not provided, calculated as 7 days behind dateTo. Note: This field cannot be used in combination with msgId. |
| dateTo | optional | Accepts the yyyy-mm-dd date format.
(or) yyyy-mm-ddThh:mm:ss.msZ eg:2019-04-01 (or) 2019-04-01 T13:26:05.598ZIf not provided, calculated as 7 days from dateFrom. If dateFrom is also not provided then set to Today. Note: This field cannot be used in combination with msgId |
| getAgentsInfo | optional | Accepts true or false. If the value is true then the agent info is fetched and put in the author object of the agent. If the value is false or the field is not provided then agent info is not passed in the response. |
Note
The duration between dateTo and dateFrom should be less than 7 days, else an error will be thrown.
Request Body Parameters¶
| PARAMETER | REQUIRED/OPTIONAL | DESCRIPTION |
| skip/offset | optional | The number of messages to be skipped. |
| limit | optional | The number of messages to be shown on each page. |
| forward | optional | Takes string values - "true" or "false". Specifies the direction of the messages to be retrieved.
|
| msgId | optional | A specific Message-Id if known. This would fetch the records starting from that message either forward or backward depending upon the direction (see below) requested.
In case only the specific conversation is required, set the limit to 1 Note: This field cannot be used in combination with dateFrom and dateTo. |
| includeTraceId | optional | Whether to include the trace ID in the response. A trace ID is a unique ID assigned to each incoming message. Possible values of the parameter:
|
| direction | optional when msgId is given |
|
| sessionId | optional | A specific Session-Id if known. Refer here to obtain the session id |
| tags | optional | Meta tags to filter the conversations. |
| getAgentsInfo | optional | Accepts true or false. If the value is true then the agent info is fetched and put in the author object of the agent. If the value is false or the field is not provided then agent info is not passed in the response. |
Sample Response¶
Sample response for the GET method
{
"total": 1,
"moreAvailable": false,
"icon": "https://dlnwzkim0wron.cloudfront.net/f-87c47629-7exxxxxxxx-a807ccfb1cf0.png",
"messages": [
{
"_id": "ms-fee996b9-0485-55a3-bf42-417c1272aff4",
"channels": [
{
"type": "rtm",
"channelUId": "alan.walker@abc.com"
}
],
"type": "incoming",
"status": "received",
"createdBy": "u-1bc0993f-e0d6-5589-973d-6fe2663de2d4",
"lmodifiedBy": "u-1bc0993f-e0d6-5589-973d-6fe2663de2d4",
"createdOn": "2023-07-18T09:46:46.925Z",
"lmodifiedOn": "2023-07-18T09:46:46.925Z",
"botId": "st-369f9021-2a85-5b32-9005-63139d57c2e5",
"orgId": "o-f4b49c0a-f027-57bf-aef0-b68ad9b51ee2",
"accountId": "6461f97ed43763474b34e56e",
"isBB": 1,
"ms": 1,
"chnl": "rtm",
"isD": 1,
"components": [
{
"_id": "cp-ae11791d-118f-53f1-8905-9bc9f03fdece",
"cT": "text",
"data": {
"text": "hi"
},
"thumbnails": []
}
],
"timestampValue": 1689673606939,
"__v": 0,
"lang": "en",
"sT": 1,
"sessionId": "64b65f87277b464507f778c0",
"cluster_id": "Others",
"resourceid": "messagestore",
"tags": {
"messageTags": [],
"userTags": [
{
"value": "Alan",
"name": "Alan Walker"
}
],
"sessionTags": []
},
"traceId": "5371b61d-b1bb-4432-80de-7430772b0cfb"
},
{
"_id": "ms-5436a303-0d8c-58e8-8ad3-33bf5bcefcb7",
"channels": [
{
"type": "rtm",
"channelUId": "alan.walker@abc.com"
}
],
"type": "outgoing",
"status": "pending",
"createdOn": "2023-07-18T09:46:47.497Z",
"lmodifiedOn": "2023-07-18T09:46:47.497Z",
"createdBy": "u-1bc0993f-e0d6-5589-973d-6fe2663de2d4",
"components": [
{
"_id": "cp-c035b2f4-10f2-5294-b655-c2d6273e0154",
"cT": "text",
"data": {
"text": "Hey :)"
},
"thumbnails": []
}
],
"botId": "st-369f9021-2a85-5b32-9005-63139d57c2e5",
"orgId": "o-f4b49c0a-f027-57bf-aef0-b68ad9b51ee2",
"accountId": "6461f97ed43763474b34e56e",
"isBB": 1,
"ms": 1,
"chnl": "rtm",
"isD": 1,
"lang": "en",
"timestampValue": 1689673607507,
"__v": 0,
"sT": 1,
"sessionId": "64b65f87277b464507f778c0",
"resourceid": "messagestore",
"tags": {
"messageTags": [],
"userTags": [
{
"value": "Alan",
"name": "Alan Walker"
}
],
"sessionTags": []
}
},
Sample Response from POST method:
{
"total": 1,
"moreAvailable": false,
"messages" : [
{
"_id": "ms-xxxxxxxxxxxxxxxxxxxx",
"type": "incoming",
"status": "sent to cs",
"createdBy":"u-xxxxxxxxxxxxxxxxxxx",
"lmodifiedBy": u-xxxxxxxxxxxxxxxxxxx",
"lmodifiedOn": "2019-04-10T10:21:45.103Z",
"channels": [
{
"type": "rcs"
}
],
"botId":"st-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"orgId": "o-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"accountId": "5xxxxxxxxxxxxxxxxxxxxxxxx",
"isBB": 0,
"ms": 1,
"channel": "rcs",
"components": [
{
"_id":"cp-xxxxxxxxxxx",
"cT": "text",
"data": {
"text": "23"
},
"thumbnails": []
}
],
"createdOn": "2019-04-10T10:21:45.106Z",
"timestampValue": 1554891705106,
"__v": 0,
"sessionId": "5cadbefc6a81a71559f6bece"
}
]
}
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. |
| icon | The URL of the bot logo. |
| messages | Contains complete information about the message. |
| messages._id | The unique identifier for the message record. |
| messages.traceId | A unique identifier associated with each incoming message.
Note: The Trace ID is retained in the logs for 30 days. Once the Trace ID is expired, you see a tooltip message as ‘ |
| messages.type | The message type – incoming (user input) or outgoing (bot response). |
| messages.status | Processing status of the message: received, queued, in progress, delivered, or pending. |
| messages.lmodifiedOn | The last modified time for the record. |
| messages.createdBy | The user ID of the end user who was chatting with the bot. |
| messages.channels | The channels object provides additional information about the channel through which the conversation was initiated. |
| messages.channels.type | Name of the channel through which the conversation is initiated. The default is ‘rtm’. |
| messages.channels.channelUId | The end-user’s identity provided by the channel. |
| messages.components | Additional information about the message record. |
| messages.components._id | The unique id of the component. |
| messages.components.cT | Type of the user input (component type): text, audio, video, image, attachment, contact, task, filelink, location, email, alert, action, timeline, meeting, error, upgrade, NLResponse, or contextUpdate. |
| messages.components.data | The data object. |
| messages.components.data.text | The message shown to the user or the bot, depending on the message type. |
| messages.components.thumbnails | The thumbnails object. |
| messages.components.thumbnails._id | The unique id of the thumbnails. |
| messages.components.thumbnails.width | The width of the thumbnails. |
| messages.components.thumbnails.height | The height of the thumbnails. |
| messages.components.thumbnails.size | The size of the thumbnails. |
| messages.components.thumbnails.url | The URL of the thumbnails. |
| messages.botId | Bot ID or Stream ID. |
| messages.orgId | The organization ID to which the bot belongs to. |
| messages.accountId | The account id to which the bot belongs to. |
| messages.isBB | Informs whether the conversation was initiated from the Bot Builder; 1 for Yes, 0 for No. |
| messages.isD | Informs whether the conversation was initiated by a developer; 1 for Yes, 0 for No. |
| messages.lang | The conversation’s language. |
| messages.ms | Message source; enum[0,1,2,3]; 0-task alert, 1-text, 2-task(action), and 3-others. |
| messages.chnl | The end user’s conversation channel. |
| messages.createdOn | The record creation date. |
| messages.timestampValue | The creation date converted into the timestamp format. |
| messages.__v | The field is used for internal purposes. No specific significance. |
| messages.resourceid | The field is used for internal purposes. No specific significance. |
| messages.tags | Meta tags to filter the conversations. |
| messages.tags.messageTags | Message tags object; custom tags added to the message in the conversation. |
| messages.tags.messageTags.value | Tag’s value. |
| messages.tags.messageTags.name | Tag’s name. |
| messages.tags.userTags | User tags object; custom tags added to the user’s profile information. |
| messages.tags.userTags.value | Tag’s value. |
| messages.tags.userTags.name | Tag’s name. |
| messages.tags.sessionTags | Session tags object; custom tags added to the conversation session. |
| messages.tags.sessionTags.value | Tag’s value. |
| messages.tags.sessionTags.name | Tag’s name. |