Conversation History API

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.

Field	Value
Method	GET and POST
Endpoint	GET 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-encoding	gzip, deflate, br — Recommended for v2 of both GET and POST methods.
Content Type	application/json
Authorization	auth: {{JWT}} See How to generate the JWT Token.
API Scope	App 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

Parameter	Required	Description
host	Required	Environment URL, for example, https://platform.kore.ai.
botId	Optional	Bot 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

Parameter	Required	Type	Description
userId	Required for GET, optional for POST	String	The ID of the user (email or enterprise unique ID).
skip/offset	Optional	Number	Number of sessions to skip.
limit	Optional	Number	Number of messages per page.
channelType	Optional	String	Channel 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.
dateFrom	Optional	Date	Start date in yyyy-mm-dd or yyyy-mm-ddThh:mm:ss.msZ format. Cannot be used with msgId.
dateTo	Optional	Date	End date in yyyy-mm-dd or yyyy-mm-ddThh:mm:ss.msZ format. Cannot be used with msgId.
getAgentsInfo	Optional	Boolean	If true, agent info is included in the response.
includeSecureForm	Required (v2)	Boolean	Displays form input submitted by the user.
sessionId	Optional		A specific session ID.

The duration between dateTo and dateFrom must be less than 7 days.

Request Body Parameters

Parameter	Required	Type	Description
skip/offset	Optional		Number of sessions to skip.
limit	Optional	Number	Number of messages per page.
forward	Optional	Boolean	true for old-to-recent order, false for most-recent-to-oldest.
msgId	Optional	String	A specific message ID to start retrieving from. Cannot be used with dateFrom/dateTo.
includeTraceId	Optional	Boolean	true to include trace ID in the response.
direction	Optional (when msgId given)	Number	<0 reverse, =0 bidirectional, >0 forward.
sessionId	Optional	Array	A specific session ID.
tags	Optional	Object	Meta tags to filter conversations.
getAgentsInfo	Optional	Boolean	If 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

Parameter	Type	Description
total	Number	Total number of records matching the request parameters.
moreAvailable	Boolean	true if more records are available; false if all records are returned.
icon	URL	The URL of the bot logo.
messages	Array	Complete information about each message.
messages._id	String	Unique identifier for the message record.
messages.traceId	String	Unique identifier associated with each incoming message. Retained for 30 days.
messages.type	String	Message type: incoming (user input) or outgoing (bot response).
messages.status	String	Processing status: received, queued, in progress, delivered, or pending.
messages.createdBy	String	User ID of the end user chatting with the bot.
messages.channels	Array	Channel metadata.
messages.channels.type	String	Channel name; default is rtm.
messages.channels.channelUId	String	End-user identity provided by the channel.
messages.components	Array	Additional information about the message record.
messages.lang	String	Language of the conversation.
messages.chnl	String	End user’s conversation channel.
messages.tags	Object	Meta tags for filtering conversations.