← Voltar ao Blog
novidades byon bsuid usernames-whatsapp webhooks api-v2

Usernames no WhatsApp Chegaram: Suporte a BSUID e BYON API v2

Read in English →

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:

  1. O usuário tem username.
  2. Seu número comercial não conversou com ele nos últimos 30 dias.
  3. 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, from e wa_id passam a conter o BSUID quando não há telefone.
  • O contato ganha user_id, parent_user_id e profile.username. Eventos whatsapp_message no WebSocket ganham userId, parentUserId e username.
  • Você responde para um BSUID usando o mesmo campo toNumber / to de 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:

LegacyAPI v2
EntradaPayload no formato PipesBot + conversationIdUm envelope por change da Meta, com o change.value original
ConversasSalvas por remetenteNenhuma. Nada para manter sincronizado
StatusNão entreguessent, delivered, read, failed
Outros campos da MetaSó status de templateToda change que a Meta envia para seus números
EnviotoNumberto (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_number ou user_changed_user_id) com previous_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 131062 quando a Meta só tem o BSUID. Peça o número antes com um botão ou mensagem interativa REQUEST_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

  1. Encontre todo lugar onde seu código usa o telefone como chave de usuário e adicione o fallback de BSUID acima.
  2. Verifique as assinaturas dos webhooks.
  3. 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.