Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(pairing): warn that a wwjs pairing code can unlink a linked device

Yudhi Armyndharis73932e8cf9b6
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 056ef6dab..0b4463e87 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -773,6 +773,8 @@ Returned via `transformSession`.
Request an 8-char pairing code to link via phone number (alternative to QR).
+> ⚠️ **On the whatsapp-web.js engine, only request a code for a number you are prepared to re-link.** A request for a number that already has a linked session has been observed to end with WhatsApp revoking that device: the linked session logs a LOGOUT, its credentials are deleted, and it falls back to `qr_ready` with no phone. Nothing here refuses such a request: the guards check the session's state, never the number. The request runs inside the shared WhatsApp Web page and resets its linking mode before asking for a code, so the blast radius is the account rather than the session. Baileys was not affected in the same tests. Link by QR when a session of that number must stay up.
+
**Auth:** API key (OPERATOR) · **Scope:** session-scoped
**Path parameters**
diff --git a/docs/examples/session-phone-number-pairing.md b/docs/examples/session-phone-number-pairing.md
index 409ae1a06..580cb4377 100644
--- a/docs/examples/session-phone-number-pairing.md
+++ b/docs/examples/session-phone-number-pairing.md
@@ -6,6 +6,8 @@ This flow returns an 8-character pairing code that the user enters in WhatsApp o
> This does **not** create or register a new WhatsApp account. It only links an existing WhatsApp account as a companion device for an OpenWA session.
+> **On the whatsapp-web.js engine, request a code only for a number you are prepared to re-link.** A pairing request for a number that already has a linked session has been observed to end with WhatsApp revoking that device: within about a minute the linked session logs `WhatsApp unlinked this device (LOGOUT)`, its stored credentials are deleted, and it returns to `qr_ready` with no phone. The request runs inside the shared WhatsApp Web page and resets its linking mode before it asks for a code, so the blast radius is the account, not the session. Baileys has no such page and was not affected in the same tests. If a session of that number must stay up, link the new one by QR.
+
## Flow
```
@@ -94,7 +96,7 @@ After the code is accepted, the OpenWA session should move to a connected/ready
## Troubleshooting
- If OpenWA returns `Session is not started`, call `POST /api/sessions/{sessionId}/start` first.
-- If OpenWA returns `Session is already authenticated`, the account is already linked and no pairing code is needed.
+- If OpenWA returns `Session is already authenticated`, the account is already linked and no pairing code is needed. Nothing refuses a request whose number is linked to a DIFFERENT session, or to a device outside this gateway, and on whatsapp-web.js that is the request that can unlink it; see the warning at the top.
- If OpenWA returns 409 `Session is not waiting to be linked`, the engine is still connecting (or reconnecting after a drop). Wait for `status` to read `qr_ready` and request again. After a code was accepted the same 409 is answered until the session is `ready`; do not request another code then. On Baileys the same 409 can also answer while `status` already reads `qr_ready`, for as long as the WebSocket takes to finish closing (up to 30 s on a silently dropped connection); retry rather than treating it as a bad state.
- If the phone number is rejected, send digits only in international format, without `+`, spaces, or punctuation.
- If pairing keeps failing with a generic "check the phone number" rejection even though the number is correct and in the right format, WhatsApp is refusing the linked-device identity for that account rather than the number itself. The default device name `OpenWA` is carried into the pairing request, and some accounts reject a non-standard one. Set `BAILEYS_BROWSER_NAME=Ubuntu` (or another standard OS name), restart the session, and request a fresh code.
diff --git a/src/engine/engine-capability-matrix.ts b/src/engine/engine-capability-matrix.ts
index 0f3ada0ed..c58d86e24 100644
--- a/src/engine/engine-capability-matrix.ts
+++ b/src/engine/engine-capability-matrix.ts
@@ -304,6 +304,21 @@ export const CURATED_CAPABILITY_EXCEPTIONS: Record<string, MethodCapability> = {
evidence:
"baileys rejectCall(callId, callFrom) (Socket/messages-recv.d.ts:10) with the raw `from` JID cached from the 'offer' call event (Types/Call.d.ts); measured live on 2026-09-17 with 7.0.0-rc14, a real call fired call.received then call.rejected and auto-reject stopped the caller's phone at once. wwjs Call.reject() exists and is typed Promise<void> (index.d.ts:2417) on the Call from the client 'call' event (index.d.ts:643), but measured live on 2026-09-17 on OpenWA 0.23.4 with WhatsApp Web 2.3000.1047471845-alpha the reject resolved and OpenWA logged the call as auto-rejected while the caller's phone kept ringing until it timed out. The cause is not established. The page function Call.reject() runs, WWebJS.rejectCall, is modified by OpenWA patch 1 (scripts/wwebjs-201832.patch), which reads getMaybeMePnUser()._serialized || $1",
},
+ requestPairingCode: {
+ wwjs: { status: 'supported' },
+ baileys: { status: 'supported' },
+ evidence:
+ 'Curated for a hazard, not a gap: both engines return a code. wwjs Client.requestPairingCode ' +
+ '(Client.js:516-571) runs in the shared WhatsApp Web page and calls ' +
+ 'PairingCodeLinkUtils.setPairingType + initializeAltDeviceLinking before startAltLinkingFlow, ' +
+ 'checking no precondition; measured twice (2026-09-17, 2026-09-18) a request for a number that ' +
+ 'already had a linked session was followed within about a minute by WhatsApp revoking that ' +
+ 'device, whatsapp-web.js deleting its credentials and the session returning to qr_ready. It ' +
+ 'also arms an in-page 3-minute re-request interval that OpenWA cannot cancel (cancelPairingCode ' +
+ 'is not exposed) and notifies the phone on every code. baileys requestPairingCode ' +
+ '(Socket/socket.js:596-650) writes only its own creds and sends one link_code_companion_reg IQ, ' +
+ 'with no shared page; no side effect was observed there.',
+ },
sendCatalog: {
wwjs: { status: 'not-available', rootCause: 'library-limitation' },
baileys: { status: 'not-available', rootCause: 'library-limitation' },