Skip to content

WhatsApp Usernames

Also called: WhatsApp username · Usernames on WhatsApp · WhatsApp user handles

Definition
Handles that WhatsApp users can adopt in 2026 so others reach them without seeing their number, changing how businesses identify and record customers.

Exhibit A

Scrub through the usernames rollout

6 / 6

H1 2027Coming upEvent 6 of 6

WhatsApp account IDs

A new Graph API version brings WhatsApp account IDs and endpoints alongside phone number IDs.

Key dates for usernames and the business-scoped IDs that come with them, from BSUIDs in webhooks to the new account IDs. Move the scrubber to see what each step changes for a business.

Event 6 of 6: H1 2027 — WhatsApp account IDs (coming up). A new Graph API version brings WhatsApp account IDs and endpoints alongside phone number IDs.

What is WhatsApp usernames?

WhatsApp usernames are handles that WhatsApp users can choose so that other people can find and message them without knowing, or seeing, their phone number. Meta is rolling them out to users gradually during 2026. For people it is a privacy feature; for businesses on the WhatsApp Business Platform it changes something basic, because the phone number has always been how a customer is identified in webhooks, CRMs and consent logs.

Once a user turns on a username, Meta can omit their phone number from the webhooks a business receives, both the wa_id in contacts and the from on messages. The number is still included if the business and the user messaged or called each other within the last 30 days, or if the user is in the business's contact book. What is always present is the business-scoped user ID (BSUID), in contacts[].user_id and messages[].from_user_id, which webhooks have carried since early April 2026. It is scoped to the business portfolio and is regenerated, with a user_id_update webhook, when the user changes phone number.

User usernames are different from a business username, the handle a business reserves for itself so customers can find it, which businesses could reserve, adopt or change from 29 June 2026. This page is about the customer's username and what a business must change to keep recognising customers who hide their numbers. Meta is also adding the ability to send messages by BSUID, so a business can reply to a username user it has no number for.

Key takeaways

  • WhatsApp usernames let users be reached by a handle instead of a phone number; Meta is rolling them out gradually through 2026.
  • When a user enables a username, their phone number can be left out of your webhooks.
  • The number still appears if either side messaged or called in the last 30 days, or the user is in your contact book.
  • The business-scoped user ID (BSUID) is the stable key that arrives either way, so CRMs and consent records must store it.
  • Business usernames, the business's own handle, are a separate feature that opened on 29 June 2026.

Why does WhatsApp usernames matter?

A business that keys everything on phone numbers will start losing customers into duplicate records as usernames spread: a known buyer writes in after two months, the webhook has no number, and the inbox treats them as a stranger. Worse for compliance, an opt-out recorded against a phone number may not be matched to the same person arriving with only a BSUID. Adding the BSUID to customer records, consent logs and routing now, while most webhooks still carry both IDs, avoids a painful clean-up later.

How does WhatsApp usernames work?

  1. A user adopts a username

    In the WhatsApp app the user picks a handle. Other people, and businesses, can now be contacted by or contact them without the number being shown.

  2. Webhooks may drop the number

    For that user, wa_id and from can be absent from your webhooks, unless you exchanged messages or calls within 30 days or the user is in your contact book.

  3. The BSUID is always there

    contacts[].user_id and messages[].from_user_id carry the BSUID, in the form of a country code, a dot and up to 128 alphanumerics.

  4. Match on either key

    Look a customer up by wa_id first, then by BSUID; store both whenever both are present so later events with only one still match.

  5. Handle changes

    When the user changes phone number, Meta issues a new BSUID and sends a user_id_update webhook. Update the stored key instead of creating a new customer.

Example: A returning customer with no number

A Jaipur jewellery brand's regular buyer switches on a username in August. In October, three months after her last chat, she messages about a repair. The webhook carries her BSUID but no wa_id, because more than 30 days have passed and she is not in the brand's contact book. The brand's CRM had stored her BSUID next to her number since April, so the message lands in her existing thread with her purchase history, and her earlier opt-out from promotional offers still applies.

WhatsApp usernames in code

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "{WABA_ID}",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "919876543210", "phone_number_id": "{PHONE_NUMBER_ID}" },
        "contacts": [{ "profile": { "name": "Meera" }, "user_id": "IN.7Hq2Lk9ZpW4xRt3V" }],
        "messages": [{
          "from_user_id": "IN.7Hq2Lk9ZpW4xRt3V",
          "id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAEhgUM0E5QjRDN0Y",
          "timestamp": "1760851200",
          "type": "text",
          "text": { "body": "Hi, can you repair a clasp?" }
        }]
      }
    }]
  }]
}

No wa_id and no from: only the BSUID identifies the customer.

Common mistakes with WhatsApp usernames

  • Making phone number a required column

    Schemas that reject a contact without a number will drop username users. Make the number optional and require the BSUID instead.

  • Losing opt-outs

    An opt-out stored only against a phone number will not match a later message carrying only a BSUID. Record consent against the customer, linked to both IDs.

  • Sharing BSUIDs across portfolios

    A BSUID is scoped to one business portfolio. A group with two portfolios sees two different BSUIDs for one person, so do not use it as a cross-company key.

  • Confusing user and business usernames

    Reserving your business's handle does nothing for matching customers. The two features are separate and need separate work.

WhatsApp Usernames FAQs

Will businesses still see customers' phone numbers?+
Often, but not always. A user with a username can arrive without a phone number unless you messaged or called within 30 days or they are in your contact book; the BSUID always arrives.
What is the difference between a WhatsApp username and a business username?+
A WhatsApp username is a customer's personal handle; a business username is the handle a business reserves so people can find it. Business usernames opened on 29 June 2026, while user usernames roll out through 2026.
How should opt-in records handle WhatsApp usernames?+
Record consent against the customer and link it to both the phone number and the BSUID. That way an opt-in or opt-out still applies when a later message carries only one of the two.
Can I message a username user who has no number on file?+
Only by BSUID, which Meta is adding to the Cloud API through a recipient field. Check that it is enabled for your account before building on it, and keep the phone number whenever a webhook still includes it.

Best practices for WhatsApp usernames

  • Backfill BSUIDs now from webhooks that carry both IDs.
  • Add the business number to customers' contact books where they ask you to; it keeps the number visible.
  • Show agents the BSUID-linked history so they do not ask regulars to re-identify.
  • Subscribe to user_id_update and test it before usernames are common.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms