Users without a phone number (BSUID)
Someone who adopted a WhatsApp username can write to your customer without their phone number showing. Meta identifies that user by a BSUID. Luna receives, keeps and delivers the BSUID, and your system needs to treat the phone number as optional.
What the BSUID is#
The BSUID is the user identifier that does not depend on the phone number. It has the country code (two letters), a dot and up to 128 letters and digits: US.13491208655302741918. The parent BSUID, which Meta sends in some portfolios, has ENT after the country: US.ENT.11815799212886844830. Keep the whole value, as it came: Luna and Meta do not normalize it, and an altered value no longer finds the user.
The phone number still exists. Meta sends it in the webhook when there was a message or a call in both directions in the last 30 days, or when the user is in the portfolio’s contact book. Outside that, only the BSUID arrives. There is no API that converts a phone number into a BSUID, or the other way round: Luna has no way to find one from the other.
What changes in events#
message.received, message.status and message.echo gain three fields, always present and null when they do not apply: user_id (the BSUID), parent_user_id and username. And wa_id can be null: when the user writes without a phone number, the correspondent is user_id. The values arrive as Meta sent them.
{
"version": "2026-11-10",
"event_id": "e2f81dd079e4419dac363779655be694a25cc502b7646be51cdac4b0cfc276fb",
"event_type": "message.received",
"occurred_at": "2026-11-03T14:02:11.482Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"message": {
"id": "c8a1e5d2-6f3b-4a7c-9e0d-1b2c3d4e5f60",
"wamid": "wamid.EXAMPLE_NO_PHONE",
"wa_id": null,
"user_id": "BR.13491208655302741918",
"parent_user_id": null,
"username": "mariasouza",
"type": "text",
"text": "Oi! Queria saber o status do meu pedido.",
"profile_name": "Maria Souza",
"media": null,
"interactive": null,
"button": null,
"location": null,
"contacts": null,
"reaction": null,
"context": null,
"referral": null,
"unsupported": null,
"edit": null,
"revoke": null,
"order": null
}
}On the status of a message you sent by BSUID, wa_id can also be null and user_id identifies the recipient. The event stays in the same ordering group as the conversation: the order inside the conversation is still guaranteed.
{
"version": "2026-11-10",
"event_id": "464e089a80690f1792db6249678ddeced5ad5be0d46d95e2daa263779f7d92e5",
"event_type": "message.status",
"occurred_at": "2026-10-06T14:02:14.090Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"message": {
"id": "ae60f288-7565-4315-a440-3663e9c231e1",
"wamid": "wamid.EXAMPLE_NOT_A_REAL_ID",
"wa_id": "5511900000000",
"user_id": "BR.13491208655302741918",
"parent_user_id": null,
"username": null,
"status": "sent",
"error_code": null,
"error": null,
"pricing": {
"billable": false,
"pricing_model": "PMP",
"type": "free_customer_service",
"category": "service"
},
"callback_data": "atendimento-8841"
}
}What the contact key is in your system#
Use the BSUID (user_id) as the contact key when it comes, and the phone number as an attribute. When a message carries both, Luna links phone number and BSUID in the same conversation: the conversation you already had by phone number keeps the same id, and gains the userId. No history is rewritten.
The most recent phone number the user themselves used wins. If a conversation already has another phone number and a message arrives from the same BSUID with a new one, Luna uses the new one. Two conversations are never merged: if the new phone number already belongs to another conversation of the number, it is not moved, and both conversations stay, each one findable by one of the identities.
{
"id": "0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12",
"waId": null,
"userId": "BR.13491208655302741918",
"parentUserId": null,
"username": "mariasouza",
"numberId": "7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11",
"windowOpen": true
}GET /v1/conversations and GET /v1/messages return userId, parentUserId and username, and waId can now be null. Both gain the userId filter, which is an exact match and returns an empty list when nothing matches. GET /v1/conversations?waId= still finds the conversation by phone number.
How to answer someone without a phone number#
POST /v1/messages accepts recipient, the recipient’s BSUID, in place of to. Send one of the two: both together, or neither, answer 400. To answer, use the user_id of the received event.
{
"from": "123456789012345",
"recipient": "BR.13491208655302741918",
"text": { "body": "Oi, Maria! Seu pedido saiu para entrega." }
}- The 24-hour window works the same way. A BSUID-only conversation opens the window when the user writes, and free text outside it answers 409
window_closed. A template goes through outside the window, as for any recipient. - An authentication template does not go to a BSUID. One-tap, zero-tap and copy-code authentication templates need the phone number. Luna refuses with 400, before Meta, when it knows the template, it is an authentication one and the destination is
recipient. If Luna does not know the template (created directly in Meta's panel), Meta refuses with error131062. Send that template to the phone number, into. - Error
131062: Meta refused the BSUID recipient for this send. Luna returns it as undeliverable, with the action: send to the phone number, into. Repeating by BSUID does not help. - Replying by quoting requires the same conversation: quote a message from the conversation of the
recipientyou are using.
When the contact changes phone number or BSUID#
Meta announces the change with a system message (user_changed_number or user_changed_user_id). Luna links the new identity to the same conversation, does not open the service window (it is not the user writing) and delivers the contact.identity_changed event. It carries previous_user_id and user_id: use both to update the contact in your records. The fields Meta omits arrive null.
{
"version": "2026-11-10",
"event_id": "f73a65b1f155f86f94e0886ad29bac662a822fabf796b626cdf865c7060f0db9",
"event_type": "contact.identity_changed",
"occurred_at": "2026-11-03T15:20:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"contact": {
"wamid": "wamid.EXAMPLE_IDENTITY_CHANGE",
"change_type": "user_changed_user_id",
"wa_id": null,
"user_id": "BR.98765432109876543210",
"previous_user_id": "BR.13491208655302741918",
"parent_user_id": null,
"previous_parent_user_id": null
}
}What Luna does not do#
- It does not convert a phone number into a BSUID or a BSUID into a phone number: Meta does not offer that lookup.
- It does not merge two conversations that, in your records, are the same person. That is a decision for your system, which has both identifiers.
- It does not guarantee strict event order at the moment a BSUID-only conversation gains a phone number: the ordering key changes once, at that moment, and in-flight events from before and after can arrive in any order among themselves. Order inside the conversation holds before and after that change.
The events are in Receive events, sending is in Send messages and the errors are in Errors. Every field of GET /v1/conversations, GET /v1/messages and POST /v1/messages is in the API reference.