Usernames - Frequently Asked Questions – Blip | Blip Help

Webhooks and Notifications

When is there a webhook for identity changes?

Meta triggers webhooks in only two scenarios:

BSUID changes — webhook user_id_update
Phone number changes — webhook user_preferences

⚠️ There is no webhook when a user activates the username or stops sharing their phone number. This change happens silently in subsequent interactions.

How to detect: Monitor the metadata of messages. When a message arrives without PN (phone number), but with BSUID filled, it means the user activated the username.

Contact Reconciliation

How does Blip reconcile contacts with the new identifier?

Blip maintains a continuous mapping between PN ↔ BSUID ↔ Blip ID, created since April 2026, and performs reconciliation automatically:

Flow:

Contact interacts (with PN + BSUID)
    ↓
Blip checks existing mapping
    ↓
Found → Updates existing contact (history preserved)
Not found → Creates new contact

Example: If a contact you have known since 2025 (with PN 5531999999999) interacts using username, Meta sends PN + BSUID together. Blip recognizes and updates the existing contact.

⚠️Limitation: For contacts who have never interacted with you, there is no automatic mapping. Mapping only occurs when there is actual interaction.

Identifiers (IDs)

What is the difference between Blip ID, BSUID, WaId, and Username?

Identifier	What it is	Who creates it	Scope
Blip ID	Internal Blip ID	Blip	Per contact on the platform
BSUID	User ↔ company relationship	Meta	Per company (Business Manager)
WaId	Corresponds to the WhatsApp phone number	–	Global
Username	User's public name	User	Global

Will the Blip ID be deprecated?

No. The Blip ID is one of the new contact identities.

It was created precisely to bring stability and independence to the Meta model. You can safely use it in all integrations.

Contact Data and Fields

Will extra fields (CPF, email, name) still be provided?

Yes, without impact. Only the contact's identity field will evolve. All others remain intact:

CPF, email, name
Phone (when available)
Custom fields
Extras

Even when the user hides the PN (activating the username), Blip continues sending all these data in webhooks.

What will the exact message payload look like?

With PN shared:

