← Back to Blog
product-update byon bsuid whatsapp-usernames webhooks api-v2

WhatsApp Usernames Are Here: BSUID Support and BYON API v2

Ler em português →

Short version: WhatsApp is rolling out usernames. Once a user adopts one, Meta may stop sending their phone number in your webhooks and send a BSUID (business-scoped user ID) instead. If your bot keys users by phone number, those messages break. PipesBot now handles BSUIDs on every BYON App, and we’re launching BYON API v2, which hands you Meta’s payloads untouched. All App webhooks are now signed.

What Meta is changing

WhatsApp is adding usernames country by country through 2026. Along with that, every user gets a BSUID, one per business portfolio, whether or not they have a username. It looks like US.13491208655302741918 (country code, a dot, then up to 128 alphanumerics).

Meta omits the phone number from a webhook when all three of these are true:

  1. The user has a username.
  2. Your business number hasn’t messaged with them in the last 30 days.
  3. They aren’t in the Meta-hosted contact book.

When that happens, messages[].from and contacts[].wa_id are simply missing, not empty, and new fields carry the identity instead: from_user_id, contacts[].user_id and profile.username. Statuses get recipient_user_id and may drop recipient_id.

Meta hasn’t given a cutoff date, but says supporting this is mandatory and that there’s no recourse for messages a business can’t process. A bot that does users[message.from] will receive a message with no from and either crash or reply to nobody.

What PipesBot does now

On every BYON App (legacy included)

You don’t have to change anything to keep receiving messages from username users:

  • fromNumber, from and wa_id hold the BSUID when there’s no phone number.
  • The contact gains user_id, parent_user_id and profile.username. WebSocket whatsapp_message events gain userId, parentUserId and username.
  • You can reply to a BSUID with the same toNumber / to field you use today.
  • Replies over WebSocket now go to the contact stored on the conversation, not to whatever number the client sent.

BYON API v2: Meta’s data, untouched

The legacy API reshapes Meta’s webhooks into a PipesBot format and tracks a conversationId per sender. That model assumed a phone number is a stable key, and BSUIDs break that assumption. So v2 drops the reshaping:

LegacyAPI v2
InboundPipesBot-shaped payload + conversationIdOne envelope per Meta change, with Meta’s change.value as-is
ConversationsStored per senderNone. Nothing to keep in sync
StatusesNot deliveredsent, delivered, read, failed
Other Meta fieldsTemplate status onlyEvery change Meta sends for your numbers
SendingtoNumberto (phone or BSUID), or recipient in passthrough

A v2 webhook looks like this:

{
  "id": "evt_3f9c1a7b2d4e4f6a8b0c1d2e3f4a5b6c",
  "field": "messages",
  "createdAt": "2026-10-08T10:30:01.123Z",
  "pipes": { "appId": "app_xyz789", "poolNumberId": "pn_123", "media": {} },
  "whatsapp": {
    "messaging_product": "whatsapp",
    "contacts": [{ "user_id": "US.13491208655302741918", "profile": { "name": "Ana", "username": "ana.costa" } }],
    "messages": [{ "from_user_id": "US.13491208655302741918", "id": "wamid...", "type": "text", "text": { "body": "Hi!" } }]
  }
}

New Apps are created on v2. Existing Apps upgrade from Settings → Upgrade to API v2. The upgrade is one-way: it deletes stored conversations and legacy queued messages, and reconnects your WebSocket clients. Your webhook URL, keys, numbers and WhatsApp history stay the same. The v2 migration guide has the full checklist.

How to key your users

Treat the BSUID as the user’s identity and the phone number as an optional attribute you may learn later:

function userKey(message: { from?: string; from_user_id?: string }) {
  return message.from_user_id ?? message.from;
}

This is for v2, where you get Meta’s raw messages[]. On legacy, fromNumber holds the phone when Meta sends one and the BSUID when it doesn’t, so the same user can show up under two values. Key on the contact’s user_id instead, and fall back to fromNumber only when it’s missing.

Two edge cases to handle:

  • BSUIDs change when a user changes phone number. Meta sends a system message (user_changed_number or user_changed_user_id) with previous_user_id. Use it to move your records to the new id.
  • Some templates need a real phone number. One-tap, zero-tap and copy-code authentication templates fail with error 131062 when Meta only has a BSUID. Ask for the number first with a REQUEST_CONTACT_INFO button or interactive message; the user chooses whether to share it.

Signed webhooks for every App

App webhooks were unsigned until now. Every delivery to an App webhook URL (messages, template status, number.onboarded) is now signed with Standard Webhooks: webhook-id, webhook-timestamp and webhook-signature headers, with a per-App whsec_ secret you can reveal and rotate in the dashboard.

import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.PIPES_WEBHOOK_SECRET!); // whsec_...
const event = wh.verify(rawBody, headers); // throws on bad signature or stale timestamp

On v2, webhook-id equals the envelope id, which is also the key to dedupe on: deliveries are at-least-once, and the same event can reach you over both webhook and WebSocket. More in Webhook Security.

What to do this week

  1. Find every place your code uses the phone number as a user key and add the BSUID fallback above.
  2. Verify webhook signatures.
  3. Plan the move to API v2 if you’re still on legacy. It’s the format that keeps working as Meta adds fields.

If you’re new to webhooks for AI agents on WhatsApp, start with our webhooks guide. Meta’s own reference is Business-scoped user IDs.