(Meta and Gupshup implementation)

Introduction & Summary

Meta is letting WhatsApp users hide their phone number behind a username — similar to Instagram or Telegram. When that happens, instead of a phone number, your business will receive a different identifier called a BSUID (Business-Scoped User ID).

HELPFUL LINKS -

Partner API to enable the BSUID flag at an app level
Payload Samples for All Webhooks
Sending message to BSUID (coming soon)
Requesting contact info template and session (coming soon)
Reserving Business username (coming soon)

SUMMARY FOR THOSE WHO WILL CONTINUE TO RELY ON PHONE NUMBER -

The username feature will only apply to users who actively choose a username, which Meta starts rolling out in H2 2026 — and even then, phone numbers will still flow through for everyone you've recently interacted with, due to Meta and Gupshup’s Contact Book. Exception being - C2WA and other such first time interaction.

On the Gupshup side, we've already done the heavy lifting. Our platform handles BSUID internally and continues to expose phone numbers to you wherever possible. For most of your existing flows — campaigns, transactional sends, customer support no change is needed, as long as you have the phone number.

SUGGESTION :
By default, when a brand-new user pings your business (via direct message or CTWA ad) without a phone number, these messages will be parked and held at Gupshup for a maximum of 30 days period. We are also planning to provide an API to help you retrieve such messages, so you can consider them in your lead bucket. You can prompt them with a Request Contact Info CTA (via template or an interactive message), to continue capturing their phone number. Once a phone number is shared, you can continue to move them to the regular bucket of users to initiate further conversation with the user.

SUMMARY FOR THOSE WHO WANT TO INTEGRATE BSUID-

These businesses / partners must enable the ‘BSUID in webhook’ flag. Thus, if username is adopted: if no phone number is present you will receive only the BSUID. You can use either BSUID or phone number both to send messages.

SUGGESTION
Using phone numbers is recommended to ensure contact book synchronization while sending messages. By default, when a brand-new user pings your business (via direct message or CTWA ad) without a phone number, you can automatically prompt them with a Request Contact Info CTA at the start of the interaction, to continue capturing their phone number. Once a phone number is shared, you can continue to move them to the regular bucket of users to initiate further conversation with the user.

SUMMARY OF MESSAGING

End-user adoption of Username
This is purely WhatsApp Consumer App behaviour and cannot be managed. Meta will enable it geo-by-geo post June 29. It may start in limited countries (not announced by Meta as on June 20) such that WhatsApp end users will get the ability in their app to set username in their app. Refer ‘Username Adoption by End user’ section below for details
For receiving all messages and outgoing msg status webhooks-
Fixed identifier will be BSUID (Business scoped user ID). Phone number as an identifier may depend on several factors. Refer more details below

ALL OUTGOING MSG STATUS & INCOMING MESSAGE WEBHOOKS IF END USER DID NOT ADOPT USERNAME -
No change from today. You will receive the phone number and BSUID both in outgoing msg status and incoming message webhooks.
(This behaviour is irrespective of whether you enabled the flag to receive BSUID in webhooks)

OUTGOING MSG STATUS WEBHOOKS IF END USER ADOPTED USERNAME -
Factors for receiving phone number -
(This behaviour is irrespective of whether you enabled the flag to receive BSUID in webhooks)
A. If message was sent to a phone number, thus it will show in outgoing msg status webhooks with phone number
OR
B. If message was sent to BSUID and it exists in Meta contact book, it will show in outgoing msg status webhooks with phone number
OR
C. [GUPSHUP IMPLEMENTATION] If message was sent to BSUID and it exists in Gupshup contact book, it will be passed on to Meta with phone number, thus it will show in outgoing msg status webhooks with phone number

Pending cases for receiving ONLY BSUID and no phone number -
A. [GUPSHUP IMPLEMENTATION] If message was sent to BSUID and it does not exist in Gupshup contact book, it will be passed on to Meta with BSUID
AND
B. If you have enabled the flag at app level, to receive BSUID-only webhooks
NOTE : If B is not done, the BSUID-only status webhooks will be dropped at Gupshup - to ensure your system doesn't break without the phone number. There will be no way to retrieve them.

