Pular para o conteúdo principal

Usernames - Perguntas Frequentes

  • Atualizado
  1. Webhooks e Notificações
  2. Reconciliação de Contatos
  3. Identificadores (IDs)
  4. Dados do Contato e Campos
  5. Envio de Mensagens
  6. Campanhas e Disparos
  7. Fluxos no Studio
  8. Cronograma e Rollout
  9. Componentes de Template
  10. Estratégia de Preparação
  11. Casos Especiais
  12. Perguntas Gerais
  13. Recursos Adicionais

 

Webhooks e Notificações

Quando há webhook para mudanças de identidade?

A Meta dispara webhooks apenas em dois cenários:

  • BSUID muda — webhook user_id_update

  • Número de telefone muda — webhook user_preferences

⚠️ Não há webhook quando um usuário ativa o nome de usuário ou deixa de compartilhar seu número de telefone. Essa mudança ocorre silenciosamente nas interações subsequentes.

Como detectar: Monitore o metadata das mensagens. Quando uma mensagem chega sem PN (número de telefone), mas com BSUID preenchido, significa que o usuário ativou o nome de usuário.

 

Reconciliação de Contatos

Como a Blip concilia contatos com o novo identificador?

A Blip mantém um mapeamento contínuo entre PN ↔ BSUID ↔ ID Blip, criado desde abril de 2026, e faz a reconciliação automaticamente:

Fluxo:

Contato interage (com PN + BSUID)
    ↓
Blip consulta mapeamento existente
    ↓
Encontrado → Atualiza contato existente (histórico preservado)
Não encontrado → Cria novo contato

Exemplo: Se um contato que você conhece desde 2025 (com PN 5531999999999) interage usando nome de usuário, a Meta envia PN + BSUID juntos. A Blip reconhece e atualiza o contato existente.

⚠️Limitação: Para contatos que nunca conversaram com você, não há mapeamento automático. O mapeamento ocorre apenas quando há interação real.

 

Identificadores (IDs)

Qual é a diferença entre Blip ID, BSUID, WaId e Username?

Identificador O quê é Quem cria Escopo
Blip ID ID interno da Blip Blip Por contato na plataforma
BSUID Relação usuário ↔ empresa Meta Por empresa (Business Manager)
WaId Corresponde ao número de telefone do whatsapp – Global
Nome de usuário (Username) Nome público do usuário Usuário Global

O ID Blip será deprecado?

Não. O Blip ID é uma das novas identidades do contato.

Foi criado justamente para trazer estabilidade e independência ao modelo Meta. Você pode usar com segurança em todas as integrações.

 

Dados do Contato e Campos

Os campos extras (CPF, e-mail, nome) continuarão vindo?

Sim, sem impactos. Apenas o campo identity do contato evoluirá. Todos os demais continuam intactos:

  • CPF, e-mail, nome

  • Telefone (quando disponível)

  • Campos customizados

  • Extras

Mesmo quando o usuário oculta o PN (ativando o nome de usuário), a Blip continua enviando todos esses dados nos webhooks.

Como ficará o payload exato da mensagem?

Com PN compartilhado:

