Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(message): state that chat history comes back oldest first

Yudhi Armyndharis93411ea098b4
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 1cc46e1c5..b55a15d78 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1310,7 +1310,8 @@ Fetch chat history live from WhatsApp for a chat, bypassing the local DB.
**Response** `200`
-Returns a bare array of engine-neutral `IncomingMessage` objects:
+Returns a bare array of engine-neutral `IncomingMessage` objects: the chat's most recent `limit` messages, oldest first
+(ascending `timestamp`).
```json
[
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index 47b763ce5..b4e4c6805 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -329,7 +329,7 @@ export interface PluginEngineReadCapability {
getContactById(sessionId: string, contactId: string): Promise<...>;
checkNumberExists(sessionId: string, phone: string): Promise<...>;
getChats(sessionId: string): Promise<...>;
- // Recent messages for a chat, both directions (history backfill). `limit` is clamped host-side to 1-100.
+ // Recent messages for a chat, both directions, oldest first (history backfill). `limit` is clamped host-side to 1-100.
getChatHistory(sessionId: string, chatId: string, limit?: number, includeMedia?: boolean): Promise<...>;
// Canonical form of a chat id: resolves a known '@lid' privacy id to its stable '<phone>@c.us',
// otherwise returns the id unchanged (best-effort).
diff --git a/openapi.json b/openapi.json
index 21a36578e..b826120dd 100644
--- a/openapi.json
+++ b/openapi.json
@@ -3359,7 +3359,7 @@
],
"responses": {
"200": {
- "description": "Chat history (most recent messages)",
+ "description": "Chat history (most recent messages, oldest first)",
"content": {
"application/json": {
"schema": {
diff --git a/src/core/plugins/plugin.interfaces.ts b/src/core/plugins/plugin.interfaces.ts
index 3f8828f65..bce0a6295 100644
--- a/src/core/plugins/plugin.interfaces.ts
+++ b/src/core/plugins/plugin.interfaces.ts
@@ -511,7 +511,10 @@ export interface PluginEngineReadCapability {
getContactById(sessionId: string, contactId: string): ReturnType<IWhatsAppEngine['getContactById']>;
checkNumberExists(sessionId: string, phone: string): ReturnType<IWhatsAppEngine['checkNumberExists']>;
getChats(sessionId: string): ReturnType<IWhatsAppEngine['getChats']>;
- /** Recent messages for a chat (both directions), for history backfill. `limit` is clamped host-side. */
+ /**
+ * Recent messages for a chat (both directions), oldest first, for history backfill. `limit` is
+ * clamped host-side.
+ */
getChatHistory(
sessionId: string,
chatId: string,
diff --git a/src/engine/interfaces/whatsapp-engine.interface.ts b/src/engine/interfaces/whatsapp-engine.interface.ts
index 7321ba653..798dea23c 100644
--- a/src/engine/interfaces/whatsapp-engine.interface.ts
+++ b/src/engine/interfaces/whatsapp-engine.interface.ts
@@ -1090,13 +1090,14 @@ export interface MessageOperationsCapability {
*/
export interface ChatHistoryCapability {
/**
- * Read a chat's recent messages, newest first. When `includeMedia` downloads blobs, an optional
- * `mediaMaxBytes` tightens the declared-size pre-gate below the global MEDIA_DOWNLOAD_MAX_BYTES —
+ * Read a chat's most recent `limit` messages, returned oldest first (ascending timestamp). When
+ * `includeMedia` downloads blobs, an optional `mediaMaxBytes` tightens the declared-size pre-gate
+ * below the global MEDIA_DOWNLOAD_MAX_BYTES —
* the status seed uses it to skip downloads the store would discard as over-cap anyway.
- * Inlined media is additionally bounded in aggregate (CHAT_HISTORY_MEDIA_BUDGET_BYTES): once the
- * running base64 total crosses the budget, later media messages carry the `omitted` marker instead
- * of a download. An optional `signal` (e.g. client disconnect) stops the read loop early; the
- * messages collected so far are returned.
+ * Inlined media is additionally bounded in aggregate (CHAT_HISTORY_MEDIA_BUDGET_BYTES), spent in
+ * that same order: once the running base64 total crosses the budget, the newer media messages
+ * carry the `omitted` marker instead of a download. An optional `signal` (e.g. client disconnect)
+ * stops the read loop early; the messages collected so far are returned.
*/
getChatHistory(
chatId: string,
diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.ts
index abe5eb34a..bebf0e525 100644
--- a/src/modules/message/message.controller.ts
+++ b/src/modules/message/message.controller.ts
@@ -570,7 +570,11 @@ export class MessageController {
'(whatsapp-web.js only; loads earlier messages on demand). Forces metadata-only (includeMedia ' +
'is ignored). Large/slow requests may increase WhatsApp rate-limiting risk; default false.',
})
- @ApiResponse({ status: 200, description: 'Chat history (most recent messages)', type: [ChatHistoryMessageDto] })
+ @ApiResponse({
+ status: 200,
+ description: 'Chat history (most recent messages, oldest first)',
+ type: [ChatHistoryMessageDto],
+ })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 501, description: ENGINE_NOT_SUPPORTED_501 })
@ApiResponse({