Usernames na Meta API Oficial do WhatsApp já é realidade — como preparar sua integração

A Meta oficializou o suporte a usernames (nomes de usuário) na Cloud API do WhatsApp em 2026. Negócios podem agora reservar e reivindicar handles únicos — como @JasperMarket — através do WhatsApp Manager, Meta Business Suite ou via API dedicada. Para usuários finais, a funcionalidade permite ocultar o número de telefone e exibir apenas o username em conversas, aumentando a privacidade.

TL;DR: Usernames na WhatsApp Cloud API já estão disponíveis para reserva. A partir de julho de 2026, clientes que adotarem usernames podem enviar mensagens sem compartilhar telefone; empresas recebem apenas o BSUID (business-scoped user ID). É essencial integrar BSUID nos fluxos de CRM e atendimento antes do rollout completo.

A mudança tem impacto direto na forma como negócios identificam e armazenam contatos. Compreender o modelo BSUID e adaptar integrações existentes é crítico para evitar interrupções no atendimento.

O que são usernames no WhatsApp Business Platform?

Usernames funcionam como identificadores únicos e legíveis que empresas podem reivindicar para facilitar o contato com clientes. Em vez de compartilhar o número de telefone comercial completo, o negócio pode divulgar @SuaLoja em campanhas, perfis de redes sociais e materiais de marketing.

Do ponto de vista técnico, usernames são opcionais tanto para empresas quanto para usuários finais. Quando um cliente adota um username e inicia uma conversa pela primeira vez com uma empresa, a Cloud API retorna o BSUID em vez do número de telefone.

Como funciona o BSUID (business-scoped user ID)?

O BSUID é um identificador único e permanente vinculado ao relacionamento entre um usuário e uma conta comercial específica. Ele substitui o número de telefone em cenários onde o cliente escolheu privacidade.

Características do BSUID:

• Escopo por conta de negócio: cada empresa recebe um BSUID diferente para o mesmo usuário.
• Permanente: não muda ao longo do tempo, mesmo que o usuário altere seu username ou telefone.
• Privado: não permite identificação cruzada entre empresas.

A Meta projetou o BSUID para preservar a privacidade do usuário final sem comprometer a capacidade da empresa de manter histórico de conversas e dados de CRM.

Como reservar e reivindicar um username para seu negócio?

A Meta liberou a reserva de usernames antes do rollout completo. Negócios podem garantir handles desejados através de três canais:

1. WhatsApp Manager

Acesse o painel administrativo da conta comercial, navegue até configurações de perfil e insira o username desejado. A aprovação ocorre em até 48 horas, dependendo da disponibilidade e conformidade com políticas de nomenclatura.

2. Meta Business Suite

Mesma interface centralizada usada para gerenciar Facebook e Instagram. A aba WhatsApp agora inclui a opção de reivindicação de username.

3. Username API

Para empresas que gerenciam múltiplas contas ou oferecem soluções white-label, a Meta disponibilizou endpoints REST para reserva e gestão programática de usernames. A documentação oficial detalha autenticação, payloads e códigos de status.

Usernames reivindicados ficam reservados até que o recurso seja ativado na região geográfica da empresa. A Meta está iniciando o rollout gradual a partir de julho de 2026.

Impacto técnico: o que muda nas integrações com a Cloud API

A introdução de usernames e BSUIDs altera o comportamento padrão da Cloud API em conversas novas. Compreender as mudanças evita falhas em pipelines de CRM, roteamento de tickets e automações.

Cenário 1: Cliente existente com telefone já armazenado

Quando um cliente que já interagiu com a empresa no passado envia uma nova mensagem — mesmo após adotar username — a Cloud API continua retornando o número de telefone se:

• O Contact Book está habilitado (padrão).
• Houve interação recente (janela de 24 horas ou sessão ativa).

Impacto: nenhum. Fluxos existentes funcionam normalmente.

Cenário 2: Novo cliente com username adotado

Quando um usuário que nunca interagiu com a empresa envia a primeira mensagem e tem um username ativo, a Cloud API retorna apenas o BSUID no webhook de mensagem recebida. O campo from conterá o BSUID em vez do formato de número internacional.

Impacto: sistemas que dependem exclusivamente do número de telefone como chave primária falharão ao processar a mensagem.

