Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(wwebjs): correct the onboarding-modal locale guidance
Yudhi Armyndharisc5e20f6b2077
diff --git a/.env.example b/.env.exampleindex 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.mdindex 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.### Dependenciesdiff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex 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 adapterand only gives up after five clicks that fail to land — at that point a human must click through itonce, 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 showndiff --git a/src/config/configuration.ts b/src/config/configuration.tsindex df4b328ee..91dc00bc7 100644--- a/src/config/configuration.ts+++ b/src/config/configuration.ts@@ -62,11 +62,12 @@ export function resolveNonNegativeIntEnv(raw: string | undefined, fallback: numbexport 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.tsindex 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,