# Users without a phone number (BSUID)

Fonte: https://lunahia.com.br/en/docs/users-without-phone

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.

Message from someone who does not show a phone number

```json
{
  "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
  }
}
```

> **This is a contract change**, which is why the event version went up to `2026-11-03` (and went up again to `2026-11-04` with the complete incoming content). `wa_id` is no longer always a text: whoever read it without checking for null needs to handle the case. Before it, Luna did not receive the message from someone writing without a phone number. A new event type (`contact.identity_changed`, below) does not raise the version.

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.

Status (with phone number and BSUID)

```json
{
  "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.

A conversation without a phone number in GET /v1/conversations

```json
{
  "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.

Sending by BSUID

```json
{
  "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 error `131062`. Send that template to the phone number, in `to`.
- **Error `131062`**: Meta refused the BSUID recipient for this send. Luna returns it as undeliverable, with the action: send to the phone number, in `to`. Repeating by BSUID does not help.
- **Replying by quoting** requires the same conversation: quote a message from the conversation of the `recipient` you are using.

> If your records have the phone number of a contact who wrote with a BSUID only, **do not** use it in `to` to answer: Luna does not know they are the same person, would open another conversation by phone number, with the window closed, and would refuse free text. Use `recipient` with the `user_id` you received.

## 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.

BSUID change

```json
{
  "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](https://lunahia.com.br/en/docs/receive-events), sending is in [Send messages](https://lunahia.com.br/en/docs/send-messages) and the errors are in [Errors](https://lunahia.com.br/en/docs/errors). Every field of `GET /v1/conversations`, `GET /v1/messages` and `POST /v1/messages` is in the [API reference](https://lunahia.com.br/en/docs/reference).
