# Usuários sem telefone (BSUID)

Fonte: https://lunahia.com.br/docs/usuarios-sem-telefone

Quem adotou um nome de usuário no WhatsApp pode escrever para o seu cliente sem que o telefone dele apareça. A Meta identifica esse usuário por um BSUID. A Luna recebe, guarda e entrega o BSUID, e o seu sistema precisa tratar o telefone como opcional.

## O que é o BSUID

O BSUID é o identificador do usuário que não depende do telefone. Tem o código do país (duas letras), um ponto e até 128 letras e números: `US.13491208655302741918`. O BSUID pai, que a Meta manda em alguns portfólios, tem `ENT` depois do país: `US.ENT.11815799212886844830`. **Guarde o valor inteiro, como veio**: a Luna e a Meta não o normalizam, e um valor alterado deixa de achar o usuário.

O telefone continua existindo. A Meta o manda no webhook quando houve mensagem ou ligação nos dois sentidos nos últimos 30 dias, ou quando o usuário está no livro de contatos do portfólio. Fora disso, só o BSUID chega. **Não existe API que converta telefone em BSUID**, nem o contrário: a Luna não tem como descobrir um a partir do outro.

## O que muda nos eventos

`message.received`, `message.status` e `message.echo` ganham três campos, sempre presentes e nulos quando não se aplicam: `user_id` (o BSUID), `parent_user_id` e `username`. E `wa_id` **pode ser nulo**: quando o usuário escreve sem telefone, o interlocutor é o `user_id`. Os valores chegam como a Meta mandou.

Mensagem de quem não mostra o telefone

```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
  }
}
```

> **É uma mudança de contrato**, e por isso a versão dos eventos subiu para `2026-11-03` (e subiu de novo para `2026-11-04` com o conteúdo de entrada completo). `wa_id` deixou de ser sempre um texto: quem o lia sem checar o nulo precisa tratar o caso. Antes dela, a Luna não recebia a mensagem de quem escrevia sem telefone. Tipo novo de evento (`contact.identity_changed`, abaixo) não sobe a versão.

No status de uma mensagem que você enviou por BSUID, `wa_id` também pode ser nulo e o `user_id` identifica o destinatário. O evento fica no mesmo grupo de ordem da conversa: a ordem dentro da conversa continua garantida.

Status (com telefone e 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"
  }
}
```

## Qual é a chave do contato no seu sistema

Use o BSUID (`user_id`) como chave do contato quando ele vier, e o telefone como atributo. Quando a mensagem traz os dois, a Luna liga telefone e BSUID na **mesma conversa**: a conversa que você já tinha por telefone continua com o mesmo `id`, e passa a ter o `userId`. Nenhum histórico é reescrito.

O telefone mais recente que o próprio usuário usou vence. Se uma conversa já tem outro telefone e chega uma mensagem do mesmo BSUID com um telefone novo, a Luna passa a usar o novo. Duas conversas nunca são fundidas: se o telefone novo já pertence a outra conversa do número, ele não é movido, e as duas conversas continuam, cada uma achável por uma das identidades.

Uma conversa sem telefone em 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` e `GET /v1/messages` devolvem `userId`, `parentUserId` e `username`, e `waId` passa a poder ser `null`. Os dois ganham o filtro `userId`, que é igualdade exata e devolve lista vazia quando nada casa. `GET /v1/conversations?waId=` continua achando a conversa pelo telefone.

## Como responder a quem não tem telefone

`POST /v1/messages` aceita `recipient`, o BSUID do destinatário, no lugar de `to`. Mande **um dos dois**: os dois juntos, ou nenhum, respondem 400. Para responder, use o `user_id` do evento recebido.

Envio por BSUID

```json
{
  "from": "123456789012345",
  "recipient": "BR.13491208655302741918",
  "text": { "body": "Oi, Maria! Seu pedido saiu para entrega." }
}
```

- **A janela de 24 horas funciona igual.** Uma conversa só de BSUID abre a janela quando o usuário escreve, e texto livre fora dela responde 409 `window_closed`. Template passa fora da janela, como para qualquer destinatário.
- **Template de autenticação não vai para BSUID.** Os templates de autenticação de um toque, zero toque e copiar código precisam do telefone. A Luna recusa com 400, antes da Meta, quando conhece o template, ele é de autenticação e o destino é `recipient`. Se ela não conhece o template (criado direto no painel da Meta), a Meta recusa com o erro `131062`. Envie esse template para o telefone, em `to`.
- **Erro `131062`**: a Meta recusou o destinatário por BSUID para este envio. A Luna o devolve como não entregável, com a ação: enviar para o telefone, em `to`. Não adianta repetir por BSUID.
- **Responder citando** exige a mesma conversa: cite uma mensagem da conversa do `recipient` que você está usando.

> Se o seu cadastro tem o telefone de um contato que escreveu só com BSUID, **não** o use em `to` para responder: a Luna não sabe que os dois são a mesma pessoa, abriria outra conversa por telefone, com a janela fechada, e recusaria o texto livre. Use `recipient` com o `user_id` que você recebeu.

## Quando o contato troca de telefone ou de BSUID

A Meta avisa a troca com uma mensagem de sistema (`user_changed_number` ou `user_changed_user_id`). A Luna liga a identidade nova à mesma conversa, não abre a janela de atendimento (não é uma mensagem que o usuário escreveu) e entrega o evento `contact.identity_changed`. Ele traz `previous_user_id` e `user_id`: use os dois para atualizar o contato no seu cadastro. Os campos que a Meta omite vêm nulos.

Troca de BSUID

```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
  }
}
```

## O que a Luna não faz

- Não converte telefone em BSUID nem BSUID em telefone: a Meta não oferece essa consulta.
- Não funde duas conversas que, no seu cadastro, são a mesma pessoa. Isso é decisão do seu sistema, que tem os dois identificadores.
- Não garante a ordem estrita dos eventos no instante em que uma conversa só de BSUID ganha o telefone: a chave de ordem muda uma vez, naquele momento, e eventos em voo de antes e de depois podem chegar em qualquer ordem entre si. A ordem dentro da conversa vale antes e depois dessa passagem.

Os eventos estão em [Receber eventos](https://lunahia.com.br/docs/receber-eventos), o envio em [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens) e os erros em [Erros](https://lunahia.com.br/docs/erros). Cada campo de `GET /v1/conversations`, `GET /v1/messages` e `POST /v1/messages` está na [referência da API](https://lunahia.com.br/docs/referencia).
