Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: use plain punctuation in the text added since 0.23.5

Yudhi Armyndharis0fb9b1d565f1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 46b5e12b3..eacf162ef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,10 +10,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- Baileys inbound button, template quick-reply, list-row and native-flow replies arrive as `type: "text"` with a structured `button { id, text? }` on `message.received` (whatsapp-web.js still has no interactive reply fields). The REST chat-history route is whatsapp-web.js only and does not carry these fields. Thanks @gabrielmmoraes1999.
-- Baileys inbound business prompts that offer clickable buttons (or list rows) also carry `buttons: [{ id, text }, …]` on `message.received` (URL/call CTAs are omitted — they cannot be clicked), so choices like Sim/Não are no longer flattened away into `body` only. Thanks @gabrielmmoraes1999.
+- Baileys inbound business prompts that offer clickable buttons (or list rows) also carry `buttons: [{ id, text }, …]` on `message.received` (URL/call CTAs are omitted, since they cannot be clicked), so choices like Sim/Não are no longer flattened away into `body` only. Thanks @gabrielmmoraes1999.
- `POST /api/sessions/:sessionId/messages/click-button` sends a structured button/list reply against a stored WhatsApp Business prompt on Baileys (whatsapp-web.js returns `501`). Classic `buttonsMessage` / `templateMessage` / `listMessage` prompts are supported; native-flow `interactiveMessage` replies are unverified. Thanks @gabrielmmoraes1999.
- The dashboard Chats thread shows a quote preview and call detail on history-loaded messages, which previously rendered on live messages only. Thanks @gabrielmmoraes1999.
-- The dashboard Chats thread renders inbound Baileys prompt `buttons` and taps them through `POST .../messages/click-button`; prompt choices are also kept in persisted message `metadata` so they survive reload for rendering. Clicking still requires the prompt to be in the engine store — an evicted prompt 404s. Thanks @gabrielmmoraes1999.
+- The dashboard Chats thread renders inbound Baileys prompt `buttons` and taps them through `POST .../messages/click-button`; prompt choices are also kept in persisted message `metadata` so they survive reload for rendering. Clicking still requires the prompt to be in the engine store, so an evicted prompt 404s. Thanks @gabrielmmoraes1999.
- Webhook and automation filters accept a `chatId` condition, so a webhook can be scoped to specific groups or chats instead of only to a sender ([#1634](https://github.com/rmyndharis/OpenWA/issues/1634)). Thanks @krishshah9944 and @bhavyachopra99.
- The dashboard Templates list has a delete button on each row, so a template can be deleted without opening it in the editor first. Like the editor's delete button, it shows only for keys that can write templates. Thanks @C24212.
- On the dashboard Chats page, Escape closes the open chat, channel or status viewer and returns to the list. It leaves the key alone while a dialog, a menu or the media viewer is open, since those handle Escape themselves. Thanks @C24212.
diff --git a/dashboard/src/components/chats/ChatThread.tsx b/dashboard/src/components/chats/ChatThread.tsx
index bf864fd8d..456fa3355 100644
--- a/dashboard/src/components/chats/ChatThread.tsx
+++ b/dashboard/src/components/chats/ChatThread.tsx
@@ -414,7 +414,7 @@ function ChatThread({
msg.type !== 'call' && <MessageBody text={msg.body} className="message-text" />
)}
- {/* Inbound business prompt choices — tap calls POST .../messages/click-button. */}
+ {/* Inbound business prompt choices; a tap calls POST .../messages/click-button. */}
{!isMe && !isRevoked && !isMasked && (msg.metadata?.buttons?.length ?? 0) > 0 && (
<div className="message-prompt-buttons" role="group" aria-label={t('chats.promptButtons')}>
{msg.metadata!.buttons!.map((btn, idx) => {
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 5e302ae17..f1865439f 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -325,7 +325,7 @@ and therefore apply on the next start, leaving a reconnect sequence already in f
| Field | Type | Constraints | Description |
| ---------------------- | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `autoRejectCalls` | boolean | — | Auto-reject every incoming call as soon as it rings (Baileys only) |
+| `autoRejectCalls` | boolean | none | Auto-reject every incoming call as soon as it rings (Baileys only) |
| `maxReconnectAttempts` | number | integer, 0–20 | Reconnect attempt cap (`0` disables reconnect; `null` = unlimited). Bounds the gateway's own reconnect: every reconnect on whatsapp-web.js, and on Baileys only the one after a logged-out close |
| `reconnectBaseDelay` | number | integer, 1000–300000 (ms) | Base delay of the reconnect backoff, on the same engine scope |
@@ -2036,7 +2036,7 @@ The quoted body is best-effort resolved from the DB for the reply preview.
Tap a choice on a WhatsApp Business button / list prompt by sending the structured reply proto WhatsApp expects.
-**Auth:** API key (OPERATOR) · **Engines:** Baileys only — whatsapp-web.js returns `501`
+**Auth:** API key (OPERATOR) · **Engines:** Baileys only; whatsapp-web.js returns `501`
**Path parameters**
@@ -2044,7 +2044,7 @@ Tap a choice on a WhatsApp Business button / list prompt by sending the structur
| --------- | ------ | ----------- |
| sessionId | string | Session ID |
-**Request body** — `ClickButtonDto`
+**Request body**: `ClickButtonDto`
| Field | Type | Required | Constraints | Description |
| --------- | ------ | -------- | ------------------- | ---------------------------------------------------------------------------- |
@@ -2071,7 +2071,7 @@ Tap a choice on a WhatsApp Business button / list prompt by sending the structur
> reject or treat any of these differently from a phone tap. The prompt must already be in the
> Baileys message store (received while the session was live); persisted `metadata.buttons` can still
> render after the store evicts the prompt, and a tap then 404s. URL/call CTA buttons cannot be
-> clicked this way — only quick-reply style choices and list rows.
+> clicked this way, only quick-reply style choices and list rows.
**Errors:** `400` validation failure, session not active, the message is not a clickable prompt, or `buttonId` is not among its choices · `401` · `403` · `404` prompt not in the engine store / wrong chat · `501` whatsapp-web.js · `409` conflict or engine not ready (retryable) · `500` engine error
@@ -4586,14 +4586,14 @@ Create a webhook for the session.
**Request body** — `CreateWebhookDto`
-| Field | Type | Required | Constraints | Description |
-| ---------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| url | string | yes | `@IsUrl({ require_tld: false })` (allows hostnames without a dot, e.g. `http://localhost:3000`); also run through the SSRF guard, which can reject with `400`. Entity column max 2048 chars. | Webhook URL to receive events. |
-| events | string[] | no | `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Event names to subscribe to (see allowed set above). Defaults to `["message.received"]` when omitted. |
-| secret | string | no | `@IsString`, `@MinLength(16)`, `@MaxLength(255)` | HMAC-SHA256 signing key. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). Used for `X-OpenWA-Signature`. Defaults to `null`. |
-| headers | Record<string,string> | no | `@IsHeaderMap()` — flat object (not array), ≤50 entries, names match `/^[A-Za-z0-9-]+$/`, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard). | Custom headers added to deliveries. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). At delivery, `content-type` and `x-openwa-*` names are stripped. Defaults to `{}`. |
-| filters | WebhookFilters \| null | no | `@IsValidWebhookFilters()` — `{ conditions: [...] }`; each condition `{ field, operator('is'\|'isNot'\|'contains'\|'equals'), value(string\|string[]\|boolean), caseSensitive?:boolean }`; bounds: max 20 conditions, 100 values/condition, 1000-char text values. Message fields: `sender`, `recipient`, `chatId`, `body`, `type`, `isGroup`, `kind`, `fromMe`, `hasMedia`, `mentions`. An id-valued condition accepts a bare phone number, but a group must be written as its full `<id>@g.us` JID: bare digits canonicalise to `@c.us` and match no group. | Optional AND pre-filter; **all** conditions must match for the webhook to fire. Omit/null = fire on every subscribed event. Defaults to `null`. ⚠️ A condition whose field is DEFINED for the event family but absent from that event's payload cannot match, so it suppresses the event entirely (a field with no definition for the family is skipped instead, and does not suppress) — `message.ack`/`message.failed` carry `{ id, messageId, status, ack }` and `message.reaction` carries `{ messageId, chatId, reaction, senderId }`, none of which has a sender or body, so a `sender` filter silently drops all three. Scope the subscription with `events[]` rather than relying on a filter to be inert. Set `LOG_LEVEL=debug` to see each suppression and the payload fields that were available. |
-| retryCount | number (int) | no | `@IsInt`, `@Min(0)`, `@Max(5)` | Delivery retry attempts on failure. Defaults to `3`. |
+| Field | Type | Required | Constraints | Description |
+| ---------- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| url | string | yes | `@IsUrl({ require_tld: false })` (allows hostnames without a dot, e.g. `http://localhost:3000`); also run through the SSRF guard, which can reject with `400`. Entity column max 2048 chars. | Webhook URL to receive events. |
+| events | string[] | no | `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Event names to subscribe to (see allowed set above). Defaults to `["message.received"]` when omitted. |
+| secret | string | no | `@IsString`, `@MinLength(16)`, `@MaxLength(255)` | HMAC-SHA256 signing key. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). Used for `X-OpenWA-Signature`. Defaults to `null`. |
+| headers | Record<string,string> | no | `@IsHeaderMap()` — flat object (not array), ≤50 entries, names match `/^[A-Za-z0-9-]+$/`, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard). | Custom headers added to deliveries. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). At delivery, `content-type` and `x-openwa-*` names are stripped. Defaults to `{}`. |
+| filters | WebhookFilters \| null | no | `@IsValidWebhookFilters()`, i.e. `{ conditions: [...] }`; each condition `{ field, operator('is'\|'isNot'\|'contains'\|'equals'), value(string\|string[]\|boolean), caseSensitive?:boolean }`; bounds: max 20 conditions, 100 values/condition, 1000-char text values. Message fields: `sender`, `recipient`, `chatId`, `body`, `type`, `isGroup`, `kind`, `fromMe`, `hasMedia`, `mentions`. An id-valued condition accepts a bare phone number, but a group must be written as its full `<id>@g.us` JID: bare digits canonicalise to `@c.us` and match no group. | Optional AND pre-filter; **all** conditions must match for the webhook to fire. Omit/null = fire on every subscribed event. Defaults to `null`. ⚠️ A condition whose field is DEFINED for the event family but absent from that event's payload cannot match, so it suppresses the event entirely (a field with no definition for the family is skipped instead, and does not suppress). `message.ack`/`message.failed` carry `{ id, messageId, status, ack }` and `message.reaction` carries `{ messageId, chatId, reaction, senderId }`, none of which has a sender or body, so a `sender` filter silently drops all three. Scope the subscription with `events[]` rather than relying on a filter to be inert. Set `LOG_LEVEL=debug` to see each suppression and the payload fields that were available. |
+| retryCount | number (int) | no | `@IsInt`, `@Min(0)`, `@Max(5)` | Delivery retry attempts on failure. Defaults to `3`. |
```json
{
@@ -6397,7 +6397,7 @@ Generate a shareable WhatsApp call link.
#### POST /api/sessions/:sessionId/calls/:callId/reject
-Reject a currently ringing incoming call. **Baileys only**: the whatsapp-web.js engine answers `501`. Only a live call can be rejected — the id is valid while the call rings (a short server-side cache); afterwards it expires.
+Reject a currently ringing incoming call. **Baileys only**: the whatsapp-web.js engine answers `501`. Only a live call can be rejected: the id is valid while the call rings (a short server-side cache); afterwards it expires.
**Auth:** API key (OPERATOR)
@@ -6414,7 +6414,7 @@ Reject a currently ringing incoming call. **Baileys only**: the whatsapp-web.js
**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role · `404` call not found or no longer ringing · `409` conflict or engine not ready (retryable) · `501` the whatsapp-web.js engine cannot reject a call · `503` session not ready or dependency unavailable (retryable)
-> **Auto-reject per session.** Set `"config": { "autoRejectCalls": true }` when creating a session to have the server reject every incoming call automatically — the `call.received` event is still dispatched first, so automations keep full visibility. Baileys only; see the note at the top of this section.
+> **Auto-reject per session.** Set `"config": { "autoRejectCalls": true }` when creating a session to have the server reject every incoming call automatically, and the `call.received` event is still dispatched first, so automations keep full visibility. Baileys only; see the note at the top of this section.
### 6.4.15 Media conversion (opt-in)
@@ -6539,7 +6539,7 @@ Create a rule. **Auth:** API key (OPERATOR)
}
```
-`400` — invalid conditions (unknown field/operator, over-limit values) or over-limit text. `404` when no session has this id.
+`400`: invalid conditions (unknown field/operator, over-limit values) or over-limit text. `404` when no session has this id.
#### GET /api/sessions/:sessionId/automation-rules
@@ -6902,29 +6902,29 @@ Every registered webhook receives an HTTP `POST` with a JSON body of this shape:
These are the events OpenWA actually emits. A webhook is registered with an `events` list; an event is delivered to a webhook when its `events` array includes the event name or `"*"`.
-| Event | When it fires | `data` payload sketch |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `message.received` | An inbound message arrives | The full message object: `id`, `from`, `to`, `body`, `type`, `timestamp` (epoch **seconds**), `isGroup`, `kind` (user-facing chat discriminator of `chatId` — `individual\|group\|channel\|status\|broadcast\|unknown`), `hasMedia`, `contact{…}` (plus optional `senderPhone` for `@lid` senders, `order{orderId,token?}` / `product{productId,…}` on `order` / `product` messages, `buttons:[{id,text}]` on a WhatsApp Business prompt that offers choices, and `button{id,text?}` when the sender tapped one — **Baileys only**) |
-| `message.sent` | An outbound message is created/sent from this session | Same message object shape as `message.received` |
-| `message.ack` | A delivery/read receipt updates an outbound message | `{ id, messageId, status, ack }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it |
-| `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1 }` |
-| `message.revoked` | A message is deleted/recalled | `{ id, revokedId?, chatId, from, to, type: "revoked", body: "", timestamp }` — **reconcile on `revokedId`** (the original deleted message's id), falling back to `id`. On whatsapp-web.js `id` is the _revocation notification_ (a distinct message that won't match a stored id) and `revokedId` may be absent when the original isn't cached locally; on Baileys the two coincide |
-| `message.reaction` | A reaction is added, changed, or removed | `{ messageId, chatId, reaction, senderId, reactions? }` — `reactions` is the post-apply `{ senderId: emoji }` snapshot, omitted when the gateway holds no stored copy of the message to compute it from (an ephemeral message, or one predating the session going live); treat it as unknown rather than empty and keep the map you already hold. `reaction` is empty when removed |
-| `message.edited` | A message body or media caption is edited | `{ messageId, chatId, body, senderId, from, to, fromMe, isGroup, type, hasMedia, author?, mentionedIds?, timestamp }` — `messageId` is the original message id, `body` is the latest text/caption, and `timestamp` is the edit occurrence time in epoch **seconds** (not the original creation time) |
-| `session.qr` | A new pairing QR is generated | `{ sessionId, qr }` — `qr` is a **PNG data URL** (`data:image/png;base64,…`), the same rendered value `GET /api/sessions/{sessionId}/qr` returns as `qrCode`, not the raw `2@…` linking ref. Render it directly in an `<img src>`; the raw ref never leaves the engine adapter |
-| `session.authenticated` | The session pairs and becomes ready | `{ sessionId, phone, pushName }` |
-| `session.disconnected` | The session disconnects on the engine or WhatsApp side (drop, conflict, or a phone-initiated unlink). Not fired for API-initiated stop/logout/delete — those are acknowledged by the API response and the `session.status` transition | `{ sessionId, reason }` |
-| `session.reconnect_loop` | Every 5th consecutive reconnect attempt is scheduled (attempt 5, 10, 15, …) — the session is failing to come back up | `{ sessionId, attempts, nextDelayMs }` |
-| `presence.update` | A subscribed chat's presence changed — someone came online, started typing, or stopped. Only actual CHANGES are dispatched: WhatsApp repeats itself freely, and every repeat would otherwise be a delivery | `{ sessionId, chatId, participants: [{ id, state, lastSeen? }], groupOnlineCount? }` — `state` is `available`/`unavailable`/`composing`/`recording`/`paused`; `lastSeen` is epoch **seconds** and absent when the contact hides it. Requires `POST .../presence/subscribe` first, and Baileys — whatsapp-web.js cannot observe presence |
-| `session.restriction` | WhatsApp places a restriction on the account, or lifts one. Deduped: an unchanged restriction is not re-announced, and a lift is only sent when one was in force | `{ sessionId, active, kind, code, expiresAt }` — `active` is `false` for a lift and `kind`/`code` then describe the restriction that ended; `expiresAt` is an ISO timestamp or `null`. See `restriction` on the session response for the `kind` values |
-| `session.status` | The session status transitions | `{ sessionId, status }` where `status` is one of `created` / `initializing` / `qr_ready` / `authenticating` / `ready` / `disconnected` / `action_required` / `failed` |
-| `group.join` | Participant(s) are added to or join a group this session is in | `{ groupId, actorId?, participantIds, timestamp }` — `actorId` is the admin/inviter when known. **Baileys**: a session added to or joining a group reports only its own id in `participantIds` (members added with it are not listed) |
-| `group.leave` | Participant(s) leave or are removed from a group | `{ groupId, actorId?, participantIds, timestamp }` |
-| `group.update` | Group metadata changes (subject, description, announce/locked settings) | `{ groupId, actorId?, participantIds, changes?, timestamp }` — `changes` carries only the fields that changed: `subject?`, `description?`, `announce?`, `locked?` |
-| `group.join_request` | Someone asked to join a group this session administers (join-approval mode on) | `{ groupId, actorId?, participantIds, timestamp }` — `participantIds` are the users asking to join; `actorId` is who created the request when the engine reports one (differs from the requester on a non-admin add). Act on it via `GET/POST .../groups/:groupId/membership-requests[...]` **Baileys caveat**: the library (7.0.0-rc13) emits this only for non-admin-add requests — an invite-link self-request may produce no event there (upstream TODO); the membership-requests list endpoint still reports it. |
-| `call.received` | An incoming voice/video call starts ringing. Dispatched by both engines, but **not reliable on whatsapp-web.js**: it fired in a live test on 2026-09-17 and did not in one on 2026-08-10 | `{ callId, from, isVideo, isGroup, timestamp }` — `callId` is the id to pass to `POST /sessions/:sessionId/calls/:callId/reject` (Baileys only). `from` may be an `@lid` privacy id on either engine; resolve it with `GET /api/sessions/:sessionId/contacts/:contactId/phone` |
-| `call.accepted` / `call.rejected` / `call.missed` | A ringing call ended — answered, declined, or never picked up. **Baileys only**: whatsapp-web.js emits no call-outcome event | `{ sessionId, callId, from, outcome, isVideo, isGroup, timestamp }` — `callId` matches the `call.received` that preceded it, so the pair can be correlated. The engines report _what_ happened, never _who_ did it: an accept can come from any linked device. An outcome is only sent for a call this session saw ring, and offline-replayed signalling for calls that ended while disconnected is dropped. WhatsApp's `terminate` is deliberately unmapped — it covers both a caller hanging up before answer and either side ending an answered call, with nothing to tell them apart |
-| `status.received` | A contact posts a status/story (opt-in — see below) | `{ sessionId, statusId, contact: { id, name?, pushName? }, type, caption?, hasMedia, mediaOmitted, omitReason?, postedAt, expiresAt }` — `statusId` is the store's `id` (usable with the status endpoints below); `postedAt`/`expiresAt` are epoch **milliseconds** (unlike the epoch-seconds convention for message timestamps), matching the `GET /status` store's own `Date`-backed fields |
+| Event | When it fires | `data` payload sketch |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message.received` | An inbound message arrives | The full message object: `id`, `from`, `to`, `body`, `type`, `timestamp` (epoch **seconds**), `isGroup`, `kind` (user-facing chat discriminator of `chatId` — `individual\|group\|channel\|status\|broadcast\|unknown`), `hasMedia`, `contact{…}` (plus optional `senderPhone` for `@lid` senders, `order{orderId,token?}` / `product{productId,…}` on `order` / `product` messages, `buttons:[{id,text}]` on a WhatsApp Business prompt that offers choices, and `button{id,text?}` when the sender tapped one — **Baileys only**) |
+| `message.sent` | An outbound message is created/sent from this session | Same message object shape as `message.received` |
+| `message.ack` | A delivery/read receipt updates an outbound message | `{ id, messageId, status, ack }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it |
+| `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1 }` |
+| `message.revoked` | A message is deleted/recalled | `{ id, revokedId?, chatId, from, to, type: "revoked", body: "", timestamp }` — **reconcile on `revokedId`** (the original deleted message's id), falling back to `id`. On whatsapp-web.js `id` is the _revocation notification_ (a distinct message that won't match a stored id) and `revokedId` may be absent when the original isn't cached locally; on Baileys the two coincide |
+| `message.reaction` | A reaction is added, changed, or removed | `{ messageId, chatId, reaction, senderId, reactions? }` — `reactions` is the post-apply `{ senderId: emoji }` snapshot, omitted when the gateway holds no stored copy of the message to compute it from (an ephemeral message, or one predating the session going live); treat it as unknown rather than empty and keep the map you already hold. `reaction` is empty when removed |
+| `message.edited` | A message body or media caption is edited | `{ messageId, chatId, body, senderId, from, to, fromMe, isGroup, type, hasMedia, author?, mentionedIds?, timestamp }` — `messageId` is the original message id, `body` is the latest text/caption, and `timestamp` is the edit occurrence time in epoch **seconds** (not the original creation time) |
+| `session.qr` | A new pairing QR is generated | `{ sessionId, qr }` — `qr` is a **PNG data URL** (`data:image/png;base64,…`), the same rendered value `GET /api/sessions/{sessionId}/qr` returns as `qrCode`, not the raw `2@…` linking ref. Render it directly in an `<img src>`; the raw ref never leaves the engine adapter |
+| `session.authenticated` | The session pairs and becomes ready | `{ sessionId, phone, pushName }` |
+| `session.disconnected` | The session disconnects on the engine or WhatsApp side (drop, conflict, or a phone-initiated unlink). Not fired for API-initiated stop/logout/delete — those are acknowledged by the API response and the `session.status` transition | `{ sessionId, reason }` |
+| `session.reconnect_loop` | Every 5th consecutive reconnect attempt is scheduled (attempt 5, 10, 15, …) — the session is failing to come back up | `{ sessionId, attempts, nextDelayMs }` |
+| `presence.update` | A subscribed chat's presence changed — someone came online, started typing, or stopped. Only actual CHANGES are dispatched: WhatsApp repeats itself freely, and every repeat would otherwise be a delivery | `{ sessionId, chatId, participants: [{ id, state, lastSeen? }], groupOnlineCount? }` — `state` is `available`/`unavailable`/`composing`/`recording`/`paused`; `lastSeen` is epoch **seconds** and absent when the contact hides it. Requires `POST .../presence/subscribe` first, and Baileys — whatsapp-web.js cannot observe presence |
+| `session.restriction` | WhatsApp places a restriction on the account, or lifts one. Deduped: an unchanged restriction is not re-announced, and a lift is only sent when one was in force | `{ sessionId, active, kind, code, expiresAt }` — `active` is `false` for a lift and `kind`/`code` then describe the restriction that ended; `expiresAt` is an ISO timestamp or `null`. See `restriction` on the session response for the `kind` values |
+| `session.status` | The session status transitions | `{ sessionId, status }` where `status` is one of `created` / `initializing` / `qr_ready` / `authenticating` / `ready` / `disconnected` / `action_required` / `failed` |
+| `group.join` | Participant(s) are added to or join a group this session is in | `{ groupId, actorId?, participantIds, timestamp }` — `actorId` is the admin/inviter when known. **Baileys**: a session added to or joining a group reports only its own id in `participantIds` (members added with it are not listed) |
+| `group.leave` | Participant(s) leave or are removed from a group | `{ groupId, actorId?, participantIds, timestamp }` |
+| `group.update` | Group metadata changes (subject, description, announce/locked settings) | `{ groupId, actorId?, participantIds, changes?, timestamp }` — `changes` carries only the fields that changed: `subject?`, `description?`, `announce?`, `locked?` |
+| `group.join_request` | Someone asked to join a group this session administers (join-approval mode on) | `{ groupId, actorId?, participantIds, timestamp }` — `participantIds` are the users asking to join; `actorId` is who created the request when the engine reports one (differs from the requester on a non-admin add). Act on it via `GET/POST .../groups/:groupId/membership-requests[...]` **Baileys caveat**: the library (7.0.0-rc13) emits this only for non-admin-add requests — an invite-link self-request may produce no event there (upstream TODO); the membership-requests list endpoint still reports it. |
+| `call.received` | An incoming voice/video call starts ringing. Dispatched by both engines, but **not reliable on whatsapp-web.js**: it fired in a live test on 2026-09-17 and did not in one on 2026-08-10 | `{ callId, from, isVideo, isGroup, timestamp }` — `callId` is the id to pass to `POST /sessions/:sessionId/calls/:callId/reject` (Baileys only). `from` may be an `@lid` privacy id on either engine; resolve it with `GET /api/sessions/:sessionId/contacts/:contactId/phone` |
+| `call.accepted` / `call.rejected` / `call.missed` | A ringing call ended, whether answered, declined, or never picked up. **Baileys only**: whatsapp-web.js emits no call-outcome event | `{ sessionId, callId, from, outcome, isVideo, isGroup, timestamp }`. `callId` matches the `call.received` that preceded it, so the pair can be correlated. The engines report _what_ happened, never _who_ did it: an accept can come from any linked device. An outcome is only sent for a call this session saw ring, and offline-replayed signalling for calls that ended while disconnected is dropped. WhatsApp's `terminate` is deliberately unmapped: it covers both a caller hanging up before answer and either side ending an answered call, with nothing to tell them apart |
+| `status.received` | A contact posts a status/story (opt-in — see below) | `{ sessionId, statusId, contact: { id, name?, pushName? }, type, caption?, hasMedia, mediaOmitted, omitReason?, postedAt, expiresAt }` — `statusId` is the store's `id` (usable with the status endpoints below); `postedAt`/`expiresAt` are epoch **milliseconds** (unlike the epoch-seconds convention for message timestamps), matching the `GET /status` store's own `Date`-backed fields |
> **`status.received` is opt-in and carries no media blob.** Unlike every other event above, `status.received` is only delivered to a webhook whose `events` list explicitly includes `"status.received"` (or `"*"`) — registering for other events does not implicitly subscribe you to it. The payload never embeds media bytes: when `hasMedia` is `true`, fetch the file separately via `GET /api/sessions/:sessionId/status/:statusId/media`. Your own posted statuses never trigger this event — only inbound stories from contacts (an own-send echo is dropped before ingest).
diff --git a/openapi.json b/openapi.json
index a5cc3e67a..832ca7506 100644
--- a/openapi.json
+++ b/openapi.json
@@ -3024,7 +3024,7 @@
},
"/api/sessions/{sessionId}/messages/click-button": {
"post": {
- "description": "Sends a structured button/list reply quoted to a previously received prompt. Not a native UI tap — WhatsApp may reject or treat it differently. Classic button/template/list prompts are supported; native-flow interactiveMessage replies are unverified. whatsapp-web.js returns 501. URL/call CTA buttons cannot be clicked this way. The prompt must still be in the engine store (a reloaded bubble can render choices from persisted metadata and then 404).",
+ "description": "Sends a structured button/list reply quoted to a previously received prompt. Not a native UI tap, so WhatsApp may reject it or treat it differently. Classic button/template/list prompts are supported; native-flow interactiveMessage replies are unverified. whatsapp-web.js returns 501. URL/call CTA buttons cannot be clicked this way. The prompt must still be in the engine store (a reloaded bubble can render choices from persisted metadata and then 404).",
"operationId": "MessageController_clickButton",
"parameters": [
{
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/ClickButtonRequest.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/ClickButtonRequest.java
index 1c3d70f25..83ae3959c 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/ClickButtonRequest.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/ClickButtonRequest.java
@@ -1,7 +1,7 @@
package com.rmyndharis.openwa.model;
/**
- * Request body for tapping a choice on a WhatsApp Business prompt. Baileys only —
+ * Request body for tapping a choice on a WhatsApp Business prompt. Baileys only:
* whatsapp-web.js answers 501.
*/
public record ClickButtonRequest(String chatId, String messageId, String buttonId, String text) {
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java
index 4c9e61334..d0e6ef179 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java
@@ -142,7 +142,7 @@ public final class MessagesResource {
}
/**
- * Click a button on a WhatsApp Business prompt. Baileys only — whatsapp-web.js returns 501.
+ * Click a button on a WhatsApp Business prompt. Baileys only: whatsapp-web.js returns 501.
* Sends a structured reply proto quoted to the prompt, not a native UI tap.
*/
public MessageResponse clickButton(String sessionId, ClickButtonRequest body) {
diff --git a/sdk/javascript/src/resources/messages.ts b/sdk/javascript/src/resources/messages.ts
index 3b17f3fe8..19e9e44c1 100644
--- a/sdk/javascript/src/resources/messages.ts
+++ b/sdk/javascript/src/resources/messages.ts
@@ -132,7 +132,7 @@ export class MessagesResource {
/**
* Click a button on a WhatsApp Business prompt. Baileys only (whatsapp-web.js returns 501).
- * Sends a structured reply proto quoted to the prompt — not a native UI tap.
+ * Sends a structured reply proto quoted to the prompt, not a native UI tap.
*/
clickButton(sessionId: string, body: ClickButtonRequest): Promise<MessageResponse> {
return this.client.request<MessageResponse>({
diff --git a/src/engine/adapters/baileys-message-mapper.ts b/src/engine/adapters/baileys-message-mapper.ts
index df90b5c07..e4047caa6 100644
--- a/src/engine/adapters/baileys-message-mapper.ts
+++ b/src/engine/adapters/baileys-message-mapper.ts
@@ -268,7 +268,7 @@ export interface BaileysButtonReplyContent {
* Extract the stable id (and visible label) when the sender tapped a business button, template
* quick-reply, list row, or native-flow control. Returns `undefined` when the content is not a
* reply shape, or when WhatsApp omitted the id a caller would act on. Pass the NORMALIZED content,
- * as the adapter does — a reply in a disappearing chat nests under `ephemeralMessage`.
+ * as the adapter does: a reply in a disappearing chat nests under `ephemeralMessage`.
*/
export function extractBaileysButtonReply(
content: BaileysButtonReplyContent,
@@ -309,7 +309,7 @@ export function extractBaileysButtonReply(
if (contentType === 'interactiveResponseMessage') {
const flow = content.interactiveResponseMessage?.nativeFlowResponseMessage;
- // Replies must carry a stable id — a display-text-only params payload is not actionable.
+ // Replies must carry a stable id: a display-text-only params payload is not actionable.
const fromParams = parseNativeFlowButtonParams(flow?.paramsJson, { requireId: true });
if (fromParams) {
return fromParams;
@@ -391,7 +391,7 @@ const CLICKABLE_NATIVE_FLOW_NAMES = new Set(['quick_reply', 'button_click']);
/**
* One clickable choice, carrying the proto index a template reply must echo. Not published on
- * {@link IncomingMessage.buttons} — callers send `id` (and optional `text`) and the click path
+ * {@link IncomingMessage.buttons}: callers send `id` (and optional `text`) and the click path
* looks the index up.
*/
export interface BaileysClickableChoice {
@@ -445,7 +445,7 @@ export interface BaileysButtonClickPayload {
/**
* Resolve a click against a stored business prompt: validate the content type and button id, fill
* in the display text when the caller omitted it, and build the `sendMessage` content WhatsApp
- * expects for that prompt shape. CTA url/call entries are not clickable — only quick-reply style
+ * expects for that prompt shape. CTA url/call entries are not clickable, only quick-reply style
* choices and list rows. When several choices share an id, a caller-supplied `text` disambiguates
* (a list reusing `rowId` across sections).
*/
@@ -493,7 +493,7 @@ export function resolveBaileysButtonClick(
/**
* Choices that can be answered with a structured reply. URL/call CTAs and other native-flow names
- * are excluded — the WhatsApp client opens CTAs locally and there is no reply shape to fake.
+ * are excluded: the WhatsApp client opens CTAs locally and there is no reply shape to fake.
* {@link extractBaileysButtons} is a projection of this list, so the published `buttons[]` and the
* click allowlist cannot disagree.
*/
@@ -923,7 +923,7 @@ export function buildIncomingMessageFromBaileys(
to: fields.fromMe ? chatId : self,
chatId,
// Native-flow replies sometimes put the visible label only in paramsJson (surfaced on `button`),
- // not in `interactiveResponseMessage.body` — prefer an explicit body, else the button label.
+ // not in `interactiveResponseMessage.body`, so prefer an explicit body, else the button label.
body: fields.body || fields.button?.text || '',
type: mapBaileysMessageType(fields.contentType, fields.isPtt, fields.isCatalogShare),
timestamp: fields.timestamp,
diff --git a/src/engine/engine-capability-matrix.ts b/src/engine/engine-capability-matrix.ts
index 9d36f0930..5e102db4c 100644
--- a/src/engine/engine-capability-matrix.ts
+++ b/src/engine/engine-capability-matrix.ts
@@ -437,7 +437,7 @@ export const CURATED_CAPABILITY_EXCEPTIONS: Record<string, MethodCapability> = {
wwjs: { status: 'not-available', rootCause: 'library-limitation' },
baileys: { status: 'supported' },
evidence:
- 'wwjs has no interactive button-reply send path; baileys sendMessage({buttonReply,type}) / sendMessage({listReply}) for buttonsMessage, templateMessage and listMessage (Types/Message.d.ts ButtonReplyInfo / listReply; Utils/messages.js). Native-flow interactiveMessage has no helper and is unverified — the adapter sends a template buttonReply, not InteractiveResponseMessage, and must not be advertised as fully supported until a live business native-flow prompt confirms the server accepts it',
+ 'wwjs has no interactive button-reply send path; baileys sendMessage({buttonReply,type}) / sendMessage({listReply}) for buttonsMessage, templateMessage and listMessage (Types/Message.d.ts ButtonReplyInfo / listReply; Utils/messages.js). Native-flow interactiveMessage has no helper and is unverified: the adapter sends a template buttonReply, not InteractiveResponseMessage, and must not be advertised as fully supported until a live business native-flow prompt confirms the server accepts it',
},
unpinMessage: {
wwjs: { status: 'supported' },
diff --git a/src/engine/interfaces/whatsapp-engine.interface.ts b/src/engine/interfaces/whatsapp-engine.interface.ts
index eb052960b..51a6fe8e2 100644
--- a/src/engine/interfaces/whatsapp-engine.interface.ts
+++ b/src/engine/interfaces/whatsapp-engine.interface.ts
@@ -146,7 +146,7 @@ export interface IncomingMessage {
* Set when the sender tapped a WhatsApp Business button, template quick-reply, list row, or
* native-flow control. `id` is the stable handle the business defined on the button/row; `text`
* is the visible label when WhatsApp still carries it (also mirrored into `body`). **Baileys
- * only** — whatsapp-web.js does not surface interactive replies as structured fields.
+ * only**: whatsapp-web.js does not surface interactive replies as structured fields.
*/
button?: {
id: string;
@@ -154,7 +154,7 @@ export interface IncomingMessage {
};
/**
* Set on an inbound WhatsApp Business prompt that offers buttons (or list rows flattened as
- * buttons): the choices shown to the recipient. URL/call CTAs are omitted — they are not
+ * buttons): the choices shown to the recipient. URL/call CTAs are omitted, since they are not
* clickable via {@link IWhatsAppEngine.clickButton} and must not masquerade as button ids.
* Distinct from {@link IncomingMessage.button}, which is set only when someone *taps* a choice.
* **Baileys only.** Capped (count and label length) so a malformed prompt cannot bloat
@@ -1058,13 +1058,13 @@ export interface MessageOperationsCapability {
/**
* Reply to a WhatsApp Business button / list prompt as if the account tapped a choice.
* `buttonId` is the stable id from the prompt (see inbound `buttons[].id`); `text` is the visible
- * label when known. **Baileys only** — whatsapp-web.js has no interactive-reply send path.
+ * label when known. **Baileys only**: whatsapp-web.js has no interactive-reply send path.
*
* The prompt must already be in the engine message store (received while the session was live).
* Classic `buttonsMessage` / `templateMessage` / `listMessage` prompts go through Baileys'
* `buttonReply` / `listReply` helpers. Native-flow `interactiveMessage` replies are unverified
* against a live business prompt and must not be treated as fully supported. URL/call CTA
- * buttons are not clickable this way — only quick-reply style choices and list rows.
+ * buttons are not clickable this way, only quick-reply style choices and list rows.
*/
clickButton(chatId: string, messageId: string, buttonId: string, text?: string): Promise<MessageResult>;
diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.ts
index 144ddb011..75c2cc18c 100644
--- a/src/modules/message/message.controller.ts
+++ b/src/modules/message/message.controller.ts
@@ -366,8 +366,9 @@ export class MessageController {
summary: 'Click a button on a WhatsApp Business prompt (Baileys only)',
description:
'Sends a structured button/list reply quoted to a previously received prompt. Not a native UI ' +
- 'tap — WhatsApp may reject or treat it differently. Classic button/template/list prompts are ' +
- 'supported; native-flow interactiveMessage replies are unverified. whatsapp-web.js returns 501. ' +
+ 'tap, so WhatsApp may reject it or treat it differently. Classic button/template/list prompts ' +
+ 'are supported; native-flow interactiveMessage replies are unverified. whatsapp-web.js ' +
+ 'returns 501. ' +
'URL/call CTA buttons cannot be clicked this way. The prompt must still be in the engine store ' +
'(a reloaded bubble can render choices from persisted metadata and then 404).',
})