Usuários sem telefone (BSUID)
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.
{
"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
}
}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.
{
"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.
{
"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.
{
"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 erro131062. Envie esse template para o telefone, emto. - 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, emto. Não adianta repetir por BSUID. - Responder citando exige a mesma conversa: cite uma mensagem da conversa do
recipientque você está usando.
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.
{
"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, o envio em Enviar mensagens e os erros em Erros. Cada campo de GET /v1/conversations, GET /v1/messages e POST /v1/messages está na referência da API.