> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Conversation History API
[Back to API List](/ai-for-service/apis/automation/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](/ai-for-service/apis/automation/api-introduction/#generating-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:**
```bash theme={null}
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:**
```bash theme={null}
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:**
```bash theme={null}
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:**
```bash theme={null}
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):**
```bash theme={null}
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. |
| `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. |
## Sample Response
**GET method:**
```json expandable=true theme={null}
{
"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. |