Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: an environment label needs an OpenWA restart, not a session one

Yudhi Armyndharisd15bca5ffe51
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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)).
### Dependencies
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 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 a
non-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 the
phone-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 few
diff --git a/docs/examples/session-phone-number-pairing.md b/docs/examples/session-phone-number-pairing.md
index 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.ts
index 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 sessions
diff --git a/src/engine/adapters/wwebjs-onboarding.ts b/src/engine/adapters/wwebjs-onboarding.ts
index 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.',
{