{
  "contact": {
    "identity": "5531999999999@wa.gw.msging.net",
    "phoneNumber": "5531999999999",
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "metadata": {
    "#wa.bsuid": "BR.1234567890123456",
    "#wa.username": "@meuUsername"
  }
}

Sem PN compartilhado (username ativo):

{
  "contact": {
    "identity": "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net",
    "phoneNumber": null,
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "metadata": {
    "#wa.bsuid": "BR.1234567890123456",
    "#wa.username": "@meuUsername"
  }
}

Mudanças-chave:

  • contact.identity pode ser GUID ou PN

  • contact.phoneNumber pode estar nulo

  • Novos campos no metadata: #wa.bsuid, #wa.username

  • Todos os outros campos continuam

 

Envio de Mensagens

Poderei enviar mensagens por BSUID, ID Blip e PN?

Sim. As APIs de envio passam a aceitar os três:

Por PN (já funciona):

POST /messages
{
  "to": "5531999999999@wa.gw.msging.net",
  "content": { "type": "text", "text": "Olá!" }
}

Por BSUID (novo):

POST /messages
{
  "to": "BR.1234567890123456@wa.gw.msging.net",
  "content": { "type": "text", "text": "Olá!" }
}

Por ID Blip (novo):

POST /messages
{
  "to": "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net",
  "content": { "type": "text", "text": "Olá!" }
}

O endpoint GET /accounts continuará funcionando?

Sim, evoluído. Continuará aceitando consultas por PN e agora também por BSUID:

GET /accounts?phoneNumbers=5531999999999
GET /accounts?bsuids=BR.1234567890123456

Resposta continua igual:

{
  "items": [
    {
      "id": "5531999999999",
      "bsuid": "BR.1234567890123456",
      "waId": "5531999999999"
    }
  ]
}

Sem mudanças. Funciona para usuários antigos e novos.

 

Campanhas e Disparos

Poderei enviar campanhas para números de telefone normalmente?

Sim, indefinidamente. Mesmo contatos com nome de usuário ativo continuam podendo receber mensagens por PN.

Importante: Quando você inicia a conversa por PN, a Meta retorna PN + BSUID na resposta. A Blip mapeia e atualiza o contato.

Detalhe importante: Quando você envia por PN para um contato que oculta o telefone:

  • Você consegue enviar (mesmo que o PN não seja compartilhado visualmente)

  • Na resposta, Meta retorna PN + BSUID (mesmo que o usuário não compartilhe)

  • Blip atualiza o contato automaticamente

Recomendação: Continue usando PN para bases existentes. Use BSUID quando não tiver PN.

E se eu só tiver BSUID de um contato que nunca conversou comigo?

Não é possível enviar para quem você nunca conversou apenas com BSUID. BSUID só existe quando há interação entre aquele usuário e sua empresa. Se você quer alcançar alguém que nunca conversou:

  1. Você precisa do PN

  2. Ou envie primeira mensagem por PN

  3. Dessa forma, Meta fornecerá o BSUID na resposta

Posso enviar campanhas usando números e BSUID intercalados?

Sim. Para campanhas em massa (CSV), você pode misturar:

recipient,nome
+55319XXXXXXXX,Carlos
BR.1234567890,Ana
+55319XXXXXXXX,Pedro

⚠️ Atenção: Se PN e BSUID do mesmo usuário estiverem presentes na mesma base, serão realizados 2 disparos para o mesmo usuário. Garantir deduplicação é sua responsabilidade.

 

Fluxos no Studio

Contact.identity pode conter GUID em vez de PN?

Sim, a partir de 01/06/2026.

HOJE:

contact.identity = "5531999999999@wa.gw.msging.net" (sempre PN)

A PARTIR DE 01/07:

contact.identity = pode ser:
  • "5531999999999@wa.gw.msging.net" (PN quando disponível)
  • "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net" (GUID se sem PN)

⚠️ O RISCO: Se você extrai o telefone assim:

const phone = contact.identity.split("@")[0];

Pode retornar um GUID em vez de telefone quando o usuário não compartilha o PN.

A SOLUÇÃO: Use novas variáveis:

contact.whatsAppWaId    // Retorna PN quando disponível, null se não
contact.whatsAppBsuid   // Retorna BSUID (sempre disponível)

Ação recomendada:

  1. No Studio → Analisar Fluxo

  2. Ferramenta marca blocos com risco

  3. Revise e ajuste usando novas variáveis

  4. Teste em homologação

Quais são as novas variáveis do Studio?

Novas variáveis :

  • contact.whatsAppBsuid → BSUID (sempre preenchido)

  • contact.whatsAppParentId → Parent BSUID (cross-BM)

  • contact.whatsAppUserName → Nome de usuário adotado pelo usuário

  • contact.waId → Corresponde ao número do usuário no WhatsApp (quando disponível)

Antigas (continuam, mas podem mudar formato):

  • contact.identity → Agora pode ser PN ou GUID

  • contact.phoneNumber → Pode ser null quando sem PN

  • tunnel.originator → Agora pode ser PN ou GUID

  • tunnel.identity → Agora pode ser PN ou GUID

Não são afetadas:

  • contact.name, contact.email, contact.extras (CPF, etc.)

 

Cronograma e Rollout

Qual é o cronograma oficial?

Meta:

  • Junho e Julho 2026: Alpha em alguns países selecionados (não afeta Brasil)

  • H2 2026: rollout progressivo global pela Meta (incluindo Brasil)

Importante: A adoção é por usuário, não por empresa.

  • Não há "data de mudança universal"

  • É gradual conforme cada pessoa ativa username

  • Empresa A pode ter 100k usuários SEM PN no 1º dia; Empresa B pode ter 10

Há prazo limite para se adequar?

Não há obrigatoriedade com prazo fixo, mas recomenda-se ação imediata.

  • Adoção dos nomes de usuários está prevista a partir de meados de setembro

  • Número de usuários sem PN compartilhado crescerá organicamente

  • Não há data de "desativação do PN"

Recomendação:

  • Adapte o quanto antes

  • Valide com o ambiente de testes

  • Monitore impactos no segundo semestre

 

Componentes de Template

Meta fornecerá um template para solicitar PN do usuário?

Sim, através de um componente específico de solicitação de contato.

Estrutura já conhecida:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

Workflow:

  1. Marca cria template com botão REQUEST_CONTACT_INFO

  2. Blip envia template → usuário vê "Compartilhar Contato"

  3. Usuário clica → compartilha PN

  4. Webhook dispara com #wa.contactOrigin: "contact_request"

Quando será liberado: Já está disponível via API.

Limitações de customização:

  • Tipo do botão: sempre "REQUEST_CONTACT_INFO"

  • Texto do botão: sempre "Share Contact Info" (Meta traduz automaticamente)

  • Pode customizar: texto do corpo, idioma, categoria

 

Estratégia de Preparação

Tenho 1 milhão de contatos antigos. Como faço o mapeamento?

Cenário 1 - Disparo ativo de mensagens:

Você envia: Disparo ativo por PN
Meta envia relatório de notificação: Meta envia PN + BSUID
Blip: Mapeia automaticamente
Histórico preservado

Cenário 2 - Mapeamento orgânico:

Usuário inicia contato
Meta envia BSUID (e PN ou nome de usuário, quando disponíveis)

Cenário 3 - Você quer forçar mapeamento:

Use: Endpoint GET /external-contacts-mapping
Retorna: de-para PN ↔ BSUID para contatos que Meta já enviou

⚠️ Limitação: Não há endpoint para consultar BSUID de um PN que nunca teve interação. A reconciliação ocorre apenas com contatos que já interagiram com a empresa.

Meu CRM usa PN como chave primária. O que faço?

Não precisa mudar agora, mas prepare-se.

Curto prazo (até dez/2026):

  • Mantenha PN como referência principal

  • Adicione campos: BSUID, ID Blip

  • Mapear PN → BSUID conforme interações acontecem

Médio prazo (a partir de 2027):

  • Migre para ID Blip como chave principal

  • Use PN como campo secundário "quando disponível"

  • BSUID como campo de referência Meta

Exemplo de migração:

-- ANTES
PRIMARY KEY: phone_number
-- DEPOIS
PRIMARY KEY: blip_id (guid)
UNIQUE KEY: bsuid
INDEX: phone_number (nullable)

Você pode fazer isso de forma gradual.

 

Casos Especiais

O que é Parent BSUID?

Um identificador para consolidar identidade entre múltiplos Business Managers da mesma organização.

Exemplo:

Sua Empresa (CNPJ: 123456789)
├─ Business Manager 1 (Venda)
│  └─ BSUID: BR.111111111111111
├─ Business Manager 2 (Suporte)
│  └─ BSUID: BR.222222222222222
└─ Parent BSUID: BR.ENT.999999999999999 ← Identifica que é mesma empresa

Quando um usuário interage com qualquer Business Manager da sua empresa, o Parent BSUID identifica que é a mesma pessoa em contextos diferentes.

Restrições:

  • Requer aprovação Meta

  • Nem todos Business Managers são elegíveis

  • Quando disponível, vem no metadata das mensagens

Um BSUID se repete em diferentes empresas?

Não, é único por empresa.

Usuário João
├─ Empresa A: BSUID = BR.111111111111111
├─ Empresa B: BSUID = BR.222222222222222
└─ Empresa C: BSUID = BR.333333333333333

Mesma pessoa, BSUIDs completamente diferentes. Isso é por design (privacidade + segurança).

Qual é o formato de um GUID?

Um GUID é um número de 128 bits (16 bytes) representado por 32 caracteres hexadecimais.

Formato padrão com hifens:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 Exemplo real:
e4b11bdd-a9bf-46ad-a9b0-34116dece5fe

 

Perguntas Gerais

O telefone vai desaparecer do WhatsApp?

Não. Toda conta WhatsApp continua vinculada a um telefone.

O que muda é que o número pode deixar de ser compartilhado automaticamente em algumas interações com usuários que ativarem o nome de usuário.

Que campos de template estão bloqueados para PN?

⚠️ Templates de autenticação (one-tap, zero-tap, copiar código) exigem obrigatoriamente o número de telefone.

Para mensagens de texto, mídia, botões e templates de marketing, o BSUID funciona normalmente.

Como saber se um contato compartilhou seu telefone via CTA?

Veja o metadata das mensagens:

{
  "metadata": {
    "#wa.contactOrigin": "contact_request",
    "#wa.sharedWaId": true
  }
}

Se ambos estão presentes e com esses valores, o contato compartilhou seu próprio telefone através do botão REQUEST_CONTACT_INFO.

 

Recursos Adicionais

 

Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃

Artigos relacionados