> ## 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](https://koreai.mintlify.site/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.

> [!NOTE]
>
> 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](https://koreai.mintlify.site/ai-for-service/apis/automation/api-introduction.md#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.

> [!NOTE]
>
> 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:**

```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' \
--data '{
    "sessionId": ["6ae5c01a837894cdf10axxxx"],
    "channelType": "korevg",
    "dateFrom": "2026-10-31T00:00:00.000Z",
    "dateTo": "2026-11-01T00:00:00.000Z",
    "limit": 100,
    "skip": 0,
    "includeLatency": true
}'
```

**POST v2:**

```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/getMessagesV2' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": ["6ae5c01a837894cdf10axxxx"],
    "channelType": "korevg",
    "dateFrom": "2026-10-31T00:00:00.000Z",
    "dateTo": "2026-11-01T00:00:00.000Z",
    "limit": 100,
    "skip": 0,
    "includeLatency": true
}'
```

**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. |
| `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. |

> [!NOTE]
>
> 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:**

```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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.