[Feature]: BSUID and username support

[rachit-navatech]

Pre-flight

• I searched existing issues and this isn't already requested

Problem / motivation

WhatsApp is rolling out usernames and Business-Scoped User IDs (BSUIDs) starting July 7, 2026, going global by September.
The short version: phone numbers become optional. Users can hide their number behind a username, and Meta assigns each user a unique BSUID per business portfolio (e.g. US.13491208655302741918). BSUIDs are already flowing in webhooks since April 2026.
This affects OpenWA in a few ways:

• Contact lookup currently assumes phone numbers as the primary key. Need BSUID-first resolution with phone fallback.
• REST API / webhooks need to accept and return BSUIDs alongside phone numbers.
• Existing contacts need a migration path — users who enable usernames won't expose their number anymore, so phone-only workflows break.

Refs:

Meta docs on BSUIDs
Similar: whatsapp-web.js #201728, Baileys #2516

Proposed solution

No response

Alternatives considered

No response

Scope

• I understand some features are limited by the underlying WhatsApp engine (e.g. interactive Buttons/List messages are not supported on whatsapp-web.js).

[rmyndharis]

Thanks for flagging this, @rachit-navatech — good to have it on the radar ahead of the rollout. Your read on the three impact areas (contact resolution, REST/webhook surface, migration path for existing contacts) is the right breakdown.

A few thoughts from how the codebase is shaped today, so we can plan this deliberately rather than reactively:

On contact resolution going BSUID-first. The current model is two-tier — <phone>@c.us and <lid>@lid (the privacy id, per-account) — with lid_mappings bridging them. BSUID introduces a third tier that's cross-business, which is a different shape than the existing lid→phone cache. That's likely worth its own resolution table/column rather than overloading lid_mappings, since a BSUID doesn't resolve to a single phone the way a lid can. Worth scoping this out before touching the resolution path.

On the engine boundary. The good news: the anti-corruption layer at IWhatsAppEngine means we don't have to chase BSUID through every feature module. Whatever normalization we settle on can live at the adapter boundary. The thing to be careful about is not letting a raw BSUID leak past that boundary into neutral code before we know what "neutral" means for a three-identity world.

On migration / hidden numbers. This is the subtle one. A user enabling a username doesn't just "not expose" their number — it can make a previously-known phone disappear. That's a hazard for the existing lid_mappings reverse lookup and the message from filter, which could happily keep returning a stale phone and never realize it's been hidden. We'd want an explicit signal for "phone is hidden" rather than treating absence as "unknown".

On timing / where to build it. Given the upstream Baileys/wwjs support is still settling (the threads you linked are active), my instinct is to prototype BSUID resolution as a plugin first (ENGINE/EXTENSION) rather than baking it straight into the engine interface and schema. That lets us iterate on the resolution model quickly without locking the core contract before upstream stabilizes, and then promote it into IWhatsAppEngine + a schema migration once the shape is clear.

Tagging this for tracking and will follow the upstream threads. If anyone's already prototyping BSUID resolution, happy to coordinate so we don't end up with two divergent implementations.