Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(baileys): default the linked-device name to Ubuntu for pairing codes (#1857)

Yoosuf Haffejee180e5aa6df0c
diff --git a/.env.example b/.env.example
index 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.md
index 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.md
index 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.md
index 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 for
white-label tenants while keeping a global fallback.
- **Dashboard**: `tenant.branding` (display name, logo URL, optional accent color within the
existing 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.md
index 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.ts
index 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',
];