Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): warn that clearing or deleting a chat purges stored messages

Yudhi Armyndharisf3dc3922b010
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 418ee615c..975187b7c 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -229,19 +229,19 @@ Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mime
#### `chats`
-| Method | Signature | Description |
-| ------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `list` | `list(sessionId, query?)` | List active chats, most recent first. |
-| `subscribePresence` | `subscribePresence(sessionId, body)` | Subscribe to a chat's presence; updates then arrive as `presence.update` events. The subscription belongs to the connection and does not survive a reconnect. **OPERATOR** |
-| `getPresence` | `getPresence(sessionId, chatId)` | The last presence reported for a chat, or `null` when none has been. Held in memory, so a restart clears it. |
-| `markRead` | `markRead(sessionId, body)` | Mark a chat as read/seen. **OPERATOR** |
-| `markUnread` | `markUnread(sessionId, body)` | Mark a chat as unread. **OPERATOR** |
-| `archive` | `archive(sessionId, body)` | Archive or unarchive a chat. `success: false` means the engine declined. **OPERATOR** |
-| `pin` | `pin(sessionId, body)` | Pin a chat to the top of the list, or unpin it. `success: false` means WhatsApp declined — three pins maximum. **OPERATOR** |
-| `mute` | `mute(sessionId, body)` | Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with `null`. **OPERATOR** |
-| `clearMessages` | `clearMessages(sessionId, chatId)` | Delete every message in a chat, keeping the chat itself. **OPERATOR** |
-| `delete` | `delete(sessionId, body)` | Delete a chat from the chat list. **OPERATOR** |
-| `sendState` | `sendState(sessionId, body)` | Send a chat presence state (typing/recording/paused). **OPERATOR** |
+| Method | Signature | Description |
+| ------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list` | `list(sessionId, query?)` | List active chats, most recent first. |
+| `subscribePresence` | `subscribePresence(sessionId, body)` | Subscribe to a chat's presence; updates then arrive as `presence.update` events. The subscription belongs to the connection and does not survive a reconnect. **OPERATOR** |
+| `getPresence` | `getPresence(sessionId, chatId)` | The last presence reported for a chat, or `null` when none has been. Held in memory, so a restart clears it. |
+| `markRead` | `markRead(sessionId, body)` | Mark a chat as read/seen. **OPERATOR** |
+| `markUnread` | `markUnread(sessionId, body)` | Mark a chat as unread. **OPERATOR** |
+| `archive` | `archive(sessionId, body)` | Archive or unarchive a chat. `success: false` means the engine declined. **OPERATOR** |
+| `pin` | `pin(sessionId, body)` | Pin a chat to the top of the list, or unpin it. `success: false` means WhatsApp declined — three pins maximum. **OPERATOR** |
+| `mute` | `mute(sessionId, body)` | Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with `null`. **OPERATOR** |
+| `clearMessages` | `clearMessages(sessionId, chatId)` | Delete every message in a chat, keeping the chat itself. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. **OPERATOR** |
+| `delete` | `delete(sessionId, body)` | Delete a chat from the chat list. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. **OPERATOR** |
+| `sendState` | `sendState(sessionId, body)` | Send a chat presence state (typing/recording/paused). **OPERATOR** |
#### `webhooks`
@@ -606,19 +606,19 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All
#### `client.chats`
-| Method | Signature | Description |
-| -------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `list` | `list(session_id, query=None) -> list[ChatSummary]` | List chats (`query`: `limit`, `offset`). |
-| `subscribe_presence` | `subscribe_presence(session_id, body) -> SuccessResult` | Subscribe to a chat's presence; updates then arrive as `presence.update` events. The subscription belongs to the connection and does not survive a reconnect. **OPERATOR** |
-| `get_presence` | `get_presence(session_id, chat_id) -> ChatPresence \| None` | The last presence reported for a chat, or `null` when none has been. Held in memory, so a restart clears it. |
-| `mark_read` | `mark_read(session_id, body) -> SuccessResult` | Mark a chat as read. **OPERATOR** |
-| `mark_unread` | `mark_unread(session_id, body) -> SuccessResult` | Mark a chat as unread. **OPERATOR** |
-| `archive` | `archive(session_id, body) -> SuccessResult` | Archive or unarchive a chat. `success: false` means the engine declined. **OPERATOR** |
-| `pin` | `pin(session_id, body) -> SuccessResult` | Pin a chat to the top of the list, or unpin it. `success: false` means WhatsApp declined — three pins maximum. **OPERATOR** |
-| `mute` | `mute(session_id, body) -> SuccessResult` | Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with `null`. **OPERATOR** |
-| `clear_messages` | `clear_messages(session_id, chat_id) -> SuccessResult` | Delete every message in a chat, keeping the chat itself. **OPERATOR** |
-| `delete` | `delete(session_id, body) -> SuccessResult` | Delete a chat. **OPERATOR** |
-| `send_state` | `send_state(session_id, body) -> SuccessResult` | Send a typing/recording chat state. **OPERATOR** |
+| Method | Signature | Description |
+| -------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list` | `list(session_id, query=None) -> list[ChatSummary]` | List chats (`query`: `limit`, `offset`). |
+| `subscribe_presence` | `subscribe_presence(session_id, body) -> SuccessResult` | Subscribe to a chat's presence; updates then arrive as `presence.update` events. The subscription belongs to the connection and does not survive a reconnect. **OPERATOR** |
+| `get_presence` | `get_presence(session_id, chat_id) -> ChatPresence \| None` | The last presence reported for a chat, or `null` when none has been. Held in memory, so a restart clears it. |
+| `mark_read` | `mark_read(session_id, body) -> SuccessResult` | Mark a chat as read. **OPERATOR** |
+| `mark_unread` | `mark_unread(session_id, body) -> SuccessResult` | Mark a chat as unread. **OPERATOR** |
+| `archive` | `archive(session_id, body) -> SuccessResult` | Archive or unarchive a chat. `success: false` means the engine declined. **OPERATOR** |
+| `pin` | `pin(session_id, body) -> SuccessResult` | Pin a chat to the top of the list, or unpin it. `success: false` means WhatsApp declined — three pins maximum. **OPERATOR** |
+| `mute` | `mute(session_id, body) -> SuccessResult` | Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with `null`. **OPERATOR** |
+| `clear_messages` | `clear_messages(session_id, chat_id) -> SuccessResult` | Delete every message in a chat, keeping the chat itself. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. **OPERATOR** |
+| `delete` | `delete(session_id, body) -> SuccessResult` | Delete a chat. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. **OPERATOR** |
+| `send_state` | `send_state(session_id, body) -> SuccessResult` | Send a typing/recording chat state. **OPERATOR** |
#### `client.webhooks`
@@ -958,19 +958,19 @@ All payloads are associative arrays; all listed methods are synchronous and retu
#### `chats`
-| Method | Signature | Description |
-| ------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `list` | `list(string $sessionId, array $query = []): array` | List chats. |
-| `subscribePresence` | `subscribePresence(string $sessionId, array $body): array` | Subscribe to a chat's presence; updates then arrive as `presence.update` events. The subscription belongs to the connection and does not survive a reconnect. **OPERATOR** |
-| `getPresence` | `getPresence(string $sessionId, string $chatId): ?array` | The last presence reported for a chat, or `null` when none has been. Held in memory, so a restart clears it. |
-| `markRead` | `markRead(string $sessionId, array $body): array` | Mark chat(s) read. **OPERATOR** |
-| `markUnread` | `markUnread(string $sessionId, array $body): array` | Mark chat(s) unread. **OPERATOR** |
-| `archive` | `archive(string $sessionId, array $body): array` | Archive or unarchive a chat. `success: false` means the engine declined. **OPERATOR** |
-| `pin` | `pin(string $sessionId, array $body): array` | Pin a chat to the top of the list, or unpin it. `success: false` means WhatsApp declined — three pins maximum. **OPERATOR** |
-| `mute` | `mute(string $sessionId, array $body): array` | Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with `null`. **OPERATOR** |
-| `clearMessages` | `clearMessages(string $sessionId, string $chatId): array` | Delete every message in a chat, keeping the chat itself. **OPERATOR** |
-| `delete` | `delete(string $sessionId, array $body): array` | Delete chat(s). **OPERATOR** |
-| `sendState` | `sendState(string $sessionId, array $body): array` | Send a typing/recording state. **OPERATOR** |
+| Method | Signature | Description |
+| ------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list` | `list(string $sessionId, array $query = []): array` | List chats. |
+| `subscribePresence` | `subscribePresence(string $sessionId, array $body): array` | Subscribe to a chat's presence; updates then arrive as `presence.update` events. The subscription belongs to the connection and does not survive a reconnect. **OPERATOR** |
+| `getPresence` | `getPresence(string $sessionId, string $chatId): ?array` | The last presence reported for a chat, or `null` when none has been. Held in memory, so a restart clears it. |
+| `markRead` | `markRead(string $sessionId, array $body): array` | Mark chat(s) read. **OPERATOR** |
+| `markUnread` | `markUnread(string $sessionId, array $body): array` | Mark chat(s) unread. **OPERATOR** |
+| `archive` | `archive(string $sessionId, array $body): array` | Archive or unarchive a chat. `success: false` means the engine declined. **OPERATOR** |
+| `pin` | `pin(string $sessionId, array $body): array` | Pin a chat to the top of the list, or unpin it. `success: false` means WhatsApp declined — three pins maximum. **OPERATOR** |
+| `mute` | `mute(string $sessionId, array $body): array` | Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with `null`. **OPERATOR** |
+| `clearMessages` | `clearMessages(string $sessionId, string $chatId): array` | Delete every message in a chat, keeping the chat itself. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. **OPERATOR** |
+| `delete` | `delete(string $sessionId, array $body): array` | Delete chat(s). On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. **OPERATOR** |
+| `sendState` | `sendState(string $sessionId, array $body): array` | Send a typing/recording state. **OPERATOR** |
#### `webhooks`