Alert : Today’s behaviour vs Future
As of 20th June, you are receiving all outgoing msg status webhooks, and getting them with a phone number (and BSUID, if enabled), because username adoption by end-users is not live. This behaviour may not hold true once username adoption for end-users becomes live. Refer end-user adopted username to know how it will change

INCOMING MESSAGE WEBHOOKS IF END USER ADOPTED USERNAME -

Factors for receiving phone number-
(This behaviour is irrespective of whether you enabled the flag to receive BSUID in webhooks)
A. You have messaged or called the user’s phone number within the last 30 days of the webhook being triggered
OR
B. You have received a message or call from the user’s phone number within the last 30 days of the webhook being triggered
OR
C. The user is in your Meta contact book
OR
D. [GUPSHUP IMPLEMENTATION] The user is in your Gupshup contact book

Pending cases for receiving ONLY BSUID and no phone number -
A. User and business have never interacted with each other using the phone number since April 2026 such as CTWA, user initiated first interaction, etc - that does not exist in Meta or Gupshup contact book and has not agreed to share phone number through request_contact_info
AND
B. If you have enabled the flag at app level, to receive BSUID-only webhooks
NOTE : If B is not done, the BSUID-only message webhooks will be parked in Gupshup for 30 days - to ensure your system doesn't break without the phone number. Gupshup will provide the support to retrieve them in near future. The parked messages will be charged at regular per message fee, if applicable.

3. For sending service messages or utility/marketing templates -
(This behaviour is irrespective of whether you enabled the flag to receive BSUID in webhooks and whether end-user adopted username)
Can be sent with either BSUID OR Phone number. Sending messages to phone numbers is recommended, primarily so you can continue to receive phone numbers in webhooks and they get added to your Meta and Gupshup contact book.
[GUPSHUP IMPLEMENTATION] If message was sent to BSUID and it exists in Gupshup contact book, it will be passed on to Meta with phone number

4. For sending authentication templates -
(This behaviour is irrespective of whether you enabled the flag to receive BSUID in webhooks and whether end-user adopted username)
Must be sent to Phone number. Message sent to BSUID will fail. These will continue to receive phone numbers in webhooks and they get added to your Meta and Gupshup contact book.

5. Other BSUID related webhooks -
(This behaviour is irrespective of whether you enabled the flag to receive BSUID in webhooks and whether end-user adopted username)
A. You will receive a webhook when phone number of an end user changes. Now the new phone number will need to be mapped.
B. All other webhook updates (Coex, Voice, User preferences, Block User etc). Read the technical implementation below to know more
C. Block user APIs will also work with BSUID instead of phone number

6. Requesting phone number
Template creation, template sending on v2 and v3 apis & interactive session message sending with this button will be supported in Gupshup. Refer below for more details.

SUMMARY OF BUSINESS USERNAME

For setting business username -
(This behaviour is irrespective of whether you enabled the flag to receive BSUID in webhooks and whether end-user adopted username)

We encourage businesses to start planning their WhatsApp Business username strategy now so you're ready when the feature becomes available.
This feature will be supported on Gupshup once Meta goes GA after June 29. Refer below for more details.

Key components -

Username adoption by end-users

A user username is a unique, optional name that WhatsApp users can set in order to display their username instead of their phone number in the app.

Users can adopt @username from WhatsApp Settings > Profile > Username (similar to Instagram).

Meta Implementation (in testing as on 20th June 2026, GA planned in Q3 2026)

Meta will enable it geo-by-geo post June 29. It may start in limited countries (not announced by Meta as on June 20)

IMPACT -

When a user adopts a username, their phone number is hidden by default from businesses they have not previously interacted with. Users can still voluntarily share their phone number via a Meta-provided "Request Contact Info" CTA button or by typing it.
If a user changes their phone number, their BSUID also changes. Meta sends a system event so businesses can update their records.
Usernames can be used in lieu of profile names when personalizing message content for individual users.
WhatsApp users are limited to 1 username, but are able to change them periodically. Changing a username does not affect the user’s phone number or business-scoped user ID, and does not affect the user’s ability to communicate with other WhatsApp users or businesses on the WhatsApp Business Platform.
User usernames have the same format restrictions as business usernames.