Cenário 3: Cliente solicita compartilhamento do telefone

A Meta está introduzindo um novo Phone Number Request CTA (call-to-action) que permite solicitar o número do cliente diretamente na conversa. Se o usuário aceitar, o telefone é retornado na thread e automaticamente adicionado ao Contact Book.

Impacto: empresas podem recuperar números de telefone de forma transparente, sem depender de formulários externos ou mensagens manuais.

Novas capacidades disponíveis para suporte a usernames

A Meta anunciou duas funcionalidades críticas para garantir continuidade operacional durante a transição:

1. Envio via BSUID (business-scoped user ID)

Empresas poderão enviar mensagens business-initiated (templates aprovados) diretamente para o BSUID de um cliente, mesmo sem ter o telefone armazenado. Requisitos:

• Cliente deve ter iniciado uma conversa prévia com a empresa (para gerar o BSUID).
• Mensagem deve usar template aprovado pela Meta.
• A janela de atendimento de 24 horas não se aplica a BSUIDs para templates.

Exemplo de payload (curl):

curl -X POST "https://graph.facebook.com/v19.0/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "BSUID_DO_CLIENTE",
    "type": "template",
    "template": {
      "name": "nome_do_template",
      "language": { "code": "pt_BR" }
    }
  }'

2. Phone Number Request CTA

Botão nativo que solicita o telefone do cliente dentro da conversa. Quando acionado:

• O WhatsApp exibe um prompt solicitando permissão para compartilhar o número.
• Se o cliente aceitar, a Cloud API retorna o telefone via webhook.
• O número é automaticamente adicionado ao Contact Book da conta.

Implementação via mensagem interativa:

{
  "messaging_product": "whatsapp",
  "to": "BSUID_DO_CLIENTE",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": {
      "text": "Para continuar, compartilhe seu telefone."
    },
    "action": {
      "name": "phone_number_request"
    }
  }
}

Checklist de integração: prepare seu sistema para BSUID

Para evitar interrupções, sistemas que consomem a Cloud API devem adaptar fluxos de identificação e armazenamento de clientes. A Meta recomenda completar a integração antes de julho de 2026.

Passo 1: Atualizar schemas de banco de dados

Adicione suporte a BSUID como identificador alternativo ao telefone. Estrutura sugerida:

• Tabela clientes: adicione coluna bsuid (VARCHAR 128, UNIQUE).
• Índice único composto (phone, bsuid) para permitir ambos.
• Lógica de lookup: buscar primeiro por telefone; se nulo, buscar por BSUID.

Passo 2: Modificar parsers de webhooks

Webhooks de mensagens recebidas agora podem conter from como BSUID. Ajuste o parser para:

• Detectar se from é telefone (formato E.164) ou BSUID (string alfanumérica).
• Armazenar o BSUID na tabela de clientes se novo.
• Associar mensagens ao cliente correto via telefone ou BSUID.

Passo 3: Testar no ambiente Sandbox

A Meta disponibilizou Dummy API/Sandbox com suporte a BSUID. Simule:

• Recebimento de mensagem de novo cliente com BSUID.
• Envio de template via BSUID.
• Fluxo de Phone Number Request CTA e captura do telefone retornado.

Passo 4: Implementar Phone Number Request em fluxos críticos

Identifique jornadas onde o telefone é obrigatório (ex.: confirmação de pedido por SMS, integração com ERP legado). Adicione o CTA de solicitação de telefone antes desses pontos.

Passo 5: Atualizar CRM e ferramentas de roteamento

Sistemas de ticketing e CRM devem aceitar BSUID como identificador válido. Verifique:

• Zendesk, Intercom, Salesforce: campos customizados para BSUID.
• Ferramentas de automação (n8n, Zapier): mapear BSUID em triggers e ações.

Trade-offs e limitações do modelo de usernames

Apesar dos benefícios de privacidade, o modelo apresenta desafios operacionais:

Fragmentação de identidade

Clientes que alternam entre dispositivos ou reinstalam o WhatsApp podem gerar novos BSUIDs se não mantiverem o mesmo número de telefone vinculado. Isso dificulta unificação de histórico.

Dependência de Contact Book

Se o Contact Book for desabilitado, a Cloud API não retornará o telefone mesmo para clientes existentes após o rollout de usernames. Manter a funcionalidade ativa é crítico.

