---
source_url: https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/messages/history
title: Message history
updated_at: 2026-06-26T11:03:28.922Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Message history

PubNub APIs let you effectively fetch historical messages from direct, group, or public conversations.

While [App Context API](https://www.pubnub.com/docs/general/metadata/basics) lets you manage metadata and relationships between users and channels, enabling efficient tracking of which channels are associated with a given user, [Message Persistence API](https://www.pubnub.com/docs/general/storage) lets you retrieve messages from those channels. Together, these APIs enable you to gather all conversations involving a user and easily fetch specific message histories for any interactions between users.

Use `getHistory()` to fetch past messages from a channel.

:::note API limitation
Results cannot be filtered by message type. All messages within the specified timeframe are returned.
:::

### Method signature

This method takes the following parameters:

```kotlin
channel.getHistory(
    startTimetoken: Long?,
    endTimetoken: Long?,
    count: Int = 25
): PNFuture<HistoryResponse<*>>
```

#### Input

:::warning How to use the startTimetoken and endTimetoken parameters
PubNub retrieves messages by searching **backward through time** (newest to oldest). Because of this, the parameter names are the reverse of their intuitive meaning:
* **startTimetoken** is the **newer** boundary (higher timetoken value) - search begins here, **exclusive**
* **endTimetoken** is the **older** boundary (lower timetoken value) - search stops here, **inclusive**
When you provide both parameters, `startTimetoken` must be a **higher** timetoken than `endTimetoken`.
9:00 AM
10:00 AM
11:00 AM
11:59 AM
Results are always returned in oldest-first order.
:::

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| startTimetoken | Long | Optional |  | Timetoken delimiting the start of a time slice (exclusive) to pull messages from. For details, refer to the [Message Persistence](https://www.pubnub.com/docs/sdks/kotlin/api-reference/storage-and-playback). |
| endTimetoken | Long | Optional |  | Timetoken delimiting the end of a time slice (inclusive) to pull messages from. For details, refer to the [Message Persistence](https://www.pubnub.com/docs/sdks/kotlin/api-reference/storage-and-playback). |
| count | Int | Optional | `25` | Number of historical messages to return for the channel in a single call. Since each call returns all attached [message reactions](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/messages/reactions) by default this value is '25'. The maximum allowed value is `25`. For more details, refer to the description of the `includeMessageActions` parameter in the [Kotlin SDK docs](https://www.pubnub.com/docs/sdks/kotlin/api-reference/storage-and-playback#methods). |

#### Output

| Type | Description |
| --- | --- |
| `PNFuture<HistoryResponse<*>>` | `PNFuture` containing a list of messages with pagination information (`isMore: Boolean`). |

By default, each call returns all message reactions and metadata attached to the retrieved messages.

### Sample code

From the `support` channel, fetch `10` historical messages older than the timetoken `15343325214676133`.

```kotlin
val timetoken: Long = 15343325214676133
val messageCount: Int = 10

chat.getChannel("support").async { supportResult ->
    supportResult.onSuccess { supportChannel ->
        // handle success
        supportChannel.getHistory(endTimetoken = timetoken, count = messageCount).async { historyResult ->
            historyResult.onSuccess { history ->
                // handle success
            }.onFailure {
                // handle failure
            }
        }
    }.onFailure {
        // handle failure
    }
}
```