Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(wwebjs): correct the onboarding-modal locale guidance

Yudhi Armyndharisc5e20f6b2077
diff --git a/.env.example b/.env.example
index 615e3ad7d..da32a95b7 100644
--- a/.env.example
+++ b/.env.example
@@ -125,8 +125,9 @@ STATUS_SEED_ON_READY=false
# PUPPETEER_HEADLESS=true
# Browser flags, comma- or space-separated. NOTE: this REPLACES the default list rather than adding to
# it, so repeat the flags you still want — dropping --no-sandbox stops Chromium launching in a
-# container. `--lang=en-US` is appended automatically unless you pass your own `--lang`: WhatsApp Web
-# renders in the browser's language and the onboarding-modal handling below matches visible text.
+# container. `--lang=en-US` is appended automatically unless you pass your own `--lang`. It sets the
+# browser's language, but WhatsApp Web may still follow the account's; for a non-English onboarding
+# modal see WWEBJS_ONBOARDING_CONTINUE_LABELS below.
# PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage,--disable-gpu
# Path to a system Chromium/Chrome binary. Leave unset to use the bundled Puppeteer browser.
# Required in the Docker image and on hosts without a bundled browser (e.g. Alpine/ARM).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7000c5b0d..333efdfdc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -83,6 +83,7 @@ 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.
### Dependencies
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 847923ea5..3cff0ea5b 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -553,20 +553,18 @@ acknowledged before the companion device is allowed to stay linked. The adapter
and only gives up after five clicks that fail to land — at that point a human must click through it
once, so the session stops instead of being silently unlinked by WhatsApp about five minutes later.
-> **If the modal is not in English:** the detector matches the English button label (`Continue`) and
-> heading ("What's new"). The language WhatsApp Web renders in follows the browser locale, which OpenWA
-> does not set, so it is whatever the browser the container launches defaults to
-> (`PUPPETEER_EXECUTABLE_PATH` — Chrome for Testing on amd64, Debian's `chromium` on arm64). You can
-> pin it yourself by appending `--lang=en-US` to `PUPPETEER_ARGS` — that variable **replaces** the
-> default list rather than adding to it, so repeat the existing flags too (dropping `--no-sandbox` in
-> a container stops Chromium launching at all). If your deployment does get a
-> localised modal, 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 minutes later and
-> the device disappears from the phone's Linked devices list. That miss is no longer silent: when the
-> watcher finds a visible dialog it cannot match, it logs a warning (`action:
-onboarding_dialog_unrecognized`) carrying the dialog's heading and button labels — the label to add
-> via `WWEBJS_ONBOARDING_CONTINUE_LABELS`, and the heading worth reporting — minutes before the unlink
-> would happen. Because that path wipes the stored
+> **If the modal is not in English:** by default the detector matches only the English button label
+> (`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`. 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
+> minutes later and the device disappears from the phone's Linked devices list. That miss is not
+> silent: when the watcher finds a visible dialog it cannot match, it logs a warning
+> (`action: onboarding_dialog_unrecognized`) carrying the dialog's heading and button labels, including
+> the label to add, minutes before the unlink would happen. Because that path wipes the stored
> credentials, the automatic reconnect comes back with a fresh QR on its own, so the session is
> usually already sitting at `qr_ready` rather than needing a manual start. Acknowledge the modal once
> in a browser signed in as that account, then scan the QR. It does not recur — the modal is shown
diff --git a/src/config/configuration.ts b/src/config/configuration.ts
index df4b328ee..91dc00bc7 100644
--- a/src/config/configuration.ts
+++ b/src/config/configuration.ts
@@ -62,11 +62,12 @@ export function resolveNonNegativeIntEnv(raw: string | undefined, fallback: numb
export const MAX_TIMER_MS = 2147483647;
/**
- * The UI locale Chromium is pinned to. WhatsApp Web renders its chrome — including the new-account
- * onboarding modal the whatsapp-web.js adapter dismisses (#982) — in the browser's language, and that
- * detector matches visible English text. Without a pin the language is whatever the launched binary
- * defaults to, which differs between the amd64 (Chrome for Testing) and arm64 (Debian chromium) images
- * and between host installs.
+ * The UI locale Chromium is pinned to. Without a pin the browser's language is whatever the launched
+ * binary defaults to, which differs between the amd64 (Chrome for Testing) and arm64 (Debian chromium)
+ * images and between host installs. The pin settles the browser's locale only: WhatsApp Web can still
+ * render its chrome, including the new-account onboarding modal the whatsapp-web.js adapter dismisses
+ * (#982), in the account's own language (#1679), so a non-English modal needs
+ * WWEBJS_ONBOARDING_CONTINUE_LABELS.
*/
export const PINNED_BROWSER_LOCALE = 'en-US';
diff --git a/src/engine/adapters/wwebjs-onboarding.ts b/src/engine/adapters/wwebjs-onboarding.ts
index fdcd7bad0..e02bbbe18 100644
--- a/src/engine/adapters/wwebjs-onboarding.ts
+++ b/src/engine/adapters/wwebjs-onboarding.ts
@@ -10,9 +10,10 @@ export const ONBOARDING_DEFAULT_CONTINUE_LABEL = 'Continue';
* Extra confirm-button labels for a deployment whose WhatsApp Web does not render this modal in
* 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 an operator can correct a running
- * deployment through the infra config without a restart.
+ * 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.
*
* 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
@@ -43,12 +44,13 @@ export function resolveOnboardingContinueLabels(): string[] {
* against `<body>` would just be the loose text test again.
*
* LANGUAGE. The default label and the heading are English, and the modal is rendered in whatever
- * language WhatsApp Web decides. Two things address that, both defaulting to today's behaviour:
- * the launch args pin `--lang` so the page has a deterministic locale, and an operator can add
- * their own labels (see {@link resolveOnboardingContinueLabels}). An operator-supplied label matches
- * WITHOUT the heading check — the English heading would reject a localised modal regardless, so
- * requiring both would make the setting inert. The default `Continue` keeps the heading requirement,
- * so the out-of-the-box false-positive surface is unchanged.
+ * language WhatsApp Web decides. The launch args pin `--lang=en-US`, which settles the browser's
+ * locale but not necessarily WhatsApp Web's: a deployment on a Portuguese account still reported the
+ * modal in Portuguese (#1679). Another language is covered by an operator-supplied label (see
+ * {@link resolveOnboardingContinueLabels}), which matches WITHOUT the heading check: the English
+ * heading would reject a localised modal regardless, so requiring both would make the setting inert.
+ * The default `Continue` keeps the heading requirement, so the out-of-the-box false-positive surface
+ * is unchanged.
*/
export function probeOnboardingModal(options?: { labels?: string[]; headingOptionalFor?: string[] }): {
modalPresent: boolean;
@@ -315,9 +317,10 @@ export class WwebjsOnboardingWatcher {
this.onboardingDialogSignatures.add(signature);
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 an unrecognised title or ' +
- 'language, WhatsApp will unlink this companion within minutes: add its confirm-label ' +
- 'via WWEBJS_ONBOARDING_CONTINUE_LABELS, and report the heading so detection can cover it.',
+ '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 ' +
+ 'newly linked account WhatsApp unlinks the companion within minutes while it stays open. ' +
+ 'An English onboarding screen that is not recognised is worth reporting.',
{
sessionId: this.host.config.sessionId,
dialogs,