Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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 process
diff --git a/sdk/README.md b/sdk/README.md
index 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 than
being 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 not
cut off. Path segments (chat / message ids) are percent-encoded; a base-URL path
prefix (e.g. behind a proxy at `/v1`) is preserved.
diff --git a/sdk/go/README.md b/sdk/go/README.md
index 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.
```go
ctx := openwa.WithIdempotencyKey(context.Background(), "order-123")
diff --git a/sdk/java/README.md b/sdk/java/README.md
index 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.md
index 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.md
index 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.md
index 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]",