Gupshup Implementation (not required)
There is no separate implementation needed for end-user adoption of usernames as it is a WhatsApp App feature. This is purely WhatsApp Consumer App behaviour and cannot be managed.

3. BSUID and username related fields

To support end-user usernames, Meta will share a new backend user identifier called business-scoped user ID, or BSUID. BSUID uniquely identifies a WhatsApp user and is tied to a specific business (at BM level). A BSUID is a unique user identifier that can be used to message a WhatsApp user when you don’t know their phone number.

Meta Implementation (Generally available since April 2026)

BSUID Rollout is now 100% complete for all users globally by Meta.

IMPACT :

It means that a BSUID is being generated for each brand<>user combination on the platform
It means that Meta will always generate a BSUID for an end-user and pass it along with the phone number irrespective of whether the end-user adopted username or not
Once username adoption becomes generally available, and if user adopts username, Meta will omit the phone number field and only pass the BSUID.
If a WhatsApp user enables the username feature, their phone number (and thus, country dialing code) may not appear in webhooks. In these cases, business can refer BSUID prefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code (for example, US.13491208655302741918).
BSUIDs will be generated automatically
They will be prefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code and a period, followed by up to 128 alphanumeric characters (for example, US.13491208655302741918)
It will be regenerated if a user changes their phone number (which trigger a system messages webhook)
If you are a managed business (multiple BMs) - Meta has the concept of ‘Parent BSUID’ which can be used to identify the end-user across all BMs of a large business. If you want to enroll your business portfolios to receive parent BSUIDs, you can ask your Meta point-of-contact to check if you are eligible.

Gupshup Implementation (supported since April 2026)

For Incoming Webhooks

Default Behaviour (If you want to continue relying only on the phone number)
By default, Gupshup passes only the phone number and skips the user_id related new fields, without BSUID on v2 and v3 subscriptions. Thus, No changes are required on your side.

On-Demand Behaviour (Optional if you want to store BSUID along with Phone number)
For partners who want to start working with usernames early, we have provided an optional capability to include the BSUID related fields in v2 and/or v3 subscriptions.
CHANGE ONCE USERNAME ADOPTION BEGINS :
Selected behaviour for incoming messages and outgoing msg status webhooks will continue even once username adoption begins for an end-user. Refer below change to understand how they will work.

	Default behaviour	On-Demand Behaviour (enable BSUID in webhook flag)
Username not adopted (incoming message comes with phone number)	Messages will be forwarded to your webhook with phone number only, no BSUID	Messages will be forwarded to your webhook with BSUID and phone number
Username adopted (incoming message comes without phone number)	Messages will be parked for 30 days and not be forwarded to your webhook. They will still be charged Gupshup fee, as applicable	Messages will be forwarded to your webhook with BSUID, no phone number
Username not adopted (outgoing msg status webhook comes with phone number)	Status webhooks will be forwarded to your webhook with phone number only, no BSUID	Status webhooks will be forwarded to your webhook with BSUID and phone number
Username adopted (outgoing msg status webhook comes without phone number)	Status webhooks (for outgoing msg) will NOT be forwarded to your webhook and cannot be retrieved.	Status webhooks will be forwarded to your webhook with BSUID, no phone number

How to enable/disable the on-demand ‘enable BSUID in webhook flag’ related fields

Through gupshup.ai interface (Follow steps at the bottom)
OR through Partner API to enable the BSUID flag at an app level
COMING IN JULY 2026 : Partner API to enable/disable BSUID for partner’s new and existing apps at once.
COMING IN Q3 2026 : Method to retrieve parked incoming messages for up to 30 days

Refer technical implementation section below for more details

4. Sending message to BSUID instead of phone number

Businesses will be able to send messages using a phone number, a BSUID, or both. If you provide both, the system prioritizes the phone number, but you have the flexibility to use just one of these identifiers depending on your preference.

Meta Implementation (in testing as on June 15, 2026)

Send messages with BSUID will start geo-by-geo, starting with limited countries in end of June 2026 wherever end-username adoption becomes generally available.

IMPACT :

