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 be deprecated soon. This revised API addresses the limitation of the older version on Botkit enablement or Agent Transfer.
| Method | GET and POST |
| Endpoint | GET method: https://{{host}}/api/public/bot/{{BotID}}/getMessages?userId={{userID}}&skip=10&limit=10
Note: By default the GET method shows the RTM interactions. If you want to retrieve any channel interaction, you must pass the channelType parameter in the GET method. For example, to retrieve the WebHook channel interactions, enter channelType = IVR in the GET call. For the channelType parameter values, see Request Body Parameters section. |
| Content Type | application/json |
| Authorization | auth: {{JWT}}
|
| 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
Sample Request for GET Method
curl -X GET \
'https://bots.kore.ai/api/public/bot/{{BotId}}/getMessages?userId=u-XXX-XXX&
channelType=ivr&dateFrom=2019-04-01&dateTo=2019-04-05' \
-H 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'
Sample Request for POST method
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"],
"tags" : {
"and" : [
{
"name" : "tagname",
"values" : ["tagvalue1","tagvalue2"],
"type" : "tagtype"
},
{
"name" : "tagname",
"values" : ["tagvalue1","tagvalue2"],
"type" : "tagtype"
}
]
}
}'
Request Query Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| channelType | required | Channel type name for which you want to see the interactions; the default is “rtm” .
Accepted channel types are:
Note: In case of multi-webhook channel configuration, “ivr” gives the conversations for the first WebHook instance. For other WebHoo instance, specify the |
| 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. |
| 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 |
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. |
| 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. |
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-9de62385-c8bd-5053-86c2-7axxxxxxxxxx72",
"channels": [
{
"to": "st-3dfe0cc0-6c34-5b46-bb15xxxxxxxcf",
"type": "ivr",
"channelDispName": "WW"
}
],
"type": "incoming",
"status": "received",
"createdBy": "u-47d826af-3a83-51f7-a049-dexxxxxx",
"lmodifiedBy": "u-47d826af-3a83-51f7-a049-dexxxxxxx",
"createdOn": "2023-03-28T11:06:38.793Z",
"lmodifiedOn": "2023-03-28T11:06:38.793Z",
"botId": "st-3dfe0cc0-6c34-5b46-bb15-bf2dxxxxxxf",
"orgId": "o-312ffdea-4dbc-56e9-abfa-1d2xxxxxxx8",
"accountId": "61f8ea4799bf74163xxxxxxx35",
"isBB": 0,
"ms": 1,
"chnl": "ivr",
"isD": 0,
"components": [
{
"_id": "cp-4b3b4800-5d5a-5179-a9dc-c09dxxxxxxx91",
"cT": "text",
"data": {
"text": "hi"
},
"thumbnails": []
}
],
"timestampValue": 1680001598803,
"__v": 0,
"lang": "en",
"sT": 1,
"sessionId": "6422ca31a7cf935ce74ec355",
"EOD": 3,
"nodeType": 3,
"tr0_I": "smalltalk_9f46b71b:3a74d188fe43591674878c8d958f0299",
"tr_pId": "dg-30c18288-694b-5e27-8744-c27fxxxxxxxe:nd-msg-4944e1d5-26b9-4cda-b219-016e57b7e905:2cxxxxxxx06a98a4b40ce6bf35adfb3b",
"cluster_id": "Others",
"resourceid": "messagestore",
"tags": {
"messageTags": [],
"userTags": [],
"sessionTags": [
{
"value": "rr",
"name": "ss"
}
]
}
}
]
}
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.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. |