Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(messages): list the whatsapp-web.js recipient refusals

Yudhi Armyndharis8f0c12761503
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index cca2207b2..45f5e501a 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1699,6 +1699,10 @@ One upstream gap remains on whatsapp-web.js and cannot be switched off from here
message resolves but the page decides it is not replyable, the message is sent without the quote and
the call still succeeds.
+On whatsapp-web.js a quoted send to a channel, `status@broadcast` or a broadcast list answers `501`
+and nothing is sent: the library drops a reply to those recipients without sending it, so the
+gateway refuses it before the call. The Baileys engine does not refuse it.
+
Quoting a message from a **different chat** is not validated on these `send-*` routes on either
engine; the id is passed through as given. `POST /messages/reply` is stricter: both engines refuse a
quoted id that does not belong to the target chat, with `404`.
@@ -1963,7 +1967,7 @@ Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine, or (whatsapp-web.js) a sticker to a channel, `status@broadcast` or a broadcast list · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
#### POST /api/sessions/:sessionId/messages/send-poll
diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.md
index 3f1acdb9b..9019e678c 100644
--- a/docs/29-engine-capability-matrix.md
+++ b/docs/29-engine-capability-matrix.md
@@ -910,10 +910,15 @@ adapter boundary — none silently stubs.
`sendAudioMessage`, `sendDocumentMessage` and `sendStickerMessage` are ✅ on wwjs for chats and
groups, but a `<id>@newsletter` recipient throws `ChannelMediaNotSupportedError` (a
`NotImplementedException` → HTTP 501) at `ensureNotChannelRecipient`
- (`wwebjs-messaging.ts:425` for the media funnel, `:492` for stickers). whatsapp-web.js calls
+ (`wwebjs-messaging.ts:446` for the media funnel, `:515` for stickers). whatsapp-web.js calls
`msg.avParams()`, removed in a recent WA Web build (upstream wwebjs#201823, unresolved).
- Text→channel is unaffected, and Baileys has no such restriction, so these five rows answer `501`
- without a per-row ❌ in 29.4.
+ Unquoted text→channel is unaffected, and Baileys has no such restriction, so these five rows answer
+ `501` without a per-row ❌ in 29.4. A few other sends answer `501` on wwjs by recipient, because
+ whatsapp-web.js drops them without touching the page (`Client.js` `sendMessage` returns `null`): a
+ reply (any send carrying a quoted message), a location or a contact card to a channel,
+ `status@broadcast` or a broadcast list, and a poll or a sticker to `status@broadcast` or a
+ broadcast list. `ensureSendable` (`wwebjs-messaging.ts:206`) refuses them before the library is
+ called, so nothing is sent. The Baileys adapter refuses none of them.
- **`sendStickerMessage` — what each engine converts.** Both engines guarantee the payload really is
WebP, but they reach it differently and they do not accept the same inputs. whatsapp-web.js passes
`sendMediaAsSticker: true`, and `Util.formatToWebpSticker` converts `image/*` **and** `video/*`