You can include both to (phone number) and recipient (BSUID or parent BSUID) in your request. If you do, to (phone number) will take precedence - irrespective of whether the bsuid is correct or wrong. If you prefer, you can also use one or the other
Send message response will return the user’s phone number, if the message was sent to the user’s phone number and will return the user’s BSUID or parent BSUID, if it was sent to their BSUID or parent BSUID.
Does not work for Authentication templates

Gupshup Implementation (in testing as on June 15, 2026)
Send messages with BSUID will be supported by Gupshup once Meta allows, through Gupshup V2 and V3 endpoints.

For sending message -

With Phone Number : no change, it will be allowed
With BSUID :
Default Behaviour
By default, Gupshup will first check in Gupshup contact book, if the phone number is available. If found, then it will send message only to the phone number and skip the BSUID. Thus, it will get added to Meta contact book + Gupshup contact book + outgoing msg status webhooks will come with phone number

On-Demand Behaviour (Optional if you want to get BSUID along with Phone number in outgoing msg status webhooks)
This is same as mentioned under ‘BSUID and username related fields’

Read the technical implementation below to know more

5. Username Adoption by Businesses:

Meta Implementation (in testing as on June 20, 2026)

Business usernames provide a unique identifier for your business on WhatsApp, mapping to a single phone number without hiding it. This is currently in testing for limited allowlisted wabas at Meta. Meta will soon allow business to start with ‘Reservation’ before final ‘approval’ implementation in these geographies.

Business usernames must adhere to the following format:

may only contain English letters (a-z), digits (0-9), period (.) and underscore (_) characters
non-English characters (such as ñ, é, ü) are not supported and will cause the request to fail
must be between 3-35 characters in length
must contain at least one English letter (a-z, A-Z)
must not start or end with a period or have 2 consecutive periods
must not start with www
must not end with a domain (for example, .com, .org, .net, .int, .edu, .gov, .mil, .us, .in, .html, and so on)
case is ignored when comparing usernames, but period and underscore characters are not; for example, myID and myid are the same username but myid, my.id, and my_id are all distinct

Key Features:

Profile Update & Discovery : Once approved and usernames become available in your country, the business username will start appearing on your business profile, and users will be able to search for it using exact match search. This feature will go live in the same geos where End-user adoption will go live. Which means that - when end-users in a certain country will get the option to set username, around the same time - the business’ username (if adopted) from that country will become live too for those users.
Display Priority: In chat windows, usernames appear in the name with lower priority than saved names or verified business names. The following priority will be followed (in decreasing order of priority) for displaying business profile information in chat windows in the app.
- Saved contact name
- Verified business name or Official Business Account name
- Username
- Phone number
Phone number always visible : If you adopt a business username, however, it will not cause your business phone number to be hidden in the WhatsApp or WhatsApp Business client.
Unique username for each phone number : A business username is mapped to a single business phone number across all of WhatsApp; that is, a phone number can have only one username at a given time, and no two WhatsApp phone numbers (consumer or business) can have the same username. It means that multiple phone numbers in a BM will need to adopt different usernames.

How it will work:

Reservation of a Business Username.:
There are 2 methods to reserve a business username once Meta goes live for your country -
A. Meta’s Suggestions : Meta has already reserved certain names on behalf of businesses basis -
i. Existing WhatsApp Display Names.
Ii. WhatsApp Official Business Accounts.
Iii. Meta Verified business names.
iv. Linked Facebook Page and Instagram Business account handles.

These usernames have a higher chance of approval. You can select one of the suggested usernames.

B. Custom Business Username : Alternatively businesses can claim their own custom username and get it reserved.

TIP : Business username changes are limited (similar to consumer usernames). Plan carefully — don't iterate frequently. Business can update the username only twice in 14 days rolling period

Approval of a Business Username :

Once Meta approves your reserved username, a new business_username_update webhook will trigger whenever a username's status changes.
- approved — Indicates the username is approved and visible to WhatsApp users. Triggered when the username’s status changes from reserved to approved, or the username was changed via the WhatsApp Business app.
- deleted — Indicates the username has been deleted via the WhatsApp Business app.
- reserved — Indicates the username is reserved for the business phone number but is not visible to WhatsApp users. It will become visible once the usernames feature is made available to everyone.

Support

Use the Meta Report Abuse channel via Direct Support⁠ to report impersonation.
Use the WhatsApp Intellectual Property Contact Form⁠ form to report infringement.

