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.
This is a newer version of the old API which will soon be deprecated. This revised API addresses the limitation of the older version on Botkit enablement or Agent Transfer.
| Method | GET |
| Endpoint |
Note: A POST API call can also be used to include Session-Id and MetaTags in the retrieved Conversation History. |
| Content Type | application/json |
| Authorization |
|
| API Scope |
OR |
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
curl -X GET \
'https://bots.kore.ai/api/public/bot/{{BotId}}/getMessages?userId=u-XXX-XXX&
channelType=facebook&dateFrom=2019-04-01&dateTo=2019-04-05' \
-H 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'
Sample Request for POST call
curl -X POST \
https://bots.kore.ai/api/public/getMessages \
-H 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
-d '{
userId : u-xxxx-xxxxx-xxxx
skip : 0,
limit : 100,
dateFrom : “2019-04-01” (or) “2019-04-01T13:25:58.515Z”,
dateTo : “2019-04-01” (or) “2019-04-01T13:25:58.515Z”,
channelType : “rcs”,
sessionId : [“5eadxxxxxxxxxxxxx”,”5ebxxxxxxxxxxxxxxx”],
tags : {
and : [
{
“name” : ”tagname”,
“values” : [“tagvalue1”,”tagvalue2”],
“type” : “tagtype” // user/message/session
},
{
“name” : ”tagname”,
“values” : [“tagvalue1”,”tagvalue2”],
“type” : “tagtype” // user/message/session
}
]
}
}
Request Body Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| userId |
required for GET call optional for POST call |
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. |
| forward | optional |
Takes boolean values true/false. Specifies the direction of the messages to be retrieved.
|
| dateFrom | optional | Takes the date format yyyy-mm-dd (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 | 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.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 |
| channelType | optional |
Name of the channel of whose conversation history is needed, default is ‘rtm’ . Accepted channel types are:
Note: In case of multi-webhook channel configuration, “ivr” will give the conversations for the first WebHook instance. For those related to other instance, specify the |
| 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. |
| direction | optional when msgId is given |
Default direction is forward. |
| sessionId | optional | A specific Session-Id if known. Refer here to obtain the session id |
| tags | optional | Meta tags to filter the conversations. |
Note: The duration between dateTo and dateFrom should be less than 7 days, else an error will be thrown.
Sample Response
{
"total": 1,
"moreAvailable": false,
"messages": [
{
"_id": "ms-e172XXXXXX9a492cd2",
"type": "outgoing",
"status": "pending",
"lmodifiedOn": "2019-04-01T13:25:58.512Z",
"createdBy": "u-dfb0a15XXXXXXXXX6afa4c74d",
"channels": [
{
"type": "rcs"
}
],
"components": [
{
"_id": "cp-4fbXXXXXXXXXX6ebdd586531",
"cT": "text",
"data": {
"text": "Thanks! I now have access to your Kore Assistant account. Don’t worry, I never access your account without you asking me to do something for you."
},
"thumbnails": []
}
],
"botId": "st-fe7XXXXXX6e115e94c",
"orgId": "o-5a64XXXXXXXXXa58cd43460c3",
"accountId": "5c9c95bXXXXX23c523dbc",
"isBB": 1,
"ms": 1,
"chnl": "rcs",
"createdOn": "2019-04-01T13:25:58.515Z",
"timestampValue": 1554125158515,
"__v": 0,
"resourceid": "messagestore",
"tags": {
"messageTags": [],
"userTags": [
{
"value": "+919346804623",
"name": "RCSID"
}
],
"sessionTags": []
} }
]
}
Sample Response from POST call:
{
"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": "rtm"
}
],
"botId":"st-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"orgId": “o-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"accountId": "5xxxxxxxxxxxxxxxxxxxxxxxx",
"isBB": 0,
"ms": 1,
"channel": "rtm",
"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.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. |