Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(api): correct the sticker, contact block and ack notes
Yudhi Armyndharis97038830c174
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 550f3ac91..f3b68a0ac 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -2096,7 +2096,7 @@ Send a contact card (vCard).#### POST /api/sessions/:sessionId/messages/send-sticker-Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`. On Baileys a WebP is sent unchanged and any other `image/*` is converted to a 512x512 WebP first, keeping up to 500 animation frames.+Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`. On Baileys a WebP is sent unchanged and any other raster `image/*` is converted to a 512x512 WebP first, keeping up to 500 animation frames; `image/svg+xml` is refused with `400`.**Auth:** API key (OPERATOR)@@ -2749,7 +2749,7 @@ Block a contact.| sessionId | string | Session ID. || contactId | string | Contact id / JID, e.g. `[email protected]`. |-This route takes no request body and binds no DTO. Send an empty body `{}` (the global `whitelist` + `forbidNonWhitelisted` ValidationPipe rejects any unexpected field with `400`).+This route takes no request body and binds no DTO. Send none or an empty body `{}`: a body is not validated, and any content it carries is ignored.**Response** `200`@@ -5025,7 +5025,7 @@ Create a new API key; returns the full plaintext key exactly once.| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Defaults to `operator` when omitted. || `allowedIps` | string[] | no | each entry a valid **IPv4** address or IPv4 CIDR `/0-32`; IPv6 rejected | IP whitelist (IPv4-only by design). || `allowedSessions` | string[] | no | each `@IsString`, `@ArrayUnique`; each entry non-empty, no surrounding whitespace, no comma | Session IDs this key may access. |-| `allowedChats` | string[] | no | unique entries, each a group `<id>@g.us`, a contact `<phone>@c.us` / `<lid>@lid`, or a bare phone number | Chat IDs this key may reach (see [Roles & Authorization](#roles--authorization)). |+| `allowedChats` | string[] | no | unique entries, each a group `<id>@g.us`, a contact `<phone>@c.us` / `<lid>@lid`, or a bare phone number; at most 2000 | Chat IDs this key may reach (see [Roles & Authorization](#roles--authorization)). || `expiresAt` | string (ISO 8601 date) | no | `@IsDateString`, and must parse as a date: an ISO week, ordinal or basic form such as `2026-W40-1` is refused with `400 "expiresAt is not a parseable date"` | Stored as a `Date`. |```json@@ -7208,7 +7208,7 @@ These are the events OpenWA actually emits. A webhook is registered with an `eve| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `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`), `fromMe`, `chatId`, `media{mimetype,filename?,data?,omitted?,sizeBytes?}` (media messages only), `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. On Baileys only 1:1 receipts arrive: it reports group and status receipts per participant, which are not consumed, so an own group or status message stays at `sent` | `{ id, messageId, status, ack, chatId? }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it; `chatId` is the conversation the acked message belongs to, present whenever the engine's update names the chat (both engines do on the live path) |+| `message.ack` | A delivery/read receipt updates an outbound message. On Baileys only 1:1 receipts arrive: it reports group and status receipts per participant, which are not consumed, so an own group or status message stays at `sent`, see below | `{ id, messageId, status, ack, chatId? }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it; `chatId` is the conversation the acked message belongs to, present whenever the engine's update names the chat (both engines do on the live path) || `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1, chatId? }`; `chatId` follows the same rules as `message.ack` || `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 |@@ -7229,6 +7229,8 @@ These are the events OpenWA actually emits. A webhook is registered with an `eve| `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 |+> **`message.ack` on Baileys.** An own group or status message stays at `sent` unless the server rejects it, which still arrives as `failed`. The event is not limited to outbound messages: when the account's own phone reads a 1:1 chat, the messages received there are acked as `read` too, with no `fromMe` in the payload, and their stored copy moves to `read`.+> **`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).> **`STORE_EPHEMERAL_MESSAGES=false` affects `message.received`.** When `STORE_EPHEMERAL_MESSAGES` is set to `false`, incoming disappearing messages (those with `ephemeralDuration > 0`) are **not** persisted nor dispatched — no DB insert, no webhook delivery, and no websocket event. Downstream consumers and the dashboard both stop seeing them. Default is `true` (backward compatible — store and dispatch everything).diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.mdindex 2512284d7..8d6d64f45 100644--- a/docs/29-engine-capability-matrix.md+++ b/docs/29-engine-capability-matrix.md@@ -929,10 +929,12 @@ adapter boundary — none silently stubs.(the latter via ffmpeg), rejecting anything else with `Invalid media format`. Baileys stamps`image/webp` on the payload unconditionally and transcodes nothing(`prepareWAMessageMedia` → `MIMETYPE_MAP.sticker`), so the adapter converts before the socket:- WebP passes through byte-identical (preserving its sticker-pack EXIF), other `image/*` input is- re-encoded to a 512×512 WebP with animation retained (up to 500 frames; a longer animation is- refused with a `400`), and everything else — **including `video/*`** — is refused with a `400`.- So an animated-video sticker works on wwjs and answers `400` on Baileys. ffmpeg is deliberately+ WebP passes through byte-identical (preserving its sticker-pack EXIF), other raster `image/*`+ input is re-encoded to a 512×512 WebP with animation retained (up to 500 frames; a longer+ animation is refused with a `400`), and everything else, **including `video/*` and+ `image/svg+xml`** (the adapter blocks SVG decoding), is refused with a `400`. So an+ animated-video sticker works on wwjs and answers `400` on Baileys, and so does an SVG, which+ whatsapp-web.js hands to the page like any other `image/*`. ffmpeg is deliberatelynot wired in on the Baileys side: the binary ships only in the Docker image, so depending on itwould make the same request succeed or fail depending on how the gateway was installed.- **`deleteStatus` (baileys).** Baileys sends a status stanza, the revoke included, to exactly its