Actions to take now (prep checklist)

Align on your desired WhatsApp Business username
TIP : Tech providers must inform their business customers on this

● Confirm if you plan to use your current WhatsApp Business display names, or if

applicable, your Meta Verified business names, or your active Instagram or Facebook

business handles. This is a great opportunity to have your business name prominently

displayed on your WhatsApp accounts.

● If you have multiple WhatsApp accounts, evaluate what you want your branding

strategy to be. WhatsApp Business usernames are unique to your WhatsApp business

account and you can have one WhatsApp Business username per phone number.

● If you decide to create a new WhatsApp Business username, have several backup

options in case your preferred business username isn’t available.

Confirm whether you need to link your business phone number

In order to claim the WhatsApp Business username you want, if you plan on using your existing and active Facebook Page or Instagram account, you must link your business phone number to your Facebook Page or Instagram account before you will be able to claim the WhatsApp Business username.

You can link your phone number:

● When claiming the WhatsApp Business username in Meta Business Suite or WhatsApp Manager, or

● By accessing your Facebook Page or Instagram account and adding your phone

number directly

Prepare owners for claiming your WhatsApp Business username

● Assign a clear owner (e.g., WhatsApp admin / Business Manager admin) who will

complete claiming a WhatsApp Business username when it becomes available

● Confirm required permissions in WhatsApp Manager and/or Meta Business Suite, or

that your team is ready to use the Gupshup implementation

Gupshup Implementation (in testing as on Jun 20, 2026)

This will be live when Meta allows for all. The adoption of business username will be supported in the following ways -

A. Gupshup Business Username APIs (Suggestions, Reservation, Management APIs along with approval webhook)
B. Gupshup.ai profile section
C. Meta Business Suite: Settings > Accounts > WhatsApp Accounts > Select phone number > pencil icon > Create username.

D. WhatsApp Business App

Read the technical implementation below to know more

Technical Implementation -

How to enable/disable the on-demand ‘enable BSUID in webhook flag’ related fields

How it works -

Two app-level configuration flags control whether the incoming passthrough payload is transformed to include these new fields when sending to partner's callback URL

Flag	Scope	Effect when enabled
enableBSUID	V2 incoming format	Payload is transformed to include the new BSUID/username-related fields in the V2 format
enableBSUIDV3	V3 incoming passthrough format	Payload is transformed to include the new BSUID/username-related fields in the V3 format

Flags are independent: an app can enable V2 only, V3 only, or both.

The above can be done -

Through gupshup.ai interface (Follow steps at the bottom)
OR through Partner API to enable the BSUID flag at an app level

How to Enable BSUID flag through Gupshup.ai

From gupshup.ai, you will find the option to enable BSUID under Webhook section -

On clicking it, you can choose which format you want to enable. You can enable both - v2 (Gupshup format) and V3 (Meta format) or only one as required, depending on your subscription set.

Usernames are assigned to the username property in API responses and webhooks payloads. Once enabled, a WhatsApp user’s username will appear in all incoming messages webhooks, and all delivered and read status messages webhooks.

How do the webhooks look like

Default Behaviour or when flag is not set or disabled = By default, any extra fields received from Meta (e.g. userid, from_user_id, recipient_user_id, parent_user_id, parent_recipient_user_id, profile.username, profile.country_code, and any other new BSUID/username-related fields) are dropped and not forwarded to partner's callback URL.
The payload forwarded to subscribers (V2 or V3) remains in the existing format without these new fields. This ensures backward compatibility and no breaking changes for clients who have not opted in.

When enableBSUID is enabled for an app:

