Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(baileys): default the linked-device name to Ubuntu for pairing codes (#1857)
Yoosuf Haffejee180e5aa6df0c
diff --git a/.env.example b/.env.exampleindex 0027a833d..8e49e458f 100644--- a/.env.example+++ b/.env.example@@ -225,9 +225,9 @@ OPENWA_PIDS_LIMIT=2048# still announces per-chat presence for that call.# BAILEYS_MARK_ONLINE_ON_CONNECT=true# Device name shown in WhatsApp Settings → Linked Devices for NEW pairings (existing sessions keep-# the name they were paired with until re-linked). Default: OpenWA. It is also carried into the+# the name they were paired with until re-linked). Default: Ubuntu. It is also carried into the# phone-number pairing request: some accounts reject a non-standard name with a generic "check the-# phone number" error, so set it to a standard OS name like Ubuntu if phone-number pairing keeps failing.+# phone number" error, so keep a standard OS name like Ubuntu if you use phone-number pairing.# BAILEYS_BROWSER_NAME=# Pin a specific WhatsApp Web protocol version for the Baileys engine (e.g. 2.3000.1045340097).# Leave unset (default) for automatic multi-tier resolution (live WA Web endpoint -> upstream Defaults -> local cache -> safe fallback).diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ac49af93b..f916e9e0e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -33,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Retire the whatsapp-web.js download-mimetype install patch; inbound media downloads now pass the mimetype themselves.- Storage import abort messages name the `STORAGE_IMPORT_MAX_BYTES` or `STORAGE_IMPORT_MAX_ENTRIES` setting that stopped them.- CI and the weekly security scan run `npm audit` over the JavaScript SDK, and Dependabot watches its lockfile.+- The Baileys linked-device name defaults to `Ubuntu` instead of `OpenWA`, so phone-number pairing works without setting `BAILEYS_BROWSER_NAME`.### Fixed@@ -148,6 +149,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- With `OPENWA_DATA_DIR` set, `backup.sh` and `restore.sh` read the default SQLite databases and `./data/...` paths in `./.env` under it; pass a path in the environment to keep it in the working directory.- A storage import stops at `STORAGE_IMPORT_MAX_TOTAL_BYTES` (default 10 GiB); raise it before importing a larger export.- Baileys answers `400` for an animated sticker with more than 500 frames.+- New Baileys pairings appear as `Chrome (Ubuntu)` in Linked Devices; set `BAILEYS_BROWSER_NAME=OpenWA` to keep the old name. Linked sessions are unaffected.- `backup.sh` and `restore.sh` exit with status 2 when `./.env` or `.env.generated` sets a key in a form they cannot parse; fix the line or pass the key in the environment.- With `DATABASE_SSL=true`, `backup.sh` now fails against a PostgreSQL server whose certificate the app would reject; trust a private CA through `NODE_EXTRA_CA_CERTS` or `PGSSLROOTCERT`, and give `DATABASE_URL` the host name the certificate carries or set `PGSSLMODE`.diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex 0d9c424ed..119f47108 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -281,11 +281,12 @@ change will come from the engine libraries implementing the step.- Linking the same account by QR works**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 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`.+non-standard one. The default device name is `Ubuntu`; if `BAILEYS_BROWSER_NAME` is set to a custom+brand, set it back to `Ubuntu` (or another standard OS name like `macOS` or `Windows`),+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`.### Issue: No QR code appears, or `POST /api/sessions/:sessionId/start` returns `504`diff --git a/docs/28-multitenancy.md b/docs/28-multitenancy.mdindex 457a42cb1..8536495b4 100644--- a/docs/28-multitenancy.md+++ b/docs/28-multitenancy.md@@ -119,7 +119,7 @@ without schema change.- **Linked-device identity**: the engine's browser display name (the `BAILEYS_BROWSER` tuple)resolves per session: `session.config.browserName` → `tenant.branding.deviceName` → global- `BAILEYS_BROWSER_NAME` env → `'OpenWA'`. This supersedes the global-only env approach for+ `BAILEYS_BROWSER_NAME` env → `'Ubuntu'`. This supersedes the global-only env approach forwhite-label tenants while keeping a global fallback.- **Dashboard**: `tenant.branding` (display name, logo URL, optional accent color within theexisting token system) applied at login and in the shell; global defaults when absent.diff --git a/docs/examples/session-phone-number-pairing.md b/docs/examples/session-phone-number-pairing.mdindex ff55e4ee9..45af2dee2 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.-- On the Baileys engine, 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. whatsapp-web.js does not send the `OpenWA` device name and never reads `BAILEYS_BROWSER_NAME`, so the variable has no effect there.+- On the Baileys engine, 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 device name is carried into the pairing request, and some accounts reject a non-standard one. The default is `Ubuntu`; if `BAILEYS_BROWSER_NAME` was set to a custom brand, set it back to `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. whatsapp-web.js does not send this device name and never reads `BAILEYS_BROWSER_NAME`, so the variable has no effect there.- 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/engine/adapters/baileys-lifecycle.ts b/src/engine/adapters/baileys-lifecycle.tsindex a5f563c60..183104f25 100644--- a/src/engine/adapters/baileys-lifecycle.ts+++ b/src/engine/adapters/baileys-lifecycle.ts@@ -29,10 +29,11 @@ import type { BaileysHistory } from './baileys-history';import type { BaileysSessionStore } from './baileys-session-store';import { userPart } from '../identity/wa-id';-/** Linked-device identity shown in WhatsApp (Settings → Linked Devices). The display name is- * operator-brandable via BAILEYS_BROWSER_NAME; it only applies to pairings made after the change. */+/** Linked-device identity shown in WhatsApp (Settings → Linked Devices). The OS platform is+ * operator-configurable via BAILEYS_BROWSER_NAME; defaults to canonical 'Ubuntu' so pairing-code+ * (link-code) companion registration passes WhatsApp server-side validation. */const BAILEYS_BROWSER: [string, string, string] = [- process.env.BAILEYS_BROWSER_NAME?.trim() || 'OpenWA',+ process.env.BAILEYS_BROWSER_NAME?.trim() || 'Ubuntu','Chrome','120.0.0',];