Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: an environment label needs an OpenWA restart, not a session one
Yudhi Armyndharisd15bca5ffe51
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fac0751fd..6d4004efb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -85,7 +85,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- The pairing-code route, the phone-pairing example and the dashboard's phone tab warn that on whatsapp-web.js a code requested for a number that already has a linked session can end with WhatsApp unlinking that device; the capability matrix records the measurement ([#1653](https://github.com/rmyndharis/OpenWA/issues/1653)).- The docs and the OpenAPI field descriptions scope `maxReconnectAttempts` and `reconnectBaseDelay` to the gateway's own reconnect: on Baileys that is only the reconnect after a logged-out close, since the engine retries every other drop itself, with a fixed 1s to 60s backoff and no attempt cap ([#1651](https://github.com/rmyndharis/OpenWA/issues/1651)).- The docs, the README, the OpenAPI field descriptions and the dashboard's auto-reject hint mark call rejection, `autoRejectCalls` and the call outcome events as Baileys only, and `call.received` as not reliable on whatsapp-web.js ([#1118](https://github.com/rmyndharis/OpenWA/discussions/1118)). Thanks @etondeengole for the report.-- The FAQ, `.env.example` and the whatsapp-web.js unrecognised-dialog warning describe the onboarding-modal language correctly: `--lang=en-US` is appended automatically, WhatsApp Web can still render the modal in the account's language, and a label in `WWEBJS_ONBOARDING_CONTINUE_LABELS` plus a session restart covers it ([#1679](https://github.com/rmyndharis/OpenWA/issues/1679)). Thanks @DavidgFernandes for the report.+- The FAQ, `.env.example` and the whatsapp-web.js unrecognised-dialog warning describe the onboarding-modal language correctly: `--lang=en-US` is appended automatically, WhatsApp Web can still render the modal in the account's language, and a label in `WWEBJS_ONBOARDING_CONTINUE_LABELS` plus a restart of OpenWA covers it ([#1679](https://github.com/rmyndharis/OpenWA/issues/1679)). Thanks @DavidgFernandes for the report.+- The FAQ and the phone-pairing example say that `BAILEYS_BROWSER_NAME` takes effect after a restart of OpenWA, not of the session, since the name is read at boot ([#1666](https://github.com/rmyndharis/OpenWA/issues/1666)).### Dependenciesdiff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex ff033b797..9c34ebeaf 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -280,7 +280,8 @@ change will come from the engine libraries implementing the step.**Cause:** the pairing request carries the linked-device identity, and some accounts reject anon-standard one. The default device name is `OpenWA`; set `BAILEYS_BROWSER_NAME=Ubuntu` (or another-standard OS name), restart the session, and request a fresh code. The name applies to new pairings only;+standard OS name), restart OpenWA itself (the name is read at boot, so stopping and starting the session+is not enough), and request a fresh code. The name applies to new pairings only;a session that is already linked keeps the name it was paired with until it is re-linked. See thephone-number pairing example in `docs/examples/session-phone-number-pairing.md`.@@ -557,8 +558,9 @@ once, so the session stops instead of being silently unlinked by WhatsApp about> (`Continue`) under the English heading ("What's new"). OpenWA appends `--lang=en-US` to the browser> flags unless `PUPPETEER_ARGS` already carries a `--lang`, but that sets the browser's language, and> WhatsApp Web may still render in the account's own language. For another language, add the modal's-> confirm-button label to `WWEBJS_ONBOARDING_CONTINUE_LABELS` (for example `Continuar`) and restart the-> session: the watcher runs only for the first minutes after `ready`. A configured label is clicked+> confirm-button label to `WWEBJS_ONBOARDING_CONTINUE_LABELS` (for example `Continuar`) and restart+> OpenWA itself: the value is read at boot, so stopping and starting the session is not enough. A+> configured label is clicked> without the English heading check, but only on a button inside a visible dialog. If your deployment gets a> localised modal without a matching label, it is **not** auto-dismissed and the session never reaches> `action_required`; instead it links normally, then drops to `disconnected` with reason `LOGOUT` a fewdiff --git a/docs/examples/session-phone-number-pairing.md b/docs/examples/session-phone-number-pairing.mdindex 580cb4377..e6403e026 100644--- a/docs/examples/session-phone-number-pairing.md+++ b/docs/examples/session-phone-number-pairing.md@@ -99,5 +99,5 @@ After the code is accepted, the OpenWA session should move to a connected/ready- 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.+- 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 OpenWA itself (the name is read at boot, so stopping and starting the session is not enough), and request a fresh code.- If you want to create a brand-new WhatsApp account programmatically, that is outside OpenWA's scope. OpenWA only links an existing WhatsApp account.diff --git a/src/config/configuration.ts b/src/config/configuration.tsindex 91dc00bc7..63fbd8818 100644--- a/src/config/configuration.ts+++ b/src/config/configuration.ts@@ -75,7 +75,8 @@ export const PINNED_BROWSER_LOCALE = 'en-US';* Append the locale pin unless the operator already set one. Deliberately applied AFTER the* PUPPETEER_ARGS override rather than baked into the default string: that variable REPLACES the* defaults, so a deployment that customises args for an unrelated reason would otherwise silently- * lose the pin and the onboarding detector with it. An explicit `--lang` always wins.+ * lose the pin and fall back to the binary's default browser language. An explicit `--lang` always+ * wins.** Returns a NEW array — never mutates the input — because the resolved args object is shared by every* session, and pushing per-session flags onto a shared array leaked proxy settings across sessionsdiff --git a/src/engine/adapters/wwebjs-onboarding.ts b/src/engine/adapters/wwebjs-onboarding.tsindex 8b57eac40..66621e168 100644--- a/src/engine/adapters/wwebjs-onboarding.ts+++ b/src/engine/adapters/wwebjs-onboarding.ts@@ -11,9 +11,9 @@ export const ONBOARDING_DEFAULT_CONTINUE_LABEL = 'Continue';* English, comma-separated (`WWEBJS_ONBOARDING_CONTINUE_LABELS=Continuar,Weiter`).** Needed because the match is on visible text and WhatsApp controls those strings; we are not going- * to carry its translation table. Read per probe, not cached, so a change made through the infra- * config reaches a watcher that is still running. The watcher only runs for the first minutes after- * ready, so a label added later takes effect on the next session start.+ * to carry its translation table. The value comes from the environment loaded at boot, so a label+ * added later takes effect only after OpenWA itself restarts; stopping and starting a session is not+ * enough.** Supplying labels also drops the heading requirement for THOSE labels: the English heading regex* would reject a localised modal anyway, so requiring both would make the setting useless. That is a@@ -333,7 +333,7 @@ export class WwebjsOnboardingWatcher {this.host.logger.warn('A visible dialog on WhatsApp Web matches neither the onboarding-modal heading nor a ' +'confirm-button label. If this is the onboarding screen in another language, add its ' +- 'confirm-button label to WWEBJS_ONBOARDING_CONTINUE_LABELS and restart the session; on a ' ++ 'confirm-button label to WWEBJS_ONBOARDING_CONTINUE_LABELS and restart OpenWA; on a ' +'newly linked account WhatsApp unlinks the companion within minutes while it stays open. ' +'An English onboarding screen that is not recognised is worth reporting.',{