Incoming payloads that are forwarded in V2 format includes the new fields ((e.g. userid, from_user_id, recipient_user_id, parent_user_id, parent_recipient_user_id, profile.username, profile.country_code, and any other new BSUID/username-related fields) in the appropriate places for the V2 format.

Below are representative incoming-message and DLR payloads in both formats. Keep your existing parsers; just allow the phone field to be absent and read the BSUID fields when the relevant flag is on. Full samples for billing, user-preference, Groups, Voice and Coexistence events are in the link at the end.

Incoming message — V2

Flag OFF, phone present (unchanged, standard payload)

{

"app": "<APP_NAME>", "timestamp": 1772761148179,

"version": 2, "type": "message",

"payload": {

"id": "wamid...", "type": "text",

"payload": { "text": "Buenas" },

"sender": { "phone": "<PHONE>", "name": "",

"country_code": "57", "dial_code": "" }

}

Flag ON, phone absent (BSUID only)

{

"app": "<APP_NAME>", "timestamp": 1772761148179,

"version": 2, "type": "message",

"payload": {

"id": "wamid...", "type": "text",

"payload": { "text": "Buenas" },

"sender": {

"user_id": "<BSUID>",

"parent_user_id": "<PARENT_BSUID>",

"name": "", "username": "<USERNAME>",

"country_code": "", "dial_code": ""

}

With the flag on and phone present, the same sender object additionally carries the phone field alongside the BSUID fields.

Delivery report (DLR) — V2 , flag ON, phone absent

{

"app": "<APP_NAME>", "timestamp": 1772761147857,

"version": 2, "type": "message-event",

"payload": {

"id": "<WDS_MESSAGE_ID>", "gsId": "<GS_MSG_ID>",

"type": "sent/delivered/read",

"userId": "<DESTINATION_BSUID>",

"parentUserId": "<PARENT_BSUID>",

"profileName": "", "profileUsername": "",

"payload": { "ts": 1772761146 },

"conversation": { "id": "<CONV_ID>", "expiresAt": 1773019380,

"type": "<CONV_TYPE>" },

"pricing": { "policy": "PMP", "category": "<CAT>", "type": "<TYPE>" }

}

When phone is present (flag on), the same payload additionally carries the destination phone field. With the flag off and phone present, you get your standard V2 DLR with destination and no BSUID fields.

When enableBSUIDV3 is enabled for an app:

Incoming payloads that are forwarded in V3 passthrough format are transformed so that the forwarded payload includes the new fields in the appropriate places for the V3 format. In incoming messages - Contact object > profile includes username as a field and the Messages object includes from user id and from parent user id. In outgoing msg status webhooks, Contact object includes username, user id and parent user id while the status object includes user id and parent userid.

Incoming message — V3

Flag ON, phone absent (BSUID only)

{

"entry": [{ "changes": [{ "field": "messages", "value": {

"contacts": [{

"parent_user_id": "<PARENT_BSUID>",

"profile": { "name": "test user name",

"username": "<USERNAME>" },

"user_id": "<BSUID>"

}],

"messages": [{

"from_user_id": "<BSUID>",

"from_parent_user_id": "<PARENT_BSUID>",

"id": "wamid...", "type": "text",

"text": { "body": "How much..." },

"timestamp": "1772775961"

}],

"messaging_product": "whatsapp",

"metadata": { "display_phone_number": "919019595595",

"phone_number_id": "392843927237559" }

}}], "id": "383534141505613" }],

"object": "whatsapp_business_account"

}

With the flag on and phone present, contacts[] also includes wa_id and messages[] also includes from (the phone number), alongside the BSUID fields shown above.

Delivery report (DLR) — V3 , flag ON, phone present

{

"entry": [{ "changes": [{ "field": "messages", "value": {

"contacts": [{ "parent_user_id": "<PARENT_BSUID>",

"profile": { "name": "test user name", "username": "<USERNAME>" },

"user_id": "<BSUID>", "wa_id": "<PHONE>" }],

"statuses": [{

"id": "...", "status": "delivered", "timestamp": "1772761087",

"recipient_id": "<PHONE>",

"recipient_user_id": "<BSUID>",

"parent_recipient_user_id": "<PARENT_BSUID>",

"pricing": { "billable": false, "category": "service",

"pricing_model": "PMP", "type": "free_customer_service" }

}],

"messaging_product": "whatsapp",

"metadata": { "display_phone_number": "918657025980",

"phone_number_id": "440930745778604" }

}}], "id": "510717575449287" }],

"object": "whatsapp_business_account"

}

Transformation is only to add/preserve the new BSUID/username-related fields in the respective passthrough format; it does not alter behavior for the other format (e.g. V2 flag does not change V3 payload and vice versa).

DOCUMENTATION : Payload Samples for All Webhooks can be referred here (including outgoing msg status webhooks, incoming message webhooks, coex, voice, user preferences and all other incoming webhooks)

Sending Messages to BSUID

Sending message to BSUID is supported in V2 and V3 APIs both.

V3 API (applies to both regular Cloud API and MM Lite V3)

Pass the phone number in the to field and / or the BSUID in the recipient field. If both are present, preference is given to the phone number.

curl --location 'https://{{api_front_base_url}}/wa/app/{{app_id}}/v3/msg' \

--header 'apikey: {api-key}' \

--header 'Content-Type: application/json' \

--data '{

"messaging_product": "whatsapp",

"recipient_type": "individual",

"to": "918222334455", // phone — optional

"recipient": "IN.35263896023254374", // BSUID — optional

"type": "text",

"text": { "body": "Hello World!" }

V3 response — phone supplied (or phone + BSUID)

{

"messages": [ { "id": "fe8d9b48-6ae0-46c6-9995-15c0438bb3d9" } ],

"messaging_product": "whatsapp",

"contacts": [ { "input": "917735695203", "wa_id": "917735695203" } ]

}

V3 response — only BSUID supplied

{

"messages": [ { "id": "d19d9b71-e5c4-424a-af3a-b28cebc4321c" } ],

"messaging_product": "whatsapp",

"contacts": [ { "input": "IN.34796978343279480",

"user_id": "IN.34796978343279480" } ]

}

Note: when you send to a BSUID only, the response contacts object returns user_id instead of wa_id.

V2 API

For V2 template and session APIs, the response format is unchanged. Pass the BSUID (or parent BSUID) in the userId field. If both destination (phone) and userId are present, preference is given to destination.

V2 template message

curl --location --request POST \

'https://{{api_front_base_url}}/wa/api/v1/template/msg' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--header 'apikey: {{api-key}}' \

--data-urlencode 'channel=whatsapp' \

--data-urlencode 'source=919953550569' \

--data-urlencode 'destination=918871601297' \ // phone — optional

--data-urlencode 'userId=IN.35263896023254374' \ // BSUID or parentUserId

--data-urlencode 'src.name=myTemplateName' \

--data-urlencode 'template={"id":"<template-id>","params":[]}' \

--data-urlencode 'bidSpec={"perMsgBidMultiplier":"1"}'

V2 session message

curl --location --request POST \

'https://{{api_front_base_url}}/wa/api/v1/msg' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--header 'apikey: {{api-key}}' \

--data-urlencode 'channel=whatsapp' \

--data-urlencode 'source=919953550569' \

--data-urlencode 'destination=918871601297' \ // phone — optional

--data-urlencode 'message={"type":"text","text":"Hi user"}' \

--data-urlencode 'src.name=myAppName' \

--data-urlencode 'userId=IN.34796978343279480' // BSUID or parentUserId

Validation note

BSUIDs are validated by Meta synchronously — sending to a malformed or unrecognised BSUID fails immediately in the API response, rather than via a later delivery receipt as happens for unreachable phone numbers. Store and pass the BSUID exactly as you received it.

DOCUMENTATION : API Documentation for the same will be updated soon

Refer Error Codes below

Error Codes

Error code — 131062

Details — Business-scoped User ID (BSUID) recipients are not supported for this message.

Requesting Contact Info
Sample webhook payload when customer shares the phone number

Contact share — user shares phone via Request Contact Info CTA
When a user taps to share their number in response to a Request Contact Info CTA, you receive a V2 and V3 message of type contacts events. It carries both the shared phone (in messages[].contacts[].phones[] and contacts[].wa_id) and the BSUID (from_user_id, contacts[].user_id) — letting you bind the two and store the mapping. origin is contact_request.

{

"entry": [{

"changes": [{

"field": "messages",

"value": {

"metadata": {

"phone_number_id": "339655972561940",

"display_phone_number": "919953550569"

"messaging_product": "whatsapp",

"messages": [{

"from": "917015696538",

"id": "wamid...",

"type": "contacts",

"contacts": [{

"origin": "contact_request",

"name": { "first_name": "Karan",

"formatted_name": "Karan" },

"phones": [{

"phone": "917015696538",

"wa_id": "917015696538",

"type": "MOBILE"

}],

"vcard": "QkVHSU46VkNBUkQK...RU5EOlZDQVJE==" —----> optional

}],

"from_user_id": "IN.35244766291834014",

"timestamp": "1780324175"

}],

"contacts": [{

"user_id": "IN.35244766291834014",

"profile": { "name": "Karan", "username": "mav1122" },

"wa_id": "917015696538"

}]

}

}],

"id": "342736278914679"

}],

"gs_app_id": "6f414190-d45c-4671-bca1-fb6c3018cb13",

"object": "whatsapp_business_account"

}

The vcard is a base64-encoded contact card (abbreviated above). On receiving this, persist the BSUID and phone mapping on your side so future sends and lookups can use the phone number.

V2 format webhook as below

{

"version": 2,

"timestamp": 1779784091297,

"type": "message",

"app": "AppName",

"phone": "9199XXXXX569",

"payload": {

"id": "wamid.HBgUSU4uMzQ2NjExMTY1ODAxOTg5OTEVFAASGCBBQzZDRkRFODYxN0IxNzE3ODQ0QTgyNzE4QTVEOTQzRgA=",

"type": "contact",

"source": "9188xxxxx297",

"sender": {

"name": "ㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤNisha",

"user_id": "IN.34661116580198991",

"username": "testusername",

"country_code": "91",

"dial_code": "88xxxxx297"

"payload": {

"contacts": [

{

"name": {

"first_name": "John",

"formatted_name": "Doe"

"phones": [

{

"phone": "9188XXXXX297",

"type": "MOBILE",

"wa_id": "9188XXXXX297"

}

]

}

]

}

Analytics

No changes in Gupshup or Meta analytics.

Billing and invoicing

No changes in Gupshup or Meta billing or fees or billing events.

Reserving of Usernames by Businesses

This will include a bunch of APIs and webhooks

Adopting or Changing or Transferring or Deleting Username
Getting current username and status
Getting Meta suggestions for username
business_username_updates webhook once the username is approved, deleted or reserved by Meta

DOCUMENTATION : API Documentation for the same will be updated soon

Username / Business Scoped User ID

Introduction & Summary

HELPFUL LINKS -

SUMMARY FOR THOSE WHO WILL CONTINUE TO RELY ON PHONE NUMBER -

SUMMARY FOR THOSE WHO WANT TO INTEGRATE BSUID-

SUMMARY OF MESSAGING

SUMMARY OF BUSINESS USERNAME

Key components -

Username adoption by end-users

3. BSUID and username related fields

4. Sending message to BSUID instead of phone number

5. Username Adoption by Businesses:

Actions to take now (prep checklist)

Technical Implementation -

How to enable/disable the on-demand ‘enable BSUID in webhook flag’ related fields

How do the webhooks look like

When enableBSUID is enabled for an app:

When enableBSUIDV3 is enabled for an app:

Sending Messages to BSUID

V3 API (applies to both regular Cloud API and MM Lite V3)

V2 API

Error Codes

Requesting Contact Info
Sample webhook payload when customer shares the phone number

Analytics

Billing and invoicing

Reserving of Usernames by Businesses

Comments

Introduction & Summary

HELPFUL LINKS -

SUMMARY FOR THOSE WHO WILL CONTINUE TO RELY ON PHONE NUMBER -

SUMMARY FOR THOSE WHO WANT TO INTEGRATE BSUID-

SUMMARY OF MESSAGING

SUMMARY OF BUSINESS USERNAME

Key components -

Username adoption by end-users

3. BSUID and username related fields

4. Sending message to BSUID instead of phone number

5. Username Adoption by Businesses:

Actions to take now (prep checklist)

Technical Implementation -

How to enable/disable the on-demand ‘enable BSUID in webhook flag’ related fields

How do the webhooks look like

When enableBSUID is enabled for an app:

When enableBSUIDV3 is enabled for an app:

Sending Messages to BSUID

V3 API (applies to both regular Cloud API and MM Lite V3)

V2 API

Error Codes

Requesting Contact InfoSample webhook payload when customer shares the phone number

Analytics

Billing and invoicing

Reserving of Usernames by Businesses

Related articles

Requesting Contact Info
Sample webhook payload when customer shares the phone number