Complexidade em migrações de base

Empresas com milhões de contatos armazenados apenas por telefone precisarão reconciliar dados quando clientes começarem a enviar mensagens via BSUID. Estratégias de merge e deduplicação tornam-se essenciais.

Custo de SMS como fallback

Negócios que dependem de SMS para confirmações críticas perdem a capacidade de enviar mensagens se o cliente adotar username e não compartilhar o telefone. Alternativas: email, notificações in-app ou CTA de solicitação de telefone.

Principais aprendizados

• Usernames são opcionais, mas uma vez adotados pelo cliente, a Cloud API retorna apenas o BSUID em novas conversas.
• Envio via BSUID e Phone Number Request CTA garantem continuidade operacional sem dependência do telefone.
• Sistemas devem suportar dupla identificação (telefone e BSUID) antes de julho de 2026.
• Contact Book habilitado preserva fluxos existentes para clientes recorrentes.
• Testes no Sandbox são essenciais para validar integrações antes do rollout.

Alternativas fora da Cloud API oficial: quando considerar?

A Cloud API da Meta oferece recursos nativos robustos, mas apresenta overhead para negócios de menor porte ou casos de uso específicos. Alternativas como o Uazapi — solução brasileira de WhatsApp API independente — podem simplificar a operação.

Quando a Cloud API oficial faz sentido

• Operações globais com múltiplos números e contas.
• Necessidade de features nativas (catálogos, flows, BSUIDs).
• Time técnico com capacidade de integração e manutenção contínua.

Quando APIs alternativas podem ser mais eficientes

• Pequenas e médias empresas sem equipe de devs dedicada.
• Integração rápida com CRMs brasileiros (RD Station, Pipedrive).
• Fluxos de automação simples sem dependência de usernames.

A Rollin Host oferece soluções de agente de IA para WhatsApp gerenciado, com integração via Uazapi (R$ 38/mês) + configuração de IA conversacional (R$ 299/mês gerenciado + custos de API OpenAI ~R$ 50/mês). Setup completo em até 7 dias, sem necessidade de gerenciar infraestrutura de webhooks ou parsers.

Para operações que exigem alta disponibilidade e baixa latência, a Rollin Host mantém infraestrutura em Ashburn (EUA) e Frankfurt (Alemanha) com servidores AMD EPYC + NVMe e CDN Cloudflare com presença no Brasil, garantindo processamento rápido de webhooks e respostas instantâneas.

Perguntas frequentes

O que acontece se eu não integrar BSUID antes de julho?

Mensagens de novos clientes com username não serão processadas corretamente se o sistema depender exclusivamente do número de telefone. A Meta recomenda integrar antes do rollout regional para evitar perda de leads.

Posso enviar mensagens para um BSUID sem ter o telefone do cliente?

Sim, mas apenas templates aprovados (business-initiated messages). Mensagens de sessão livre (dentro da janela de 24h) exigem que o cliente tenha enviado a última mensagem.

O BSUID muda se o cliente alterar o username?

Não. O BSUID é permanente e vinculado ao relacionamento entre o usuário e a conta comercial, independentemente de alterações no username ou telefone.

Como solicito o telefone de um cliente que só compartilhou o BSUID?

Use o Phone Number Request CTA em uma mensagem interativa. O cliente receberá um prompt nativo do WhatsApp solicitando permissão para compartilhar o telefone.

Usernames funcionam com WhatsApp Business App (versão tradicional)?

Não. Usernames e BSUID são funcionalidades exclusivas da Cloud API e WhatsApp Business Platform. O app tradicional não suporta esses recursos.

Preciso pagar para reservar um username?

Não. A reserva e reivindicação de usernames são gratuitas. Custos aplicam-se apenas às mensagens enviadas, conforme o modelo de precificação padrão da Cloud API (conversas iniciadas pelo negócio são tarifadas).

Precisa de infraestrutura confiável para hospedar webhooks da Cloud API ou integrar automação de WhatsApp sem complicação? A Rollin Host oferece VPS Cloud Pro em Ashburn com tráfego ilimitado a partir de R$ 89,90/mês (anual) e soluções de agente de IA WhatsApp gerenciado. Entre em contato para configurar seu ambiente em até 7 dias.