Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): correct the method tables, errors and timeout notes
Yudhi Armyndharisbb92c2200f5c
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 3a2fabbe5..004e16d2a 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -85,7 +85,7 @@ async function main() {const session = await client.sessions.create({ name: 'my-session' });await client.sessions.start(session.id);- // Link the account before sending: scan sessions.getQrCode or use sessions.requestPairingCode,+ // Link the account before sending: scan sessions.getQrCode (or use sessions.requestPairingCode for a number with no linked session),// then wait for status 'ready'. An unlinked session answers the send with 409.// Send a text message.@@ -122,14 +122,14 @@ The constructor takes a single `OpenWAClientOptions` object. `baseUrl` and `apiK### Resources & Methods-All resources are accessed as properties on the client (`client.<resource>.<method>`). Every method returns a `Promise`. Methods marked **OPERATOR** require an `OPERATOR`-level API key (an `ADMIN` key satisfies it); a `VIEWER` key receives a `403` (`OpenWAForbiddenError`).+All resources are accessed as properties on the client (`client.<resource>.<method>`). Every method returns a `Promise`. Methods marked **OPERATOR** require an `OPERATOR`-level API key (an `ADMIN` key satisfies it); a `VIEWER` key receives a `403` (`OpenWAForbiddenError`). Some methods are supported by one engine only and answer `501` on the other (a row says so where it matters; section [29.6 of the engine capability matrix](./29-engine-capability-matrix.md#296-the-27-not-available-cells-in-detail) lists them all).The top-level client also exposes:-| Method | Signature | Description |-| --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |-| `auth` | `client.auth()` | Validate the configured API key and resolve its role and the running engine (`{ valid, role?, engineType?, scoped? }`). |-| `request` | `client.request<T>(options)` | Raw escape hatch — issue an arbitrary request against the API. |+| Method | Signature | Description |+| --------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `auth` | `client.auth()` | Validate the configured API key and resolve its role and the running engine (`{ valid, role?, engineType?, scoped? }`); a key restricted to selected chats is refused with `403`. |+| `request` | `client.request<T>(options)` | Raw escape hatch — issue an arbitrary request against the API. |#### `sessions`@@ -148,41 +148,41 @@ The top-level client also exposes:| `logout` | `logout(id)` | Attempt an engine-native unlink of this device, then stop the session. A `200` means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later `start` needs a fresh QR. A `502` (`SESSION_LOGOUT_INCOMPLETE`) stops locally but leaves the operation incomplete; start and retry. Requires a running session. **OPERATOR** || `forceKill` | `forceKill(id)` | Force-kill a stuck session (SIGKILL + teardown). A `502` (`SESSION_FORCE_KILL_INCOMPLETE`) stops locally but the engine process may still be running; a retry answers `400`, so restart the node to reap it. **OPERATOR** || `getQrCode` | `getQrCode(id)` | Get the current QR code for authentication (live from the engine). **OPERATOR** |-| `requestPairingCode` | `requestPairingCode(id, body)` | Request an 8-character pairing code for phone-based login. **OPERATOR** |+| `requestPairingCode` | `requestPairingCode(id, body)` | Request an 8-character pairing code for phone-based login. On whatsapp-web.js, not for a number that already has a linked session (WhatsApp can revoke that device); link it by QR instead. **OPERATOR** || `setOnlinePresence` | `setOnlinePresence(id, body)` | Set the account's own global presence (appear online or offline). **OPERATOR** || `stats` | `stats()` | Aggregate statistics across the key's sessions. |#### `messages`-| Method | Signature | Description |-| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |-| `list` | `list(sessionId, query?)` | List messages (filter by chat/sender); returns `{ messages, total }`. |-| `sendText` | `sendText(sessionId, { chatId, text })` | Send a text message (`text` max 4096 chars). **OPERATOR** |-| `sendImage` | `sendImage(sessionId, body)` | Send an image (`url` or `base64`). **OPERATOR** |-| `sendVideo` | `sendVideo(sessionId, body)` | Send a video (`url` or `base64`). **OPERATOR** |-| `sendAudio` | `sendAudio(sessionId, body)` | Send an audio file (`url` or `base64`). **OPERATOR** |-| `sendDocument` | `sendDocument(sessionId, body)` | Send a document (`url` or `base64`; `filename` recommended). **OPERATOR** |-| `sendSticker` | `sendSticker(sessionId, body)` | Send a sticker (`url` or `base64`). **OPERATOR** |-| `sendLocation` | `sendLocation(sessionId, body)` | Send a location (`{ chatId, latitude, longitude, description? }`). **OPERATOR** |-| `sendContact` | `sendContact(sessionId, body)` | Send a contact card. **OPERATOR** |-| `sendTemplate` | `sendTemplate(sessionId, body)` | Render and send a stored message template. **OPERATOR** |-| `sendPoll` | `sendPoll(sessionId, body)` | Send a poll message. **OPERATOR** |-| `reply` | `reply(sessionId, body)` | Reply to a specific message. **OPERATOR** |-| `forward` | `forward(sessionId, body)` | Forward a message to another chat. **OPERATOR** |-| `clickButton` | `clickButton(sessionId, body)` | Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). **OPERATOR** |-| `react` | `react(sessionId, body)` | React to a message (empty `reaction` removes it). **OPERATOR** |-| `delete` | `delete(sessionId, body)` | Delete a message. **OPERATOR** |-| `editMessage` | `editMessage(sessionId, body)` | Edit the text of a message already sent. **OPERATOR** |-| `history` | `history(sessionId, chatId, query?)` | Get message history for a chat (read live from WhatsApp). |-| `reactions` | `reactions(sessionId, chatId, messageId)` | Get reactions for a specific message. |-| `pin` | `pin(sessionId, body)` | Pin a message in its chat. `durationSeconds` must be 86400, 604800 or 2592000; in a group only admins may pin. **OPERATOR** |-| `votePoll` | `votePoll(sessionId, body)` | Cast a vote on a poll; `options` are the option texts, not ids. Not supported on Baileys (`501`). **OPERATOR** |-| `star` | `star(sessionId, body)` | Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. **OPERATOR** |-| `unpin` | `unpin(sessionId, body)` | Unpin a pinned message. **OPERATOR** |-| `media` | `media(sessionId, chatId, messageId)` | Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. `404` when neither holds bytes. |-| `sendBulk` | `sendBulk(sessionId, body)` | Send a batch asynchronously (202 + batch id); poll via `batchStatus`. **OPERATOR** |-| `batchStatus` | `batchStatus(sessionId, batchId)` | Poll the status/progress of a bulk-send batch. |-| `cancelBatch` | `cancelBatch(sessionId, batchId)` | Cancel a running batch. **OPERATOR** |+| Method | Signature | Description |+| -------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `list` | `list(sessionId, query?)` | List messages. Filters: `type`, `direction`, `chatId`, `from`, `messageId`, `since` (inclusive) and `until` (exclusive) as epoch milliseconds, `orderBy` (`createdAt`, or `timestamp`, which leaves out rows without a message time), `limit`, `offset`, `after` (keyset cursor: the `id` of the last row of the previous page; wins over `offset`) and `inlineMedia` (`false` omits inline media payloads). Returns `{ messages, total, unknownTimestampTotal? }`; `unknownTimestampTotal` counts the rows matching the other filters whose message time is unknown, and is present only with a time bound or `orderBy: 'timestamp'`. |+| `sendText` | `sendText(sessionId, { chatId, text })` | Send a text message (`text` max 4096 chars). **OPERATOR** |+| `sendImage` | `sendImage(sessionId, body)` | Send an image (`url` or `base64`). **OPERATOR** |+| `sendVideo` | `sendVideo(sessionId, body)` | Send a video (`url` or `base64`). **OPERATOR** |+| `sendAudio` | `sendAudio(sessionId, body)` | Send an audio file (`url` or `base64`). **OPERATOR** |+| `sendDocument` | `sendDocument(sessionId, body)` | Send a document (`url` or `base64`; `filename` recommended). **OPERATOR** |+| `sendSticker` | `sendSticker(sessionId, body)` | Send a sticker (`url` or `base64`). **OPERATOR** |+| `sendLocation` | `sendLocation(sessionId, body)` | Send a location (`{ chatId, latitude, longitude, description? }`). **OPERATOR** |+| `sendContact` | `sendContact(sessionId, body)` | Send a contact card. **OPERATOR** |+| `sendTemplate` | `sendTemplate(sessionId, body)` | Render and send a stored message template. **OPERATOR** |+| `sendPoll` | `sendPoll(sessionId, body)` | Send a poll message. **OPERATOR** |+| `reply` | `reply(sessionId, body)` | Reply to a specific message. **OPERATOR** |+| `forward` | `forward(sessionId, body)` | Forward a message to another chat. **OPERATOR** |+| `clickButton` | `clickButton(sessionId, body)` | Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). **OPERATOR** |+| `react` | `react(sessionId, body)` | React to a message (an empty `emoji` removes the reaction). **OPERATOR** |+| `delete` | `delete(sessionId, body)` | Delete a message. **OPERATOR** |+| `editMessage` | `editMessage(sessionId, body)` | Edit the text of a message already sent. **OPERATOR** |+| `history` | `history(sessionId, chatId, query?)` | Get message history for a chat (read live from WhatsApp). |+| `reactions` | `reactions(sessionId, chatId, messageId)` | Get reactions for a specific message. |+| `pin` | `pin(sessionId, body)` | Pin a message in its chat. `durationSeconds` must be 86400, 604800 or 2592000; in a group only admins may pin. **OPERATOR** |+| `votePoll` | `votePoll(sessionId, body)` | Cast a vote on a poll; `options` are the option texts, not ids. Not supported on Baileys (`501`). **OPERATOR** |+| `star` | `star(sessionId, body)` | Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. **OPERATOR** |+| `unpin` | `unpin(sessionId, body)` | Unpin a pinned message. **OPERATOR** |+| `media` | `media(sessionId, chatId, messageId)` | Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. `404` when neither holds bytes. |+| `sendBulk` | `sendBulk(sessionId, body)` | Send a batch asynchronously (202 + batch id); poll via `batchStatus`. **OPERATOR** |+| `batchStatus` | `batchStatus(sessionId, batchId)` | Poll the status/progress of a bulk-send batch. |+| `cancelBatch` | `cancelBatch(sessionId, batchId)` | Cancel a running batch. **OPERATOR** |Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mimetype?, filename?, caption? }` (`url` and `base64` are mutually exclusive; `base64` requires `mimetype`).@@ -217,7 +217,7 @@ Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mime| `demoteParticipants` | `demoteParticipants(sessionId, groupId, participants)` | Demote participants from group admin. **OPERATOR** || `setSubject` | `setSubject(sessionId, groupId, subject)` | Update the group subject (name). **OPERATOR** || `setDescription` | `setDescription(sessionId, groupId, description)` | Update the group description (empty clears it). **OPERATOR** |-| `getGroupSettings` | `getGroupSettings(sessionId, groupId)` | Get the group settings (announce / locked / ephemeral timer). |+| `getGroupSettings` | `getGroupSettings(sessionId, groupId)` | Get the group settings (announce / locked / ephemeral timer / who may add members). || `updateGroupSettings` | `updateGroupSettings(sessionId, groupId, body)` | Update the group settings (at least one field required). **OPERATOR** || `leave` | `leave(sessionId, groupId)` | Leave a group. **OPERATOR** || `getPicture` | `getPicture(sessionId, groupId)` | The group's picture URL, or `null` when it has none. |@@ -368,7 +368,7 @@ On a non-2xx response the SDK throws a typed `OpenWAApiError` subclass carrying| `OpenWAAuthError` | 401 | Missing or invalid API key. || `OpenWAForbiddenError` | 403 | The key's role or scope refuses the call (e.g. an OPERATOR-only route, or a session, IP or chat outside the key's allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). || `OpenWANotFoundError` | 404 | Resource not found. |-| `OpenWAConflictError` | 409 | Conflict — typically the engine is not ready. |+| `OpenWAConflictError` | 409 | Conflict: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see `code`). || `OpenWARateLimitError` | 429 | Rate limited. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `retryAfterSeconds` carries its `Retry-After` header. A 429 whose `code` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `retryAfterSeconds`, which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (`SEND_PACING_BREAKER_COOLDOWN_MS`, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. || `OpenWANotImplementedError` | 501 | The active engine does not support this operation. || `OpenWAServiceUnavailableError` | 503 | The engine did not confirm in time. Transient, though a catalog 503 can persist because WhatsApp may never answer that query; 501 is permanent. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |@@ -456,7 +456,7 @@ client = OpenWAClient(session = client.sessions.create({"name": "my-session"})client.sessions.start(session["id"])-# Link the account before sending: scan sessions.get_qr_code or use sessions.request_pairing_code,+# Link the account before sending: scan sessions.get_qr_code (or use sessions.request_pairing_code for a number with no linked session),# then wait for status "ready". An unlinked session answers the send with 409.# Send a text message@@ -509,7 +509,7 @@ The client also exposes a few non-resource members:### Resources & Methods-Resources are accessed as properties on the client (e.g. `client.messages`). All methods are **snake_case**; `body`/`query` arguments are plain dicts. Methods marked **OPERATOR** require an `OPERATOR`-level API key.+Resources are accessed as properties on the client (e.g. `client.messages`). All methods are **snake_case**; `body`/`query` arguments are plain dicts. Methods marked **OPERATOR** require an `OPERATOR`-level API key. Some methods are supported by one engine only and answer `501` on the other (a row says so where it matters; section [29.6 of the engine capability matrix](./29-engine-capability-matrix.md#296-the-27-not-available-cells-in-detail) lists them all).#### `client.sessions`@@ -528,41 +528,41 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All| `logout` | `logout(session_id) -> SessionResponse` | Attempt an engine-native unlink of this device, then stop the session. A `200` means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later `start` needs a fresh QR. A `502` (`SESSION_LOGOUT_INCOMPLETE`) stops locally but leaves the operation incomplete; start and retry. Requires a running session. **OPERATOR** || `force_kill` | `force_kill(session_id) -> SessionResponse` | Force-terminate a session. A `502` (`SESSION_FORCE_KILL_INCOMPLETE`) stops locally but the engine process may still be running; a retry answers `400`, so restart the node to reap it. **OPERATOR** || `get_qr_code` | `get_qr_code(session_id) -> QrCodeResponse` | Fetch the login QR code. **OPERATOR** |-| `request_pairing_code` | `request_pairing_code(session_id, body) -> PairingCodeResponse` | Request a phone-number pairing code. **OPERATOR** |+| `request_pairing_code` | `request_pairing_code(session_id, body) -> PairingCodeResponse` | Request a phone-number pairing code. On whatsapp-web.js, not for a number that already has a linked session (WhatsApp can revoke that device); link it by QR instead. **OPERATOR** || `set_online_presence` | `set_online_presence(session_id, body) -> SuccessResult` | Set the account's own global presence (appear online or offline). **OPERATOR** || `stats` | `stats() -> SessionStatsOverview` | Session statistics overview. |#### `client.messages`-| Method | Signature | Description |-| --------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |-| `list` | `list(session_id, query=None) -> MessageListResponse` | List stored messages. |-| `send_text` | `send_text(session_id, body) -> MessageResponse` | Send a text message. **OPERATOR** |-| `send_image` | `send_image(session_id, body) -> MessageResponse` | Send an image. **OPERATOR** |-| `send_video` | `send_video(session_id, body) -> MessageResponse` | Send a video. **OPERATOR** |-| `send_audio` | `send_audio(session_id, body) -> MessageResponse` | Send audio. **OPERATOR** |-| `send_document` | `send_document(session_id, body) -> MessageResponse` | Send a document. **OPERATOR** |-| `send_sticker` | `send_sticker(session_id, body) -> MessageResponse` | Send a sticker. **OPERATOR** |-| `send_location` | `send_location(session_id, body) -> MessageResponse` | Send a location. **OPERATOR** |-| `send_contact` | `send_contact(session_id, body) -> MessageResponse` | Send a contact card. **OPERATOR** |-| `send_template` | `send_template(session_id, body) -> MessageResponse` | Send a stored template. **OPERATOR** |-| `send_poll` | `send_poll(session_id, body) -> MessageResponse` | Send a poll message. **OPERATOR** |-| `reply` | `reply(session_id, body) -> MessageResponse` | Reply to a message. **OPERATOR** |-| `forward` | `forward(session_id, body) -> MessageResponse` | Forward a message. **OPERATOR** |-| `click_button` | `click_button(session_id, body) -> MessageResponse` | Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). **OPERATOR** |-| `react` | `react(session_id, body) -> SuccessResult` | React to a message. **OPERATOR** |-| `delete` | `delete(session_id, body) -> SuccessResult` | Delete a message. **OPERATOR** |-| `edit_message` | `edit_message(session_id, body) -> MessageResponse` | Edit the text of a message already sent. **OPERATOR** |-| `history` | `history(session_id, chat_id, query=None) -> list[ChatHistoryMessage]` | Fetch chat history. |-| `reactions` | `reactions(session_id, chat_id, message_id) -> list[ReactionRecord]` | List reactions on a message. |-| `pin` | `pin(session_id, body) -> SuccessResult` | Pin a message in its chat. `durationSeconds` must be 86400, 604800 or 2592000; in a group only admins may pin. **OPERATOR** |-| `vote_poll` | `vote_poll(session_id, body) -> SuccessResult` | Cast a vote on a poll; `options` are the option texts, not ids. Not supported on Baileys (`501`). **OPERATOR** |-| `star` | `star(session_id, body) -> SuccessResult` | Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. **OPERATOR** |-| `unpin` | `unpin(session_id, body) -> SuccessResult` | Unpin a pinned message. **OPERATOR** |-| `media` | `media(session_id, chat_id, message_id) -> MessageMedia` | Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. `404` when neither holds bytes. |-| `send_bulk` | `send_bulk(session_id, body) -> BulkMessageResponse` | Enqueue a bulk send batch. **OPERATOR** |-| `batch_status` | `batch_status(session_id, batch_id) -> BatchStatusResponse` | Get bulk batch status. |-| `cancel_batch` | `cancel_batch(session_id, batch_id) -> BatchCancelResponse` | Cancel a running batch. **OPERATOR** |+| Method | Signature | Description |+| --------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `list` | `list(session_id, query=None) -> MessageListResponse` | List stored messages; the query takes the same keys as the JavaScript client's `messages.list`, and the response carries `unknownTimestampTotal` under the same conditions. |+| `send_text` | `send_text(session_id, body) -> MessageResponse` | Send a text message. **OPERATOR** |+| `send_image` | `send_image(session_id, body) -> MessageResponse` | Send an image. **OPERATOR** |+| `send_video` | `send_video(session_id, body) -> MessageResponse` | Send a video. **OPERATOR** |+| `send_audio` | `send_audio(session_id, body) -> MessageResponse` | Send audio. **OPERATOR** |+| `send_document` | `send_document(session_id, body) -> MessageResponse` | Send a document. **OPERATOR** |+| `send_sticker` | `send_sticker(session_id, body) -> MessageResponse` | Send a sticker. **OPERATOR** |+| `send_location` | `send_location(session_id, body) -> MessageResponse` | Send a location. **OPERATOR** |+| `send_contact` | `send_contact(session_id, body) -> MessageResponse` | Send a contact card. **OPERATOR** |+| `send_template` | `send_template(session_id, body) -> MessageResponse` | Send a stored template. **OPERATOR** |+| `send_poll` | `send_poll(session_id, body) -> MessageResponse` | Send a poll message. **OPERATOR** |+| `reply` | `reply(session_id, body) -> MessageResponse` | Reply to a message. **OPERATOR** |+| `forward` | `forward(session_id, body) -> MessageResponse` | Forward a message. **OPERATOR** |+| `click_button` | `click_button(session_id, body) -> MessageResponse` | Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). **OPERATOR** |+| `react` | `react(session_id, body) -> SuccessResult` | React to a message. **OPERATOR** |+| `delete` | `delete(session_id, body) -> SuccessResult` | Delete a message. **OPERATOR** |+| `edit_message` | `edit_message(session_id, body) -> MessageResponse` | Edit the text of a message already sent. **OPERATOR** |+| `history` | `history(session_id, chat_id, query=None) -> list[ChatHistoryMessage]` | Fetch chat history. |+| `reactions` | `reactions(session_id, chat_id, message_id) -> list[ReactionRecord]` | List reactions on a message. |+| `pin` | `pin(session_id, body) -> SuccessResult` | Pin a message in its chat. `durationSeconds` must be 86400, 604800 or 2592000; in a group only admins may pin. **OPERATOR** |+| `vote_poll` | `vote_poll(session_id, body) -> SuccessResult` | Cast a vote on a poll; `options` are the option texts, not ids. Not supported on Baileys (`501`). **OPERATOR** |+| `star` | `star(session_id, body) -> SuccessResult` | Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. **OPERATOR** |+| `unpin` | `unpin(session_id, body) -> SuccessResult` | Unpin a pinned message. **OPERATOR** |+| `media` | `media(session_id, chat_id, message_id) -> MessageMedia` | Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. `404` when neither holds bytes. |+| `send_bulk` | `send_bulk(session_id, body) -> BulkMessageResponse` | Enqueue a bulk send batch. **OPERATOR** |+| `batch_status` | `batch_status(session_id, batch_id) -> BatchStatusResponse` | Get bulk batch status. |+| `cancel_batch` | `cancel_batch(session_id, batch_id) -> BatchCancelResponse` | Cancel a running batch. **OPERATOR** |#### `client.contacts`@@ -595,7 +595,7 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All| `demote_participants` | `demote_participants(session_id, group_id, participants) -> ParticipantsResult` | Demote from admin. A partial refusal still answers 200, so check `results`. **OPERATOR** || `set_subject` | `set_subject(session_id, group_id, subject) -> SuccessResult` | Set group subject. **OPERATOR** || `set_description` | `set_description(session_id, group_id, description) -> SuccessResult` | Set group description. **OPERATOR** |-| `get_group_settings` | `get_group_settings(session_id, group_id) -> GroupSettings` | Get the group settings (announce / locked / ephemeral timer). |+| `get_group_settings` | `get_group_settings(session_id, group_id) -> GroupSettings` | Get the group settings (announce / locked / ephemeral timer / who may add members). || `update_group_settings` | `update_group_settings(session_id, group_id, body) -> SuccessResult` | Update the group settings (at least one field required). **OPERATOR** || `leave` | `leave(session_id, group_id) -> SuccessResult` | Leave the group. **OPERATOR** || `get_picture` | `get_picture(session_id, group_id) -> dict[str, Any]` | The group's picture URL, or `null` when it has none. |@@ -676,16 +676,16 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All#### `client.status` _(Stories)_-| Method | Signature | Description |-| -------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `list` | `list(session_id) -> dict[str, list[StatusRecord]]` | List all status updates. |-| `from_contact` | `from_contact(session_id, contact_id) -> dict[str, list[StatusRecord]]` | Status updates from one contact. |-| `media` | `media(session_id, status_id) -> StatusMedia` | Fetch the stored media bytes for a status update. |-| `send_text` | `send_text(session_id, body) -> StatusResult` | Post a text status. **OPERATOR** |-| `send_image` | `send_image(session_id, body) -> StatusResult` | Post an image status. **OPERATOR** |-| `send_video` | `send_video(session_id, body) -> StatusResult` | Post a video status. **OPERATOR** |-| `send_voice` | `send_voice(session_id, body) -> StatusResult` | Post an audio status as a voice note. WhatsApp plays one only as Ogg/Opus and neither engine transcodes, so convert with `media.convertVoice` first. **OPERATOR** |-| `delete` | `delete(session_id, status_id) -> None` | Delete a status. **OPERATOR** |+| Method | Signature | Description |+| -------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `list` | `list(session_id) -> dict[str, list[StatusRecord]]` | List all status updates. |+| `from_contact` | `from_contact(session_id, contact_id) -> dict[str, list[StatusRecord]]` | Status updates from one contact. |+| `media` | `media(session_id, status_id) -> StatusMedia` | Fetch the stored media bytes for a status update. |+| `send_text` | `send_text(session_id, body) -> StatusResult` | Post a text status. **OPERATOR** |+| `send_image` | `send_image(session_id, body) -> StatusResult` | Post an image status. **OPERATOR** |+| `send_video` | `send_video(session_id, body) -> StatusResult` | Post a video status. **OPERATOR** |+| `send_voice` | `send_voice(session_id, body) -> StatusResult` | Post an audio status as a voice note. WhatsApp plays one only as Ogg/Opus and neither engine transcodes, so convert with `media.convert_voice` first. **OPERATOR** |+| `delete` | `delete(session_id, status_id) -> None` | Delete a status. **OPERATOR** |#### `client.search`@@ -737,14 +737,14 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All### Error Handling-Every error inherits from `OpenWAError`. A non-2xx response raises an `OpenWAApiError` (or a more specific subclass picked by status); a timeout raises `OpenWATimeoutError`. The API-error classes carry `.status` (HTTP code), `.body` (parsed JSON or raw text), and `.error_kind` (the NestJS `error` field), plus `.code` (the body's `code`), `.retry_after_seconds` (the body's `retryAfterSeconds`, else the `Retry-After` header) and `.headers` (the response headers).+Every error the SDK raises itself inherits from `OpenWAError`. A non-2xx response raises an `OpenWAApiError` (or a more specific subclass picked by status); a timeout raises `OpenWATimeoutError`. A connection failure (refused, reset, DNS, TLS) surfaces as `httpx.TransportError` and an invalid argument as `ValueError`, so a catch-all names those as well. The API-error classes carry `.status` (HTTP code), `.body` (parsed JSON or raw text), and `.error_kind` (the NestJS `error` field), plus `.code` (the body's `code`), `.retry_after_seconds` (the body's `retryAfterSeconds`, else the `Retry-After` header) and `.headers` (the response headers).| Exception | Trigger || ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `OpenWAAuthError` | HTTP `401` — missing or invalid API key || `OpenWAForbiddenError` | HTTP `403` — the key's role or scope (session, IP or chat allow-list) refuses the call, or WhatsApp itself refused the operation (for example, missing group admin rights) || `OpenWANotFoundError` | HTTP `404` — resource not found |-| `OpenWAConflictError` | HTTP `409`: session not ready, or a keyed send pending or unconfirmed |+| `OpenWAConflictError` | HTTP `409`: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see `code`) || `OpenWARateLimitError` | HTTP `429` — too many requests. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `retry_after_seconds` carries its `Retry-After` header. A 429 whose `code` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `retry_after_seconds`, which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (`SEND_PACING_BREAKER_COOLDOWN_MS`, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. || `OpenWANotImplementedError` | HTTP `501` — active engine doesn't support the operation || `OpenWAServiceUnavailableError` | HTTP `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on |@@ -826,7 +826,7 @@ $client = new Client([$session = $client->sessions->create(['name' => 'my-session']);$client->sessions->start($session['id']);-// Link the account before sending: scan sessions->getQrCode or use sessions->requestPairingCode,+// Link the account before sending: scan sessions->getQrCode (or use sessions->requestPairingCode for a number with no linked session),// then wait for status 'ready'. An unlinked session answers the send with 409.$result = $client->messages->sendText($session['id'], ['chatId' => '[email protected]',@@ -862,7 +862,7 @@ Missing `baseUrl` or `apiKey` throws `OpenWA\Exceptions\OpenWAException` from th### Resources & Methods-All payloads are associative arrays; all listed methods are synchronous and return the decoded JSON (an `array`), except the `void` deletes. Methods marked **OPERATOR** require an operator-level API key.+All payloads are associative arrays; all listed methods are synchronous and return the decoded JSON (an `array`), except the `void` deletes. Methods marked **OPERATOR** require an operator-level API key. Some methods are supported by one engine only and answer `501` on the other (a row says so where it matters; section [29.6 of the engine capability matrix](./29-engine-capability-matrix.md#296-the-27-not-available-cells-in-detail) lists them all).#### `sessions`@@ -881,41 +881,41 @@ All payloads are associative arrays; all listed methods are synchronous and retu| `logout` | `logout(string $id): array` | Attempt an engine-native unlink of this device, then stop the session. A `200` means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later `start` needs a fresh QR. A `502` (`SESSION_LOGOUT_INCOMPLETE`) stops locally but leaves the operation incomplete; start and retry. Requires a running session. **OPERATOR** || `forceKill` | `forceKill(string $id): array` | Force-kill a session. A `502` (`SESSION_FORCE_KILL_INCOMPLETE`) stops locally but the engine process may still be running; a retry answers `400`, so restart the node to reap it. **OPERATOR** || `getQrCode` | `getQrCode(string $id): array` | Fetch the current QR code. **OPERATOR** |-| `requestPairingCode` | `requestPairingCode(string $id, array $body): array` | Request a phone-pairing code. **OPERATOR** |+| `requestPairingCode` | `requestPairingCode(string $id, array $body): array` | Request a phone-pairing code. On whatsapp-web.js, not for a number that already has a linked session (WhatsApp can revoke that device); link it by QR instead. **OPERATOR** || `setOnlinePresence` | `setOnlinePresence(string $id, array $body): array` | Set the account's own global presence (appear online or offline). **OPERATOR** || `stats` | `stats(): array` | `GET /api/sessions/stats/overview`. |#### `messages`-| Method | Signature | Description |-| -------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |-| `list` | `list(string $sessionId, array $query = []): array` | List stored messages. |-| `sendText` | `sendText(string $sessionId, array $body): array` | Send a text message (`send-text`). **OPERATOR** |-| `sendImage` | `sendImage(string $sessionId, array $body): array` | Send an image. **OPERATOR** |-| `sendVideo` | `sendVideo(string $sessionId, array $body): array` | Send a video. **OPERATOR** |-| `sendAudio` | `sendAudio(string $sessionId, array $body): array` | Send audio. **OPERATOR** |-| `sendDocument` | `sendDocument(string $sessionId, array $body): array` | Send a document. **OPERATOR** |-| `sendSticker` | `sendSticker(string $sessionId, array $body): array` | Send a sticker. **OPERATOR** |-| `sendLocation` | `sendLocation(string $sessionId, array $body): array` | Send a location. **OPERATOR** |-| `sendContact` | `sendContact(string $sessionId, array $body): array` | Send a contact card. **OPERATOR** |-| `sendTemplate` | `sendTemplate(string $sessionId, array $body): array` | Send a stored template. **OPERATOR** |-| `sendPoll` | `sendPoll(string $sessionId, array $body): array` | Send a native poll (2–12 options). **OPERATOR** |-| `reply` | `reply(string $sessionId, array $body): array` | Reply to a message. **OPERATOR** |-| `forward` | `forward(string $sessionId, array $body): array` | Forward a message. **OPERATOR** |-| `clickButton` | `clickButton(string $sessionId, array $body): array` | Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). **OPERATOR** |-| `react` | `react(string $sessionId, array $body): array` | React to a message. **OPERATOR** |-| `delete` | `delete(string $sessionId, array $body): array` | Delete a message. **OPERATOR** |-| `editMessage` | `editMessage(string $sessionId, array $body): array` | Edit the text of a message already sent (`$body` needs `chatId`, `messageId`, `body`). **OPERATOR** |-| `history` | `history(string $sessionId, string $chatId, array $query = []): array` | Fetch chat history. |-| `reactions` | `reactions(string $sessionId, string $chatId, string $messageId): array` | List reactions on a message. |-| `pin` | `pin(string $sessionId, array $body): array` | Pin a message in its chat. `durationSeconds` must be 86400, 604800 or 2592000; in a group only admins may pin. **OPERATOR** |-| `votePoll` | `votePoll(string $sessionId, array $body): array` | Cast a vote on a poll; `options` are the option texts, not ids. Not supported on Baileys (`501`). **OPERATOR** |-| `star` | `star(string $sessionId, array $body): array` | Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. **OPERATOR** |-| `unpin` | `unpin(string $sessionId, array $body): array` | Unpin a pinned message. **OPERATOR** |-| `media` | `media(string $sessionId, string $chatId, string $messageId): array` | Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. `404` when neither holds bytes. |-| `sendBulk` | `sendBulk(string $sessionId, array $body): array` | Enqueue a bulk send batch. **OPERATOR** |-| `batchStatus` | `batchStatus(string $sessionId, string $batchId): array` | Get bulk batch status. |-| `cancelBatch` | `cancelBatch(string $sessionId, string $batchId): array` | Cancel a bulk batch. **OPERATOR** |+| Method | Signature | Description |+| -------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `list` | `list(string $sessionId, array $query = []): array` | List stored messages; the query takes the same keys as the JavaScript client's `messages.list`, and the response carries `unknownTimestampTotal` under the same conditions. |+| `sendText` | `sendText(string $sessionId, array $body): array` | Send a text message (`send-text`). **OPERATOR** |+| `sendImage` | `sendImage(string $sessionId, array $body): array` | Send an image. **OPERATOR** |+| `sendVideo` | `sendVideo(string $sessionId, array $body): array` | Send a video. **OPERATOR** |+| `sendAudio` | `sendAudio(string $sessionId, array $body): array` | Send audio. **OPERATOR** |+| `sendDocument` | `sendDocument(string $sessionId, array $body): array` | Send a document. **OPERATOR** |+| `sendSticker` | `sendSticker(string $sessionId, array $body): array` | Send a sticker. **OPERATOR** |+| `sendLocation` | `sendLocation(string $sessionId, array $body): array` | Send a location. **OPERATOR** |+| `sendContact` | `sendContact(string $sessionId, array $body): array` | Send a contact card. **OPERATOR** |+| `sendTemplate` | `sendTemplate(string $sessionId, array $body): array` | Send a stored template. **OPERATOR** |+| `sendPoll` | `sendPoll(string $sessionId, array $body): array` | Send a native poll (2–12 options). **OPERATOR** |+| `reply` | `reply(string $sessionId, array $body): array` | Reply to a message. **OPERATOR** |+| `forward` | `forward(string $sessionId, array $body): array` | Forward a message. **OPERATOR** |+| `clickButton` | `clickButton(string $sessionId, array $body): array` | Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). **OPERATOR** |+| `react` | `react(string $sessionId, array $body): array` | React to a message. **OPERATOR** |+| `delete` | `delete(string $sessionId, array $body): array` | Delete a message. **OPERATOR** |+| `editMessage` | `editMessage(string $sessionId, array $body): array` | Edit the text of a message already sent (`$body` needs `chatId`, `messageId`, `body`). **OPERATOR** |+| `history` | `history(string $sessionId, string $chatId, array $query = []): array` | Fetch chat history. |+| `reactions` | `reactions(string $sessionId, string $chatId, string $messageId): array` | List reactions on a message. |+| `pin` | `pin(string $sessionId, array $body): array` | Pin a message in its chat. `durationSeconds` must be 86400, 604800 or 2592000; in a group only admins may pin. **OPERATOR** |+| `votePoll` | `votePoll(string $sessionId, array $body): array` | Cast a vote on a poll; `options` are the option texts, not ids. Not supported on Baileys (`501`). **OPERATOR** |+| `star` | `star(string $sessionId, array $body): array` | Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. **OPERATOR** |+| `unpin` | `unpin(string $sessionId, array $body): array` | Unpin a pinned message. **OPERATOR** |+| `media` | `media(string $sessionId, string $chatId, string $messageId): array` | Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. `404` when neither holds bytes. |+| `sendBulk` | `sendBulk(string $sessionId, array $body): array` | Enqueue a bulk send batch. **OPERATOR** |+| `batchStatus` | `batchStatus(string $sessionId, string $batchId): array` | Get bulk batch status. |+| `cancelBatch` | `cancelBatch(string $sessionId, string $batchId): array` | Cancel a bulk batch. **OPERATOR** |#### `contacts`@@ -949,7 +949,7 @@ All payloads are associative arrays; all listed methods are synchronous and retu| `setSubject` | `setSubject(string $sessionId, string $groupId, string $subject): array` | Update the group subject. **OPERATOR** || `setDescription` | `setDescription(string $sessionId, string $groupId, string $description): array` | Update the group description. **OPERATOR** || `getGroupSettings` | `getGroupSettings(string $sessionId, string $groupId): array` | Get the group settings (only the ones the active engine supports are present). |-| `updateGroupSettings` | `updateGroupSettings(string $sessionId, string $groupId, array $settings): array` | Update the group settings (at least one of `announce`, `locked`, `ephemeralSeconds`). **OPERATOR** |+| `updateGroupSettings` | `updateGroupSettings(string $sessionId, string $groupId, array $settings): array` | Update the group settings (at least one of `announce`, `locked`, `ephemeralSeconds`, `memberAddMode`). **OPERATOR** || `leave` | `leave(string $sessionId, string $groupId): array` | Leave the group. **OPERATOR** || `getPicture` | `getPicture(string $sessionId, string $groupId): array` | The group's picture URL, or `null` when it has none. || `setPicture` | `setPicture(string $sessionId, string $groupId, array $body): array` | Set the group's picture. **OPERATOR** |@@ -1090,16 +1090,16 @@ All payloads are associative arrays; all listed methods are synchronous and retu### Error Handling-All exceptions live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).+All exceptions the SDK raises itself live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). A connection failure surfaces as Guzzle's `ConnectException` and an invalid argument as `InvalidArgumentException`, so a catch-all names those as well. Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).| Exception | Extends | Trigger || ----------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `OpenWAException` | `\Exception` | Base for all SDK errors (also thrown for missing `baseUrl`/`apiKey`). |+| `OpenWAException` | `\Exception` | Base for the SDK's own errors (also thrown for missing `baseUrl`/`apiKey`); a transport failure other than a timeout is Guzzle's own. || `OpenWAApiException` | `OpenWAException` | Any non-2xx (including unfollowed 3xx and other 4xx/5xx). || `OpenWAAuthException` | `OpenWAApiException` | `401` — missing/invalid API key. || `OpenWAForbiddenException` | `OpenWAApiException` | `403` — the key's role or scope refuses the call (e.g. operator-only endpoint, or a session, IP or chat outside its allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). || `OpenWANotFoundException` | `OpenWAApiException` | `404` — resource not found. |-| `OpenWAConflictException` | `OpenWAApiException` | `409`: session not ready, or a keyed send pending or unconfirmed. |+| `OpenWAConflictException` | `OpenWAApiException` | `409`: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see `code`). || `OpenWARateLimitException` | `OpenWAApiException` | `429` — rate limited. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `getRetryAfterSeconds()` carries its `Retry-After` header. A 429 whose `getErrorCode()` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `getRetryAfterSeconds()`, which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (`SEND_PACING_BREAKER_COOLDOWN_MS`, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. || `OpenWANotImplementedException` | `OpenWAApiException` | `501` — active engine does not support the operation. || `OpenWAServiceUnavailableException` | `OpenWAApiException` | `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |@@ -1173,7 +1173,7 @@ The wire types live in a dedicated module (`types.ts` / `types.py`) so they can**Requests.** Each SDK's test suite mocks the HTTP transport and **asserts on the exact request path, method, and body** — so a drift between an SDK method and the real API (the class of bug that once shipped `messages/text` instead of the real `messages/send-text`) breaks a test rather than reaching users.-**Responses.** That is a different problem, and for a long time nothing covered it — #754 is the proof: the status, label, and channel record types drifted from the engine interface for releases without a single test noticing, because asserting the request says nothing about the reply. It is not covered by `openapi:check` either: those controllers declare no typed `@ApiResponse`, so `openapi.json` carries no response schema for them and there is nothing to diff. The gate is now `sdk/javascript/test/wire-contract.test-d.ts` — a type-level test where `tsc --noEmit` (run by `npm test` ahead of vitest) fails if a record type stops matching the engine-neutral shape as it arrives over JSON. Its `Wire*` types are **maintained by hand**: `sdk-ci.yml` re-runs the job when `whatsapp-engine.interface.ts` changes, but keeping the two in step is a human step, not a generated one.+**Responses.** That is a different problem, and for a long time nothing covered it — #754 is the proof: the status, label, and channel record types drifted from the engine interface for releases without a single test noticing, because asserting the request says nothing about the reply. `openapi:check` does not cover it either: the schemas of those records (`LabelDto`, `ChannelDto`, `ChannelMessageDto`, `StatusDto` and `StatusListResponseDto`) are in `openapi.json`, but `check:contract-shapes` does not yet map the SDKs' label, channel and status records to them. The gate is now `sdk/javascript/test/wire-contract.test-d.ts` — a type-level test where `tsc --noEmit` (run by `npm test` ahead of vitest) fails if a record type stops matching the engine-neutral shape as it arrives over JSON. Its `Wire*` types are **maintained by hand**: `sdk-ci.yml` re-runs the job when `whatsapp-engine.interface.ts` changes, but keeping the two in step is a human step, not a generated one.### Release processdiff --git a/sdk/README.md b/sdk/README.mdindex c3662a2c8..9efa066b9 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -274,8 +274,10 @@ testing, retry, tracing, or metrics. See [`go/README.md`](go/README.md).`WebhookDelivery`.- **Redirects are never followed.** A `3xx` surfaces to the caller rather thanbeing followed, so the API key is never re-sent to a redirect target.-- **Default timeout** is 30s (configurable; `0` turns it off). The JavaScript and PHP- clients bound the whole call. The Python client's is per network operation+- **Default timeout** is 30s (configurable). `0` turns it off in the JavaScript,+ Python and PHP clients; the Go client reads `0` as the 30s default and the Java+ builder refuses it. The JavaScript, PHP, Go and Java clients bound the whole call,+ response body included. The Python client's is per network operation(connect, read, write, pool), so a response that keeps trickling bytes is notcut off. Path segments (chat / message ids) are percent-encoded; a base-URL pathprefix (e.g. behind a proxy at `/v1`) is preserved.diff --git a/sdk/go/README.md b/sdk/go/README.mdindex fe985623c..5da3edb6c 100644--- a/sdk/go/README.md+++ b/sdk/go/README.md@@ -44,7 +44,7 @@ func main() {log.Fatal(err)}- // Link the account before sending: scan Sessions.QRCode or use Sessions.RequestPairingCode,+ // Link the account before sending: scan Sessions.QRCode (or use Sessions.RequestPairingCode for a number with no linked session),// then wait for status "ready". An unlinked session answers the send with 409.res, err := client.Messages.SendText(ctx, session.ID, openwa.SendTextRequest{ChatID: "[email protected]",@@ -281,7 +281,7 @@ Cutting a release:The example below requires the unreleased SDK changes on `main`; SDK 0.5.1 does not expose this per-send key argument. The server must also include the send idempotency changes after OpenWA 0.24.0.-Supply a unique caller-owned key for one logical send and reuse it when retrying that same call. Keys contain 1-255 visible ASCII characters; unrelated calls must use different keys. The SDK forwards the key without changing its retry policy or generating one automatically.+Supply a unique caller-owned key for one logical send and reuse it when retrying that same call. Keys contain 1-255 visible ASCII characters; unrelated calls must use different keys. The SDK forwards the key without changing its retry policy or generating one automatically. On the twelve routes below `net/http` may still send a keyed request once more after a dropped keep-alive connection; the gateway deduplicates it, so the call returns the first answer or a `409` `IDEMPOTENCY_KEY_IN_PROGRESS` to retry later with the same key.```goctx := openwa.WithIdempotencyKey(context.Background(), "order-123")diff --git a/sdk/java/README.md b/sdk/java/README.mdindex 03f5e52de..663769f9a 100644--- a/sdk/java/README.md+++ b/sdk/java/README.md@@ -45,7 +45,7 @@ OpenWAClient client = new OpenWAClient("http://localhost:2785", "owa_k1_…");SessionResponse session = client.sessions.create(CreateSessionRequest.builder().name("my-session").build());client.sessions.start(session.id());-// Link the account before sending: scan sessions.getQrCode or use sessions.requestPairingCode,+// Link the account before sending: scan sessions.getQrCode (or use sessions.requestPairingCode for a number with no linked session),// then wait for status READY. An unlinked session answers the send with 409.MessageResponse result = client.messages.sendText(session.id(),SendTextRequest.builder()diff --git a/sdk/javascript/README.md b/sdk/javascript/README.mdindex fc19a65fe..b1bc9bd6a 100644--- a/sdk/javascript/README.md+++ b/sdk/javascript/README.md@@ -29,7 +29,7 @@ const client = new OpenWAClient({const session = await client.sessions.create({ name: 'my-session' });await client.sessions.start(session.id);-// Link the account before sending: scan sessions.getQrCode or use sessions.requestPairingCode,+// Link the account before sending: scan sessions.getQrCode (or use sessions.requestPairingCode for a number with no linked session),// then wait for status 'ready'. An unlinked session answers the send with 409.const result = await client.messages.sendText(session.id, {chatId: '[email protected]',diff --git a/sdk/php/README.md b/sdk/php/README.mdindex 61d04b65e..408665630 100644--- a/sdk/php/README.md+++ b/sdk/php/README.md@@ -32,7 +32,7 @@ $client = new Client([$session = $client->sessions->create(['name' => 'my-session']);$client->sessions->start($session['id']);-// Link the account before sending: scan sessions->getQrCode or use sessions->requestPairingCode,+// Link the account before sending: scan sessions->getQrCode (or use sessions->requestPairingCode for a number with no linked session),// then wait for status 'ready'. An unlinked session answers the send with 409.$result = $client->messages->sendText($session['id'], ['chatId' => '[email protected]',diff --git a/sdk/python/README.md b/sdk/python/README.mdindex 9a6080359..d2fd25192 100644--- a/sdk/python/README.md+++ b/sdk/python/README.md@@ -29,7 +29,7 @@ client = OpenWAClient(session = client.sessions.create({"name": "my-session"})client.sessions.start(session["id"])-# Link the account before sending: scan sessions.get_qr_code or use sessions.request_pairing_code,+# Link the account before sending: scan sessions.get_qr_code (or use sessions.request_pairing_code for a number with no linked session),# then wait for status "ready". An unlinked session answers the send with 409.result = client.messages.send_text(session["id"], {"chatId": "[email protected]",