> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-agent-management-platform-dev.mintlify.app/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)
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:**
```json theme={null}
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:**
```json theme={null}
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:**
```json theme={null}
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:**
```json theme={null}
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):**
```json 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
| 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:**
```json theme={null}
{
"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. |
Built with [Mintlify](https://mintlify.com).