> ## 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 - Lightweight
[Back to API List](/ai-for-service/apis/automation/api-list)
A lightweight endpoint that returns chat transcripts without additional metadata or payload overhead. Supports high-volume retrieval and minimizes response size to reduce processing time and avoid rate limit issues.
| Field | Value |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Method** | GET and POST |
| **Endpoint** | **GET**: `https://{{host}}/api/public/bot/{{botId}}/messages-lite?userId={{userId}}&limit=5&skip=0&offset=0`
Or
`https://{{host}}/api/public/bot/{{botId}}/messages-lite?channelUId={{channelUId}}&channelType=whatsapp&limit=5`
**Note**: Either `userId` or `channelUId`is required.
**POST**: `https://{{host}}/api/public/bot/{{botId}}/messages-lite` |
| **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 |
## Path Parameters
| Parameter | Required | Description |
| --------- | -------- | ------------------------------------------------------------------ |
| `host` | Required | Environment URL, for example, `https://platform.kore.ai`. |
| `botId` | Required | Bot ID or Stream ID. Access it on the bot's General Settings page. |
## Sample Request
**GET Method:**
**Query by `userId`**
```bash theme={null}
curl --location --request GET 'https://{{host}}/api/public/bot/{{botId}}/messages-lite?userId={{UserId}}&channelType=korevg&includeLatency=true' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'userId: u-8*****1a-3d65-**********3cb0fdb465e4'
```
**Query by `channelUId` (single value)**
```bash theme={null}
curl --location --request GET \
'https://{{host}}/api/public/bot/{{botId}}/messages-lite?channelUId=%2B91987***3210&channelType=whatsapp&limit=5' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json'
```
**POST method:**
**Query by `userId`**
```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/messages-lite' \
--header 'accept: application/json' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
"userId": "u-xxxx-xxxxx-xxxx",
"sessionId": "5eadxxxxxxxxxxxxx",
"dateFrom": "2019-04-01",
"dateTo": "2019-04-30",
"channelType": "rtm",
"type": ["incoming", "outgoing"],
"limit": 100,
"skip": 0,
"isDeveloper": false,
"includeLatency": true
}
```
**Query by `channelUId` (single value)**
```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/messages-lite' \
--header 'accept: application/json' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
"channelUId": "john.doe@example.com",
"channelType": "email",
"dateFrom": "2026-05-01",
"dateTo": "2026-05-31",
"limit": 50
}
```
**Query by `channelUId` Array**
```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/messages-lite' \
--header 'accept: application/json' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
"channelUId": [
"+919876543210",
"john.doe@example.com"
],
"dateFrom": "2026-05-01",
"dateTo": "2026-05-31",
"limit": 100
}
```
## Request Query Parameters (GET)
| Parameter | Required | Type | Description |
| ---------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userId` | Optional | String | User identifier. Required unless `channelUId` is provided. If both are supplied, `userId` takes precedence. |
| `channelUId` | Optional | String or Array | Channel-side identifier such as `phone number`, `email address`, `RTM handle`, `PSID`. Pass the raw identifier; the platform constructs the internal format. Multi-value syntax: `channelUId=a&channelUId=b` |
| `channelType` | Optional | String | Required if `channelUId` is provided. Channel type, for example `whatsapp`, `email`, `rtm`. Source channel, for example: `rtm`, `whatsapp`, `email`, `web-sdk`. Recommended when supplying channelUId for a single-channel lookup. Omit when passing a multi-value `channelUId` array to retrieve history across all channels. |
| `sessionId` | Optional | String | Unique session identifier. |
| `dateFrom` | Optional | String | Start date for filtering messages. Format: `YYYY-MM-DD`. |
| `dateTo` | Optional | String | End date for filtering messages. Format: `YYYY-MM-DD`. |
| `isDeveloper` | Optional | Boolean | Indicates if the query runs in developer mode. Default: false. |
| `includeCount` | Optional | Boolean | When true, the response includes a total count of matching messages. Default: false. |
| `limit` | Optional | Integer | The maximum number of messages returned per request is 1000, with a default of 5 messages if no limit is specified. |
| `skip` | Optional | Integer | Number of records to skip before retrieving results. |
| `includeLatency` | Optional | Boolean | When true, each outgoing (bot) message includes a latency object with segment-level timing data. Default: false. |
| `offset` | Optional | Integer | Pagination offset value. |
## Request Body Parameters (POST)
| Parameter | Required | Type | Description |
| ---------------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId` | Optional | String | User identifier. Required unless `channelUId` is provided. If both are supplied, `userId` takes precedence. |
| `channelUId` | Optional | String or Array | Channel-side identifier such as `phone number`, `email address`, `RTM handle`, `PSID`. Pass the raw identifier; the platform constructs the internal format. Multi-value syntax: `channelUId=a&channelUId=b` |
| `channelType` | Optional | String | Source channels such as `rtm`, `whatsapp`, `email`. Recommended for single-channel lookups using `channelUId`. Omit when passing a multi-value `channelUId` array to retrieve history across all channels. Omitting `channelType` enables retrieval across all matching channels. |
| `sessionId` | Optional | String | Unique session identifier. |
| `dateFrom` | Optional | String | Start date for filtering messages. Format: `YYYY-MM-DD`. |
| `dateTo` | Optional | String | End date for filtering messages. Format: `YYYY-MM-DD`. |
| `includeLatency` | Optional | Boolean | When true, each outgoing (bot) message includes a latency object with segment-level timing data. Default: false. |
| `type` | Optional | Array | Message direction: `incoming` or `outgoing`. |
| `limit` | Optional | Integer | Maximum number of messages to return. |
| `offset` | Optional | Integer | Pagination offset value. |
| `skip` | Optional | Integer | Number of records to skip. |
| `isDeveloper` | Optional | Boolean | Indicates if the query runs in developer mode. |
| `includeCount` | Optional | Boolean | When true, the response includes a total count of matching messages. Default: false. |
## Sample Response
```json theme={null}
{
"total": 8,
"moreAvailable": false,
"messages": [
{
"_id": "ms-c715b************3-9c43-bd89ec8dd4f0",
"botId": "st-76371e************-b55c-e3a05e7ecb98",
"orgId": "o-c659105************8b9a-1cc58bc89d46",
"accountId": "699ed************659486f",
"type": "outgoing",
"status": "pending",
"createdBy": "u-84b1581***************d-3cb0fdb465e4",
"createdOn": "2026-05-26T07:08:15.911Z",
"timestampValue": 1779779295911,
"sessionId": "6a1546**********61a9b0b8",
"lang": "en",
"chnl": "korevg",
"components": [
{
"_id": "cp-b06473f2************998-54ef3cf4ba1b",
"cT": "text",
"data": {
"text": "Then came the smell. A burnt, smoky scent wafted through the air. I yanked open the door to stop the madness and was immediately hit with the sight of my lasagna looking like it had been through a volcanic eruption. Cheese had exploded everywhere — on the sides, the ceiling, and somehow, defying physics, on the outside of the microwave."
},
"thumbnails": []
}
],
"channels": [
{
"from": "+13203445682",
"to": "cs-9f1ad716-6f5f-561c-********************77706d-e9bd-4015-a08e-8d1c0d795d8b",
"channelUId": "cs-9f1ad716-6f5f-56********************2/fa776d-e9bd-4015-a08e-8d1c0d795d8b"
}
],
"latency": {
"totalMs": 2848,
"asr": {
"durationMs": 2502
},
"bot": {
"durationMs": 346
},
"tts": {
"durationMs": 0
}
}
}
]
}
```
## Response Body Parameters
| Parameter | Type | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `total` | Integer | Total number of messages matching the query. |
| `moreAvailable` | Boolean | Indicates whether more messages are available beyond the current response. |
| `messages` | Array | Array of message objects. |
| `id` | String | Unique identifier of the message. |
| `botId` | String | Unique identifier of the bot. |
| `type` | String | Direction: `incoming` or `outgoing`. |
| `status` | String | Message status, such as `pending` or `received`. |
| `createdOn` | String | ISO 8601 timestamp when the message was created. |
| `sessionId` | String | Unique session identifier. |
| `lang` | String | Language of the message. |
| `chnl` | String | Channel through which the message was sent. |
| `components` | Array | Array of message components. |
| `cT` | String | Type of message component, such as `text`. |
| `data` | Object | Object containing message content. |
| `channelUId` | String | Unique identifier of the channel. |
| `total.Ms` | Number | Total end-to-end latency from user utterance end to bot response playback start (ms). |
| `channels` | String | Array of channels involved in the message, each with `from`, `to`, and `channelUId` fields. |
| `channels.from` | String | Sender identifier for the channel, such as a phone number or email. |
| `channels.to` | String | Recipient identifier for the channel, such as a `phone number` or `email`. |
| `channels.channelUId` | String | Unique identifier for the channel interaction. |
| `latency` | Object | Object containing latency details, present when `includeLatency=true`. |
| `latency.totalMs` | String | Total end-to-end latency from user utterance end to bot response playback start (ms). |