{
  "contact": {
    "identity": "5531999999999@wa.gw.msging.net",
    "phoneNumber": "5531999999999",
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "metadata": {
    "#wa.bsuid": "BR.1234567890123456",
    "#wa.username": "@meuUsername"
  }
}

Without PN shared (username active):

{
  "contact": {
    "identity": "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net",
    "phoneNumber": null,
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "metadata": {
    "#wa.bsuid": "BR.1234567890123456",
    "#wa.username": "@meuUsername"
  }
}

Key changes:

contact.identity can be GUID or PN
contact.phoneNumber can be null
New fields in metadata: #wa.bsuid, #wa.username
All other fields remain

Message Sending

Can I send messages by BSUID, Blip ID, and PN?

Yes. The sending APIs now accept all three:

By PN (already works):

POST /messages
{
  "to": "5531999999999@wa.gw.msging.net",
  "content": { "type": "text", "text": "Hello!" }
}

By BSUID (new):

POST /messages
{
  "to": "BR.1234567890123456@wa.gw.msging.net",
  "content": { "type": "text", "text": "Hello!" }
}

By Blip ID (new):

POST /messages
{
  "to": "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net",
  "content": { "type": "text", "text": "Hello!" }
}

Will the GET /accounts endpoint continue to work?

Yes, evolved. It will continue accepting queries by PN and now also by BSUID:

GET /accounts?phoneNumbers=5531999999999
GET /accounts?bsuids=BR.1234567890123456

Response remains the same:

{
  "items": [
    {
      "id": "5531999999999",
      "bsuid": "BR.1234567890123456",
      "waId": "5531999999999"
    }
  ]
}

No changes. Works for old and new users.

Campaigns and Sends

Can I send campaigns to phone numbers normally?

Yes, indefinitely. Even contacts with an active username can still receive messages by PN.

Important: When you initiate the conversation by PN, Meta returns PN + BSUID in the response. Blip maps and updates the contact.

Important detail: When you send by PN to a contact who hides the phone:

You can send (even if the PN is not visually shared)
Meta returns PN + BSUID in the response (even if the user does not share)
Blip updates the contact automatically

Recommendation: Continue using PN for existing bases. Use BSUID when PN is unavailable.

What if I only have BSUID of a contact who has never talked to me?

You cannot send to someone you never talked to using only BSUID. BSUID only exists when there is interaction between that user and your company. If you want to reach someone who never talked:

You need the PN
Or send the first message by PN
That way, Meta will provide the BSUID in the response

Can I send campaigns mixing numbers and BSUIDs?

Yes. For mass campaigns (CSV), you can mix:

recipient,name
+55319XXXXXXXX,Carlos
BR.1234567890,Ana
+55319XXXXXXXX,Pedro

⚠️ Attention: If PN and BSUID of the same user are present in the same list, 2 sends will be made to the same user. Ensuring deduplication is your responsibility.

Flows in Studio

Can contact.identity contain GUID instead of PN?

Yes, starting 06/01/2026.

TODAY:

contact.identity = "5531999999999@wa.gw.msging.net" (always PN)

FROM 07/01:

contact.identity = can be:
  • "5531999999999@wa.gw.msging.net" (PN when available)
  • "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net" (GUID if no PN)

⚠️ RISK: If you extract the phone like this:

const phone = contact.identity.split("@")[0];

It may return a GUID instead of a phone when the user does not share the PN.

SOLUTION: Use new variables:

contact.whatsAppWaId    // Returns PN when available, null if not
contact.whatsAppBsuid   // Returns BSUID (always available)

Recommended action:

In Studio → Analyze Flow
Tool marks blocks at risk
Review and adjust using new variables
Test in staging

What are the new Studio variables?

New variables:

contact.whatsAppBsuid → BSUID (always filled)
contact.whatsAppParentId → Parent BSUID (cross-BM)
contact.whatsAppUserName → Username adopted by the user
contact.waId → Corresponds to the user's WhatsApp number (when available)

Old ones (continue, but may change format):

contact.identity → Now can be PN or GUID
contact.phoneNumber → Can be null when no PN
tunnel.originator → Now can be PN or GUID
tunnel.identity → Now can be PN or GUID

Not affected:

contact.name, contact.email, contact.extras (CPF, etc.)

Schedule and Rollout

What is the official schedule?

Meta:

June and July 2026: Alpha in some selected countries (does not affect Brazil)
H2 2026: progressive global rollout by Meta (including Brazil)

Important: Adoption is per user, not per company.

There is no "universal change date"
It is gradual as each person activates the username
Company A may have 100k users WITHOUT PN on day 1; Company B may have 10

Is there a deadline to comply?

There is no fixed deadline, but immediate action is recommended.

Username adoption is expected from mid-September
The number of users without shared PN will grow organically
There is no "PN deactivation" date

Recommendation:

Adapt as soon as possible
Validate with the testing environment
Monitor impacts in the second half of the year

Template Components

Will Meta provide a template to request the user's PN?

Yes, through a specific component of contact request.

Structure already known:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

Workflow:

Brand creates template with REQUEST_CONTACT_INFO button
Blip sends template → user sees "Share Contact"
User clicks → shares PN
Webhook triggers with #wa.contactOrigin: "contact_request"

When will it be released: It is already available via API.

Customization limitations:

Button type: always "REQUEST_CONTACT_INFO"
Button text: always "Share Contact Info" (Meta translates automatically)
You can customize: body text, language, category

Preparation Strategy

I have 1 million old contacts. How do I do the mapping?

Scenario 1 - Active message sending:

You send: Active send by PN
Meta sends notification report: Meta sends PN + BSUID
Blip: Maps automatically
History preserved

Scenario 2 - Organic mapping:

User initiates contact
Meta sends BSUID (and PN or username, when available)

Scenario 3 - You want to force mapping:

Use: GET /external-contacts-mapping endpoint
Returns: PN ↔ BSUID mapping for contacts Meta has already sent

⚠️ Limitation: There is no endpoint to query BSUID of a PN that never had interaction. Reconciliation only happens with contacts who have already interacted with the company.

My CRM uses PN as primary key. What do I do?

No need to change now, but prepare.

Short term (until Dec/2026):

Keep PN as main reference
Add fields: BSUID, Blip ID
Map PN → BSUID as interactions happen

Medium term (from 2027):

Migrate to Blip ID as primary key
Use PN as secondary field "when available"
BSUID as Meta reference field

Migration example:

-- BEFORE
PRIMARY KEY: phone_number
-- AFTER
PRIMARY KEY: blip_id (guid)
UNIQUE KEY: bsuid
INDEX: phone_number (nullable)

You can do this gradually.

Special Cases

What is Parent BSUID?

An identifier to consolidate identity across multiple Business Managers of the same organization.

Example:

Your Company (Tax ID: 123456789)
├─ Business Manager 1 (Sales)
│  └─ BSUID: BR.111111111111111
├─ Business Manager 2 (Support)
│  └─ BSUID: BR.222222222222222
└─ Parent BSUID: BR.ENT.999999999999999 ← Identifies same company

When a user interacts with any Business Manager of your company, the Parent BSUID identifies that it is the same person in different contexts.

Restrictions:

Requires Meta approval
Not all Business Managers are eligible
When available, it comes in message metadata

Does a BSUID repeat in different companies?

No, it is unique per company.

User João
├─ Company A: BSUID = BR.111111111111111
├─ Company B: BSUID = BR.222222222222222
└─ Company C: BSUID = BR.333333333333333

Same person, completely different BSUIDs. This is by design (privacy + security).

What is the format of a GUID?

A GUID is a 128-bit number (16 bytes) represented by 32 hexadecimal characters.

Standard format with hyphens:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 Real example:
e4b11bdd-a9bf-46ad-a9b0-34116dece5fe

General Questions

Will the phone number disappear from WhatsApp?

No. Every WhatsApp account remains linked to a phone number.

What changes is that the number may stop being automatically shared in some interactions with users who activate the username.

Which template fields are blocked for PN?

⚠️ Authentication templates (one-tap, zero-tap, copy code) require the phone number.

For text messages, media, buttons, and marketing templates, BSUID works normally.

How to know if a contact shared their phone via CTA?

Check the metadata of messages:

{
  "metadata": {
    "#wa.contactOrigin": "contact_request",
    "#wa.sharedWaId": true
  }
}

If both are present with these values, the contact shared their own phone through the REQUEST_CONTACT_INFO button.

Additional Resources

Need more help? Explore our content at Blip Academy or Blip Community, watch tutorials on our YouTube channel, or ask your questions in our support channel 😃