Conversation History API

Back to API List Use the Sessions History API to fetch all sessions within a desired time range and then use Conversation History API 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.

Timeline events, including the new system-triggered dialog message, are available only via Get Messages v2 — not via the Conversation History Lightweight API or Get Analytics API.

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 --location --request GET 'https://{{host}}/api/public/bot/{{botId}}/getMessages?userId={{userId}}&channelType=korevg&includeLatency=true' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'userId: u-bdc9c4ba-e7c**********2-5bc04db7796e'

GET v2:

curl --location --request POST 'https://{{host}}/api/public/bot/{{botId}}/getMessagesV2?userId={{userId}}&channelType=korevg&includeLatency=true' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'userId: u-bdc9c4ba-**********99a2-5bc04db7796e' \
--data '{}

POST v1:

curl --location --request POST 'https://{{host}}/api/public/bot/{{botId}}/getMessages' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'userId: u-bdc9c4ba-e7c5**********-5bc04db7796e' \
--data '{
  "userId": "u-bdc9c4ba-e7**********a2-5bc04db7796e",
  "includeLatency": true,
  "dateFrom": "2026-05-22",
  "dateTo": "2026-05-22",
  "sessionId": [
    "6a102**********7f3407b71"
  ],
  "limit": 100,
  "skip": 0
}'

POST v2:

curl --location --request POST 'https://{{host}}/api/public/bot/{{botId}}/getMessagesV2' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'userId: u-bdc9c4ba-**********99a2-5bc04db7796e' \
--data '{
  "userId": "u-bdc9c4b**********3-99a2-5bc04db7796e",
  "includeLatency": true,
  "dateFrom": "2026-05-22",
  "dateTo": "2026-05-22",
  "sessionId": [
    "6a102**********7f3407b71"
  ],
  "limit": 100,
  "skip": 0
}'

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 (GET)

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.
`includeLatency`	Optional	Boolean	When true, each outgoing (bot) message includes a latency object with segment-level timing data. Default: false.
`tags`	Optional	Object	Meta tags to filter conversations.
`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. Can’t be used with `msgId`.
`dateTo`	Optional	Date	End date in `yyyy-mm-dd` or `yyyy-mm-ddThh:mm:ss.msZ` format. Can’t 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.
`includeTimelineEvents`	Optional	Boolean	Includes system-generated timeline events (Agent Joined, User Dropped Off, Session Ended, Agent Transfer, System-triggered dialog) in the response. Default: false. Applies to getMessagesV2 only.
`sessionId`	Optional		A specific session ID.

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

Request Body Parameters (POST)

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. Can’t be used with `dateFrom`/`dateTo`.
`includeTraceId`	Optional	Boolean	`true` to include trace ID in the response.
`includeLatency`	Optional	Boolean	When true, each outgoing (bot) message includes a latency object with segment-level timing data. Default: false.
`direction`	Optional (when msgId given)	Number	`<0` reverse, `=0` bidirectional, `>0` forward.
`sessionId`	Optional	Array	A specific session ID.
`getAgentsInfo`	Optional	Boolean	If `true`, agent info is included.
`includeTimelineEvents`	Optional	Boolean	Includes system-generated timeline events (Agent Joined, User Dropped Off, Session Ended, Agent Transfer, System-triggered dialog) in the response. Default: false.

Sample Response

GET method:

{
  "total": 14,
  "moreAvailable": false,
  "messages": [
    {
      "_id": "ms-a7280************9-8204-6cd26af7xxxx",
      "botId": "st-1d76************0c-8871-f7ea97a0xxxx",
      "type": "incoming",
      "status": "received",
      "createdOn": "2026-03-28T12:18:22.204Z",
      "timestampValue": 1774973902204,
      "sessionId": "68b58************0cexxxx",
      "chnl": "ivrVoice",
      "lang": "en",
      "components": [
        {
          "_id": "cp-001b6069-************6b-c6868f70xxxx",
          "cT": "text",
          "data": {
            "text": "I want to check my order status"
          },
          "thumbnails": []
        }
      ],
      "channels": [
        {
          "type": "ivrVoice"
        }
      ]
    },
    {
      "_id": "ms-171c2f3************bfce-aeaa026cxxxx",
      "botId": "st-1d7611fa-************71-f7ea97a0xxxx",
      "type": "outgoing",
      "status": "pending",
      "createdOn": "2026-03-28T12:18:23.438Z",
      "timestampValue": 1774973903438,
      "sessionId": "68b58e*******53e10cexxxx",
      "chnl": "ivrVoice",
      "lang": "en",
      "components": [
        {
          "_id": "cp-59051b************-a5de-204ad4c7xxxx",
          "cT": "text",
          "data": {
            "text": "Sure! Could you share your order number?"
          },
          "thumbnails": []
        }
      ],
      "channels": [
        {
          "type": "ivrVoice"
        }
      ],
      "latency": {
        "totalMs": 1234,
        "asr": {
          "durationMs": 310,
          "provider": "google",
          "confidenceScore": 0.94
        },
        "bot": {
          "durationMs": 680
        },
        "tts": {
          "durationMs": 244,
          "provider": "azure",
          "utteranceLengthChars": 42,
          "audioLengthMs": 2100,
          "streamingEnabled": true,
          "firstByteMs": 85
        }
      }
    }
  ]
}

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.
`total.Ms`	Number	Total end-to-end latency from user utterance end to bot response playback start (ms).
`duration.Ms`	Number	Total ASR processing time including endpoint detection (ms).
`provider`	String	ASR provider used for this turn such as Google, Azure, Deepgram, and Kore).
`confidence.Score`	Number	ASR confidence score for the recognized utterance (0.0–1.0).
`utterance.Length.Chars`	Number	Character count of the text sent to TTS.
`audio.LengthMs`	Number	Duration of the generated audio clip (ms).
`streaming.Enabled`	Boolean	Whether TTS streaming was used for this turn.
`first.Byte.Ms`	Number	Time to first audio byte from TTS (ms). Relevant when streamingEnabled: true.
`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.

​Path Parameters

​Sample Request

​Request Query Parameters (GET)

​Request Body Parameters (POST)

​Sample Response

​Response Body Parameters

Path Parameters

Sample Request

Request Query Parameters (GET)

Request Body Parameters (POST)

Sample Response

Response Body Parameters