Usernames no WhatsApp Chegaram: Suporte a BSUID e BYON API v2
Resumo: o WhatsApp está liberando usernames. Quando um usuário adota um, a Meta pode parar de mandar o número de telefone dele nos seus webhooks e mandar um BSUID (business-scoped user ID) no lugar. Se o seu bot identifica usuários pelo telefone, essas mensagens quebram. O PipesBot agora trata BSUIDs em todo App BYON, e estamos lançando a BYON API v2, que entrega os payloads da Meta sem mexer em nada. Todos os webhooks de App agora são assinados.
O que a Meta está mudando
O WhatsApp está adicionando usernames país por país ao longo de 2026. Junto com isso, todo usuário ganha um BSUID, um por portfólio de negócio, tenha ele username ou não. O formato é BR.10293847561029384 (código do país, um ponto, e até 128 caracteres alfanuméricos).
A Meta omite o telefone do webhook quando as três condições abaixo são verdadeiras:
- O usuário tem username.
- Seu número comercial não conversou com ele nos últimos 30 dias.
- Ele não está na agenda de contatos hospedada pela Meta.
Quando isso acontece, messages[].from e contacts[].wa_id simplesmente não vêm (não vêm vazios, vêm ausentes), e campos novos carregam a identidade: from_user_id, contacts[].user_id e profile.username. Os status ganham recipient_user_id e podem perder o recipient_id.
A Meta não deu data de corte, mas diz que o suporte é obrigatório e que não há como recuperar mensagens que o negócio não conseguir processar. Um bot que faz users[message.from] vai receber uma mensagem sem from e vai quebrar ou responder para ninguém.
O que o PipesBot faz agora
Em todo App BYON (legacy incluído)
Você não precisa mudar nada para continuar recebendo mensagens de quem tem username:
fromNumber,fromewa_idpassam a conter o BSUID quando não há telefone.- O contato ganha
user_id,parent_user_ideprofile.username. Eventoswhatsapp_messageno WebSocket ganhamuserId,parentUserIdeusername. - Você responde para um BSUID usando o mesmo campo
toNumber/tode hoje. - Respostas pelo WebSocket agora vão para o contato salvo na conversa, e não para o número que o cliente mandou.
BYON API v2: os dados da Meta, intactos
A API legacy remodela os webhooks da Meta num formato do PipesBot e mantém um conversationId por remetente. Esse modelo assumia que telefone é uma chave estável, e o BSUID derruba essa premissa. Então a v2 abandona a remodelagem:
| Legacy | API v2 | |
|---|---|---|
| Entrada | Payload no formato PipesBot + conversationId | Um envelope por change da Meta, com o change.value original |
| Conversas | Salvas por remetente | Nenhuma. Nada para manter sincronizado |
| Status | Não entregues | sent, delivered, read, failed |
| Outros campos da Meta | Só status de template | Toda change que a Meta envia para seus números |
| Envio | toNumber | to (telefone ou BSUID), ou recipient no passthrough |
Um webhook v2 fica assim:
{
"id": "evt_3f9c1a7b2d4e4f6a8b0c1d2e3f4a5b6c",
"field": "messages",
"createdAt": "2026-10-08T10:30:01.123Z",
"pipes": { "appId": "app_xyz789", "poolNumberId": "pn_123", "media": {} },
"whatsapp": {
"messaging_product": "whatsapp",
"contacts": [{ "user_id": "BR.10293847561029384", "profile": { "name": "Ana", "username": "ana.costa" } }],
"messages": [{ "from_user_id": "BR.10293847561029384", "id": "wamid...", "type": "text", "text": { "body": "Oi!" } }]
}
}
Apps novos já nascem na v2. Apps existentes fazem o upgrade em Settings → Upgrade to API v2. O upgrade não tem volta: apaga as conversas salvas e as mensagens legacy na fila, e reconecta seus clientes WebSocket. URL de webhook, chaves, números e o histórico no WhatsApp continuam iguais. O guia de migração para v2 tem o checklist completo.
Como identificar seus usuários
Trate o BSUID como a identidade do usuário e o telefone como um atributo opcional que você pode descobrir depois:
function userKey(message: { from?: string; from_user_id?: string }) {
return message.from_user_id ?? message.from;
}
Isso vale para a v2, em que você recebe o messages[] cru da Meta. No legacy, fromNumber traz o telefone quando a Meta manda e o BSUID quando não manda, então o mesmo usuário pode aparecer com dois valores. Use o user_id do contato como chave e caia para o fromNumber só quando ele não vier.
Dois casos de borda para tratar:
- O BSUID muda quando o usuário troca de número. A Meta envia uma mensagem
system(user_changed_numberouuser_changed_user_id) comprevious_user_id. Use isso para mover seus registros para o id novo. - Alguns templates precisam de telefone de verdade. Templates de autenticação one-tap, zero-tap e copy-code falham com o erro
131062quando a Meta só tem o BSUID. Peça o número antes com um botão ou mensagem interativaREQUEST_CONTACT_INFO; o usuário decide se compartilha.
Webhooks assinados em todo App
Até agora, os webhooks de App não eram assinados. Toda entrega para a URL de webhook de um App (mensagens, status de template, number.onboarded) agora é assinada no padrão Standard Webhooks: headers webhook-id, webhook-timestamp e webhook-signature, com um secret whsec_ por App, que você pode ver e rotacionar no dashboard.
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.PIPES_WEBHOOK_SECRET!); // whsec_...
const event = wh.verify(rawBody, headers); // lança erro com assinatura inválida ou timestamp velho
Na v2, o webhook-id é igual ao id do envelope, que também é a chave para deduplicar: as entregas são at-least-once, e o mesmo evento pode chegar pelo webhook e pelo WebSocket. Mais detalhes em Webhook Security.
O que fazer nesta semana
- Encontre todo lugar onde seu código usa o telefone como chave de usuário e adicione o fallback de BSUID acima.
- Verifique as assinaturas dos webhooks.
- Planeje a migração para a API v2 se você ainda está no legacy. É o formato que continua funcionando conforme a Meta adiciona campos.
Se você está começando com webhooks para agentes de IA no WhatsApp, comece pelo nosso guia de webhooks. A referência da própria Meta é Business-scoped user IDs.