LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Usuários sem telefone (BSUID)

Usar com IA

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 telefoneJSON
{
  "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.

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/conversationsJSON
{
  "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 BSUIDJSON
{
  "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.

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 BSUIDJSON
{
  "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.