Username
Overview
WhatsApp is introducing usernames — an optional feature that allows users to hide their phone number and communicate using a username instead (similar to Telegram). This is being rolled out gradually, starting late-2026. This is a critical update. If your system relies on phone numbers as the primary identifier for incoming messages, you must adapt your integration to support the new user id field
What Is This Feature?
Meta is allowing WhatsApp users who opt in to hide their phone number by choosing a username (e.g. @john.smith). Once a user enables this, their communication with new contacts and businesses will use this hidden identity.
Key point: This is an opt-in feature. Users who don’t adopt a username will continue to work exactly as they do today — no changes to your integration are required for those users.
What Changes in Your Webhooks?
Currently, when you receive an incoming message via webhook, the sender’s phone number is included in the payload (in the “from” field). Once a user enables usernames, these phone number may be hidden and you will get a user id instead which is two digits country code + dot + 16 digits.
The phone number will still appear in your webhooks if you sent or received a message with this user’s phone number within the last 30 days (evaluated per business phone number).
Understanding the user id
The user id is the new primary identifier for WhatsApp users. Think of it as the replacement for the phone number as your “primary key.”
Format
The id consists of an ISO country code, a period, and a long numeric string. For example: IL.45634521792468
The country code prefix lets you identify the user’s country of origin (e.g. IL = Israel, US = United States). you can also use the "country" parameters that arrives in the webhook.
Key characteristics
• Automatically generated by Meta — you don’t create or manage them.
• Always present in webhooks, for every user, regardless of username adoption.
• Permanent and stable — it will not change
• Scoped to your business: The same end user will have a different user id for each business they interact with. You cannot use the user id from one business phone number to message the user from another business. Important: The USER ID is tied to your specific WhatsApp API line. If you have multiple lines and the same user contacts both, they will have a different USER ID on each line.
Sending Messages
you use the "to" field the same way as you use before. you can now deliver both the international phone number or the user id.
If you already know the user’s phone number, you can still send messages using the phone number — even if the user has enabled usernames. The username feature does not block outbound messages to known phone numbers.
Frequently Asked Questions
Q: Can I send a message to a username (e.g. @john.smith)?
A: No. Via the API, you can only send messages using a phone number or a user id. Usernames are for display and for person-to-person communication within the WhatsApp app. Users can search for each other by username in the app, but the API does not support addressing messages to a username.
Q: If I already know a user’s phone number and they enable usernames, can I still message them?
A: Yes. The username feature does not block messages sent to a known phone number. If you have the user’s phone number from any source (a call, a form, a previous conversation), you can continue messaging them exactly as you do today.
Q: Will I still see the phone number for users who previously chatted with me?
A: If the user interacted with your line after April 1, 2026, their phone number will be present permanently. You will continue to see their phone number in all webhooks, even if they later enable usernames. The phone number is also included if you had any interaction within the last 30 days.
Q: Can I use the same user id across different WhatsApp API lines?
A: No, the user id is scoped to the portfolio level. If you have lines in different portfolios, the same user will have a different user id on each. Note: user id is permanent and will never change (unlike the username, which the user can modify). The user cannot see or control their user id.
Q: Can a user hide their phone number without setting a username?
A: No. Based on the current implementation, a user must adopt a username to hide their phone number. There is no standalone “hide phone number” toggle without a username. However, having a username does not automatically hide the phone number from your webhooks — the 30-day and previous interaction still applies.
Q: What happens to the user’s display name (profile name)?
A: The profile name is always present in webhooks, regardless of username adoption. It is not affected by this feature.
This document will be updated when more information will be present.
Please note that sending messages using a User ID in the "To" field may not be supported across all WhatsApp accounts, as this feature is currently undergoing updates by Meta.