Skip to main content
Back to API List To fetch conversational messages between the bot and user in reverse chronological order. Supports pagination via offset/skip and limit parameters.
The Conversation History API provides timestamps in UTC format.
FieldValue
MethodGET and POST
EndpointGET v1: https://{{host}}/api/public/bot/{{botId}}/getMessages?userId={{userId}}&limit=10&dateFrom=2023-05-20&dateTo=2023-05-25
GET v2: https://{{host}}/api/public/bot/{{botId}}/getMessagesV2?userId={{userId}}&includeSecureForm=true
POST v1: https://{{host}}/api/public/bot/{{botId}}/getMessages (or https://{{host}}/api/public/getMessages for Admin Console)
POST v2: https://{{host}}/api/public/bot/{{botId}}/getMessagesV2
accept-encodinggzip, deflate, br — Recommended for v2 of both GET and POST methods.
Content Typeapplication/json
Authorizationauth: {{JWT}} See How to generate the JWT Token.
API ScopeApp Builder: Chat History; Admin Console: Bot Analytics > Chat History
Version differences: v1 includes messages for all tasks with a maximum of 100 messages per request. v2 excludes Alert and Action task messages and supports up to 10,000 messages per request.

​
Path Parameters

ParameterRequiredDescription
hostRequiredEnvironment URL, for example, https://platform.kore.ai.
botIdOptionalBot ID or Stream ID. Access it from the General Settings page of the bot.

​
Sample Request

GET v1: 
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}}'
GET v2: 
curl --location 'https://{{host}}/api/public/bot/{{botId}}/getMessagesV2?userId={{userId}}&includeSecureForm=true' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json'
POST v1: 
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"
  }'
POST v2: 
curl --location 'https://{{host}}/api/public/bot/{{botId}}/getMessagesV2' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "u-dd2d1106-0732-5f93-939c-8e423079xxxx"
}'
Specific call IDs (voice channels): 
curl --location \
 'https://{{host}}/api/public/bot/{{botId}}/getMessages?limit=50&dateTo=2025-06-26&callId={{callId}}&dateFrom=2025-06-23&channelType={{channelType}}' \
--header 'Content-Type: application/json' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'

​
Request Query Parameters

ParameterRequiredTypeDescription
userIdRequired for GET, optional for POSTStringThe ID of the user (email or enterprise unique ID).
skip/offsetOptionalNumberNumber of sessions to skip.
limitOptionalNumberNumber of messages per page.
channelTypeOptionalStringChannel type; default is rtm. Supported: msteams, twitter, spark, rtm, facebook, slack, kore, email, sms, wfacebook, ringcentral, jabber, yammer, alexa, twiliovoice, telegram, ivr, ivrVoice, smartassist, line, liveperson, googleactions, hangoutchat, mattermost, rcs.
dateFromOptionalDateStart date in yyyy-mm-dd or yyyy-mm-ddThh:mm:ss.msZ format. Cannot be used with msgId.
dateToOptionalDateEnd date in yyyy-mm-dd or yyyy-mm-ddThh:mm:ss.msZ format. Cannot be used with msgId.
getAgentsInfoOptionalBooleanIf true, agent info is included in the response.
includeSecureFormRequired (v2)BooleanDisplays form input submitted by the user.
sessionIdOptionalA specific session ID.
The duration between dateTo and dateFrom must be less than 7 days.

​
Request Body Parameters

ParameterRequiredTypeDescription
skip/offsetOptionalNumber of sessions to skip.
limitOptionalNumberNumber of messages per page.
forwardOptionalBooleantrue for old-to-recent order, false for most-recent-to-oldest.
msgIdOptionalStringA specific message ID to start retrieving from. Cannot be used with dateFrom/dateTo.
includeTraceIdOptionalBooleantrue to include trace ID in the response.
directionOptional (when msgId given)Number<0 reverse, =0 bidirectional, >0 forward.
sessionIdOptionalArrayA specific session ID.
tagsOptionalObjectMeta tags to filter conversations.
getAgentsInfoOptionalBooleanIf true, agent info is included.

​
Sample Response

GET method: 
{
    "total": 6,
    "moreAvailable": false,
    "messages": [
        {
            "_id": "ms-171c2f3d-dcdc-50f7-bfce-aeaa026cxxxx",
            "botId": "st-1d7611fa-908a-5f0c-8871-f7ea97a0xxxx",
            "type": "outgoing",
            "status": "pending",
            "components": [
                {
                    "cT": "text",
                    "data": {
                        "text": "Please enter intent"
                    }
                }
            ],
            "createdOn": "2025-09-01T12:17:38.824Z",
            "lang": "en",
            "sessionId": "68b58ee2a0c1153e10cexxxx"
        }
    ]
}

​
Response Body Parameters

ParameterTypeDescription
totalNumberTotal number of records matching the request parameters.
moreAvailableBooleantrue if more records are available; false if all records are returned.
iconURLThe URL of the bot logo.
messagesArrayComplete information about each message.
messages._idStringUnique identifier for the message record.
messages.traceIdStringUnique identifier associated with each incoming message. Retained for 30 days.
messages.typeStringMessage type: incoming (user input) or outgoing (bot response).
messages.statusStringProcessing status: received, queued, in progress, delivered, or pending.
messages.createdByStringUser ID of the end user chatting with the bot.
messages.channelsArrayChannel metadata.
messages.channels.typeStringChannel name; default is rtm.
messages.channels.channelUIdStringEnd-user identity provided by the channel.
messages.componentsArrayAdditional information about the message record.
messages.langStringLanguage of the conversation.
messages.chnlStringEnd user’s conversation channel.
messages.tagsObjectMeta tags for filtering conversations.