Usernames e BSUID no WhatsApp

Três conceitos que não devem ser misturados

Username comercial

Nome público associado ao número da empresa, como @suaempresa. O Flow acompanha os estados enviados pela Meta.

Pertence ao número comercial
Serve para identidade e descoberta
Pode ser reservado, aprovado ou removido

Username do usuário

Nome escolhido pela pessoa no WhatsApp, quando o recurso estiver disponível. Pode mudar e deve ser tratado como dado de exibição.

Não use como chave primária
Pode não existir em todo payload
Pode identificar uma pessoa no contexto da empresa

BSUID

Business-Scoped User ID: identificador técnico do usuário dentro da relação com determinado portfólio empresarial.

Pode existir sem telefone
Deve ser preservado exatamente como recebido
É a referência técnica para continuidade do contato

Regra prática

Username é exibição. BSUID é identidade técnica. Telefone passa a ser um campo opcional em cenários compatíveis com o rollout da Meta.

Username comercial no painel HookCloud

A HookCloud processa o evento administrativo business_username_updates, relaciona a alteração à conexão correta e atualiza o card do número.

Status da Meta	Como aparece no Flow	Significado
`reserved`	Reservado	O nome foi reservado, mas pode ainda não estar visível para todos.
`approved`	Ativo	O username foi aprovado e associado ao número.
`deleted`	Removido	O username foi removido; o histórico técnico pode manter o último valor conhecido.

{
  "field": "business_username_updates",
  "value": {
    "display_phone_number": "+5511999999999",
    "username": "suaempresa",
    "status": "approved"
  }
}

Disponibilidade controlada pela Meta

A reserva, a aprovação, a visibilidade regional e o cronograma do recurso dependem da Meta. O Flow exibe o estado recebido, mas não aprova usernames.

O que muda com o BSUID

O BSUID representa a pessoa no contexto do Business Portfolio. Em conversas iniciadas por username, alguns eventos podem chegar sem telefone. Integrações que exigem wa_id, from, recipient_id ou uma coluna de telefone obrigatória precisam ser revisadas.

Telefone, quando disponível+5511999999999

Identidade técnicaBR.13491208655302741918

Campos que sua integração deve preservar

contacts[].user_idBSUID do contato.

messages[].from_user_idBSUID do remetente.

statuses[].recipient_user_idBSUID do destinatário nos status.

parent_user_id e variantesIdentidade pai, quando aplicável.

from / wa_id / recipient_idTelefone; pode estar vazio ou ausente.

contacts[].profile.usernameUsername de exibição; pode mudar.

recipientCampo outbound para enviar ao BSUID.

toCampo outbound para enviar ao telefone.

user_id é origem; recipient é destino

Leia o BSUID no webhook e, ao responder sem telefone, envie o valor no campo recipient. Não envie o username e não use user_id como nome de campo na requisição outbound.

Entrega no webhook próprio

Quando a rota própria está confirmada, os campos de identidade enviados no webhook operacional chegam diretamente da Meta ao endpoint configurado. A HookCloud não remove user_id, from_user_id, username ou telefone.

O sistema receptor deve preservar o payload, aceitar telefone ausente e manter o BSUID no contexto do Business Portfolio correto. Consulte os exemplos sanitizados e a estratégia de isolamento em CRM próprio, webhook direto e API oficial →

O que o Flow faz — e o que continua no seu sistema

HookCloud Flow

Monitora username comercial e status.
Relaciona o evento ao número correto.
Gera notificações administrativas.
Gerencia a rota para Chatwoot ou webhook próprio.
Mostra checklist de prontidão para BSUID.

Chatwoot, CRM ou webhook

Cria e reconcilia contatos.
Aceita telefone ausente.
Armazena BSUID de forma segura.
Evita contato duplicado quando a identidade muda.
Responde usando o identificador aceito pela Meta.

O Flow não vira caixa de atendimento ou CRM. Quando a rota individual está configurada para a plataforma escolhida, os eventos operacionais são entregues ao destino externo e a modelagem dos contatos acontece nesse sistema.

Validação recomendada no Chatwoot

Copie o número no formato corretoUse o botão Número para Chatwoot. O valor é copiado como +15553811311, sem espaços, parênteses ou traços.

Compare o Phone Number IDEm WABAs com vários números, não use apenas o WABA ID para decidir qual inbox pertence a qual número.

Verifique a rota no FlowO card deve indicar rota externa confirmada e o teste de entrada precisa chegar à inbox.

Teste telefone + BSUIDO sistema deve manter um único contato com os identificadores associados.

Teste somente BSUIDA mensagem precisa ser aceita sem validação obrigatória de telefone.

Conectividade não é compatibilidade de identidade

Health verde e webhook correto confirmam a rota, mas não garantem sozinhos que a versão do Chatwoot trate contato sem telefone ou reconcilie mudanças de BSUID.

Abrir o passo a passo completo do Chatwoot →

Requisitos para webhook próprio

✓ Aceitar user_id e from_user_id

✓ Aceitar recipient_user_id em status

✓ Permitir telefone nulo ou ausente

✓ Guardar BSUID + Business ID

✓ Associar BSUID e telefone quando ambos existirem

✓ Responder com recipient quando houver somente BSUID

✓ Usar to quando houver telefone

✓ Não usar username como chave/destino

✓ Preservar campos novos da Meta

✓ Evitar logs com payloads pessoais completos

Modelo conceitual de identificação e resposta

const bsuid = event.contacts?.[0]?.user_id
  ?? event.messages?.[0]?.from_user_id
  ?? event.statuses?.[0]?.recipient_user_id
  ?? null;

const phone = event.contacts?.[0]?.wa_id
  ?? event.messages?.[0]?.from
  ?? event.statuses?.[0]?.recipient_id
  ?? null;

const destination = bsuid
  ? { recipient: bsuid }
  : { to: phone };

// BSUID sempre no contexto do Business Portfolio
// telefone é opcional
// username serve apenas para exibição

Veja payloads sanitizados de mensagem, status e envio em CRM próprio e integração.

Checklist antes de declarar compatibilidade com BSUID

Cenário	Resultado esperado
Telefone + BSUID	Um contato, com os dois identificadores associados.
Somente BSUID	Mensagem aceita sem telefone obrigatório.
Username alterado	Atualiza exibição sem criar novo contato.
`user_id_update`	Histórico reconciliado com o identificador novo.
Resposta ao cliente	Envio usa um identificador aceito pela Meta.
Webhook repetido	Idempotência evita conversa ou contato duplicado.

Critério de aprovação

Marque sua integração como compatível somente depois de validar os cenários disponíveis no ambiente real ou de homologação.

Privacidade e responsabilidades

BSUID e username de usuário podem identificar uma pessoa no contexto da empresa e devem ser tratados como dados pessoais quando aplicável.

HookCloud: armazena o username comercial e seus estados para exibição, observabilidade e suporte da conexão.
Callback global: não foi projetado para formar uma base de mensagens, usernames ou BSUIDs de clientes finais; pode haver processamento transitório estritamente técnico.
Chatwoot ou webhook próprio: recebe e trata os identificadores conforme a configuração e a política do sistema escolhido.
Assinante: define finalidade, base legal, acesso, retenção e atendimento dos direitos dos titulares.

Ler a Política de Privacidade da HookCloud →

Referências oficiais

Precisa validar sua integração?

Informe o e-mail do owner, Workspace ID, Connection ID, Phone Number ID e o código de suporte. Nunca envie o token completo ou payloads com dados pessoais em canal público.