Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: warn that the passkey linking gate blocks both engines
Yudhi Armyndharisbace4579c225
diff --git a/README.md b/README.mdindex 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).### Compliancediff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.mdindex d67fbae22..3b6622b1d 100644--- a/docs/03-system-architecture.md+++ b/docs/03-system-architecture.md@@ -1188,9 +1188,9 @@ flowchart TBendsubgraph 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]endsubgraph Resolution["Resolution"]@@ -1200,7 +1200,7 @@ flowchart TBA --> BB -->|Minor| C --> FB -->|Major wwebjs| D --> F- B -->|Major Both| E --> F+ B -->|Major Both| E --> C```### Engine Comparisondiff --git a/docs/16-risk-management.md b/docs/16-risk-management.mdindex 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 TBM1 --> 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 releases2. Engine abstraction layer — implemented (pluggable `ENGINE_TYPE`: `whatsapp-web.js` default, `baileys` alternative)3. Document fallback procedures4. Maintain relationships with library maintainers@@ -459,15 +462,20 @@ flowchart TBflowchart TBT[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```