Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: warn that the passkey linking gate blocks both engines

Yudhi Armyndharisbace4579c225
diff --git a/README.md b/README.md
index 2ac03a33f..68f871087 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,7 @@ A few things that look like bugs but are actually server-side WhatsApp policy, n
- **First message to a brand-new contact sometimes never arrives.** The API returns success because the message leaves OpenWA, but WhatsApp's server-side reach-out / trust policy drops it at delivery. This is independent of OpenWA. We track it in [#830](https://github.com/rmyndharis/OpenWA/issues/830).
- **Accounts that get restricted cannot be "unrestricted" by us.** If WhatsApp disables a number, you need to appeal through their channels — OpenWA has no lever to pull.
+- **Some accounts cannot link a new device at all.** WhatsApp has added a passkey step to companion linking for some accounts: the phone asks to "Create a passkey" or "Continue on your other device" and the session stays at `qr_ready`. Neither engine implements that step, so switching engine or using a pairing code does not help, and no OpenWA setting changes it. Avoid logging out or re-linking a session that works, since linking it again may hit the same gate, and keep the fallback from rule 5 above. See [the FAQ entry](docs/12-troubleshooting-faq.md#issue-linking-asks-for-a-passkey-and-never-completes-both-engines); tracked in [#560](https://github.com/rmyndharis/OpenWA/issues/560).
### Compliance
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.md
index d67fbae22..3b6622b1d 100644
--- a/docs/03-system-architecture.md
+++ b/docs/03-system-architecture.md
@@ -1188,9 +1188,9 @@ flowchart TB
end
subgraph Migration["Migration Path"]
- C[Update whatsapp-web.js]
+ C[Update engine library]
D[Switch to Baileys]
- E[Community Fork]
+ E[Track upstream fix\nOperators use fallback channel]
end
subgraph Resolution["Resolution"]
@@ -1200,7 +1200,7 @@ flowchart TB
A --> B
B -->|Minor| C --> F
B -->|Major wwebjs| D --> F
- B -->|Major Both| E --> F
+ B -->|Major Both| E --> C
```
### Engine Comparison
diff --git a/docs/16-risk-management.md b/docs/16-risk-management.md
index 3b3c0af96..b13a9cc44 100644
--- a/docs/16-risk-management.md
+++ b/docs/16-risk-management.md
@@ -34,13 +34,14 @@ quadrantChart
| **Risk Level** | Critical |
**Description:**
-WhatsApp can change their Web protocol at any time, which can cause the `whatsapp-web.js` library to stop working.
+WhatsApp can change its Web and multi-device protocols at any time, which can stop either engine library (`whatsapp-web.js` or Baileys) from working. A step WhatsApp enforces server-side inside the linking handshake, such as the passkey prompt some accounts now get ([#560](https://github.com/rmyndharis/OpenWA/issues/560)), blocks new links on both engines at once.
**Indicators:**
-- Spike in `whatsapp-web.js` issues
+- Spike in engine library issues (`whatsapp-web.js` or Baileys)
- Sudden increase in error rates
- Authentication failures
+- New links stall at `qr_ready` on both engines (see [docs/12](./12-troubleshooting-faq.md#issue-linking-asks-for-a-passkey-and-never-completes-both-engines))
**Mitigation Strategies:**
@@ -53,13 +54,15 @@ flowchart TB
M1 --> A1[Watch releases & issues]
M2 --> A2[Engine interface pattern]
- M3 --> A3[Baileys engine available - ENGINE_TYPE env]
+ M3 --> A3[Switch ENGINE_TYPE - only when one library breaks]
M4 --> A4[< 24h patch capability]
```
+Switching `ENGINE_TYPE` (M3) helps only when one engine library breaks. A gate WhatsApp enforces inside the linking handshake, such as the passkey step ([#560](https://github.com/rmyndharis/OpenWA/issues/560), upstream [WhiskeySockets/Baileys#2672](https://github.com/WhiskeySockets/Baileys/issues/2672)), stops new links on both engines; the fix has to come from the engine libraries, and operators rely on their fallback channel until then (see [Plan A](#plan-a-whatsapp-protocol-change)).
+
**Action Items:**
-1. Subscribe to `whatsapp-web.js` releases
+1. Subscribe to `whatsapp-web.js` and Baileys releases
2. Engine abstraction layer — implemented (pluggable `ENGINE_TYPE`: `whatsapp-web.js` default, `baileys` alternative)
3. Document fallback procedures
4. Maintain relationships with library maintainers
@@ -459,15 +462,20 @@ flowchart TB
flowchart TB
T[Trigger: Protocol Change] --> A1[Assess Impact]
A1 --> |Minor| M1[Wait for library update]
- A1 --> |Major| M2[Activate contingency]
-
- M2 --> C1[Notify users]
- C1 --> C2[Switch to maintenance mode]
- C2 --> C3[Evaluate alternatives]
- C3 --> |Baileys viable| C4[Switch to Baileys engine - set ENGINE_TYPE=baileys]
- C3 --> |No alternatives| C5[Project pause/EOL]
+ A1 --> |Major| E{One engine or both?}
+
+ E --> |One engine| C1[Notify users]
+ C1 --> C2[Set ENGINE_TYPE to the unaffected engine]
+ C2 --> M1
+ E --> |Both engines or server-side gate| B1[Notify users and link the tracking issue]
+ B1 --> B2[Keep linked sessions running - no logout or restart churn]
+ B2 --> B3[Operators move critical traffic to their fallback channel]
+ B3 --> B4[Track the engine libraries upstream]
+ B4 --> |No path for a long period| C5[Project pause/EOL]
```
+During a both-engines event keep linked sessions running rather than logging them out or deleting them: linking again may hit the same gate.
+
### Plan B: Critical Security Vulnerability
```