> For the complete documentation index, see [llms.txt](https://dnotifier.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dnotifier.gitbook.io/product-docs/chat/chat-history.md).

# Chat history

Load past messages for a conversation thread with **`fetchChatHistory`**. On WebSocket clients, the response arrives via **`onMessage`** — not as the return value of the method call.

***

## When to fetch

| Moment                      | Action                                              |
| --------------------------- | --------------------------------------------------- |
| User opens a thread         | `fetchChatHistory` for the peer ID(s)               |
| App returns from background | Refetch or merge with live messages since last seen |
| After reconnect             | Refetch to fill gaps from offline period            |

***

## API contract

| Field         | Description                                         |
| ------------- | --------------------------------------------------- |
| `senderId`    | The requesting user (must match connected `userId`) |
| `receiverIds` | Array of peer user IDs defining the thread          |

```js
await notifier.fetchChatHistory({
  senderId: "user-alice",
  receiverIds: ["user-bob"],
});
// Response delivered to onMessage
```

{% hint style="info" %}
For 1:1 chat, pass a single peer ID in `receiverIds`. The server returns messages exchanged between the participants.
{% endhint %}

***

## Handling the response

History payloads arrive in `onMessage`. Shape is app-dependent but commonly includes a `messages` array:

```js
onMessage: (msg) => {
  const body = msg.payload.toJSON();
  if (Array.isArray(body?.messages)) {
    setThreadMessages(body.messages);
  }
},
```

Distinguish history responses from live messages by checking for the `messages` array or a metadata hint your app recognizes.

***

## HTTP transport note

With `transport: "http"`, `fetchChatHistory` may return the response directly from the async call instead of routing through `onMessage`. For chat UIs, prefer **`ws`** for unified live + history handling.

***

## Language guides

| Language                | Guide                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------ |
| JavaScript / TypeScript | [javascript-typescript.md](/product-docs/chat/chat-history/javascript-typescript.md) |
| Dart / Flutter          | [dart-flutter.md](/product-docs/chat/chat-history/dart-flutter.md)                   |

***

## Related topics

* [Save history flag](/product-docs/chat/save-history.md)
* [Delete chat messages](/product-docs/chat/delete-messages.md)
* [Building 1:1 chat](/product-docs/chat/building-one-to-one-chat.md)