rmyndharis--openwa
wehub-resource-sync
4ce4204b6c
CI / Lint (push) Failing after 2s
CI / Build (push) Has been skipped
SDK CI / PHP SDK (push) Failing after 1s
Split PHP SDK / PHP SDK tests (push) Failing after 1s
CI / Test (push) Failing after 1s
CI / Dashboard (push) Failing after 0s
SDK CI / JavaScript SDK (push) Failing after 0s
SDK CI / Python SDK (push) Failing after 2s
SDK CI / Java SDK (push) Failing after 1s
Split PHP SDK / Mirror sdk/php -> rmyndharis/openwa-php (push) Has been skipped
CI / Test (PostgreSQL migrations) (push) Failing after 7m47s
CI / Docker Build (push) Has been skipped
71 行
3.3 KiB
Markdown
71 行
3.3 KiB
Markdown
# Chat History Limits
|
|
|
|
OpenWA has two different history paths, and they answer different questions.
|
|
|
|
## Local Message History
|
|
|
|
```http
|
|
GET /api/sessions/{sessionId}/messages
|
|
```
|
|
|
|
This endpoint reads from OpenWA's local database. It returns messages that OpenWA has observed and persisted while the session was connected.
|
|
|
|
Use this when you want stable pagination over messages already stored by OpenWA.
|
|
|
|
## Live WhatsApp Chat History
|
|
|
|
```http
|
|
GET /api/sessions/{sessionId}/messages/{chatId}/history?limit=50
|
|
```
|
|
|
|
This endpoint asks the active WhatsApp engine for recent messages in a chat. It bypasses OpenWA's local database and can be useful for retrieving messages that are visible to the linked WhatsApp Web session but were not yet stored locally.
|
|
|
|
The endpoint is intentionally bounded:
|
|
|
|
- `limit` defaults to `50`.
|
|
- `limit` is clamped to the range `1`–`100` (or `1`–`2000` with `deep=true`, see below).
|
|
- Values such as `limit=999` do not request unbounded history; they are reduced to the maximum allowed limit.
|
|
- `includeMedia=true` downloads media data and is slower than metadata-only history.
|
|
- `deep=true` raises the ceiling to `2000` for reaching further back, and forces metadata-only.
|
|
|
|
## How Deep It Can Reach
|
|
|
|
By default the live history endpoint returns at most the **100 most recent** messages per request (the
|
|
`limit` clamp above). The `whatsapp-web.js` engine *can* load older messages on demand — internally it
|
|
drives WhatsApp Web's "load earlier messages" mechanism — so reaching further back is bounded by
|
|
**OpenWA's cap**, not by what WhatsApp Web is willing to expose.
|
|
|
|
To go back weeks or months, set `deep=true`. This raises the ceiling to **2000** messages per request:
|
|
|
|
```http
|
|
GET /api/sessions/{sessionId}/messages/{chatId}/history?limit=2000&deep=true
|
|
```
|
|
|
|
Deep mode is **metadata-only** — `includeMedia` is ignored, because downloading base64 media for up to
|
|
2000 messages would produce an enormous, slow response. Fetch media separately for the specific messages
|
|
you need. Note that a very large, rapid history pull is heavier on the linked session and can increase the
|
|
risk of WhatsApp rate-limiting; use the smallest window that meets your need.
|
|
|
|
Deep mode applies to the `whatsapp-web.js` engine. The Baileys engine does not expose on-demand history
|
|
(it has no message-history sync), so the history endpoint returns `501 Not Implemented` there regardless
|
|
of `deep`; consume Baileys history through local storage / webhooks / WebSocket as it arrives instead.
|
|
|
|
There is still an ultimate ceiling: once WhatsApp's servers stop returning older messages for the linked
|
|
session, no further history is retrievable through the web engine, regardless of `limit`. So the endpoint
|
|
does not guarantee a complete import of all server-side WhatsApp history.
|
|
|
|
## Recommended Usage
|
|
|
|
For reliable long-term history, keep the OpenWA session connected and consume messages as they arrive through local storage, webhooks, or WebSocket events.
|
|
|
|
Use the live history endpoint as a bounded recent-history helper, not as a full historical import mechanism.
|
|
|
|
## Example
|
|
|
|
```bash
|
|
curl -H "X-API-Key: $API_KEY" \
|
|
"http://localhost:2785/api/sessions/default/messages/628123456789@c.us/history?limit=100"
|
|
```
|
|
|
|
Use `limit=100` when you want the maximum single-request live history window currently allowed by OpenWA.
|