Nova API: BSUID e usernames da WhatsApp Business Platform

O que acabámos de lançar

Depois de lançar a API gratuita de links do WhatsApp, expandimos para o outro lado do WhatsApp: a Business Platform / Cloud API. Cinco novos endpoints, todos POST com corpo JSON, para quem constrói integrações, bots ou CRMs sobre a Cloud API oficial da Meta.

Esta API resolve um problema concreto: a Cloud API introduziu recentemente o BSUID (Business-Scoped User ID) e os usernames de negócio, e ambos aparecem agora em webhooks de mensagens e de estado — mas sem ferramentas prontas para validar, parsear ou normalizar esses dados. É isso que preenchemos.

O que é um BSUID

Um BSUID é um identificador único de utilizador, criado para conseguires mandar mensagem a alguém sem saberes o número de telefone. Formato: código de país ISO 3166 + ponto + até 128 caracteres alfanuméricos — por exemplo US.13491208655302741918. Contas geridas com múltiplos portfólios usam uma variante "parent": US.ENT.11815799212886844830.

BSUIDs são scoped a portfólio: só números de negócio dentro do mesmo portfólio conseguem usar um dado BSUID. É opaco — não deve ser dividido para uso em pedidos — mas às vezes precisas de o parsear para debug, logging ou apresentar numa dashboard interna. Daí os dois primeiros endpoints.

Os cinco endpoints

Mesmas garantias da API original: sem chave de API, sem registo, CORS ativo, 60 pedidos por minuto por IP, erros sempre em JSON com código estável.

Exemplos rápidos

Parsear um BSUID:

curl -X POST "https://whatsusernames.link/api/v1/business/bsuid/parse" \
  -H "Content-Type: application/json" \
  -d '{"bsuid": "US.13491208655302741918"}'

Resposta:

{ "countryCode": "US", "id": "13491208655302741918", "isParent": false }

Resolver um contacto a partir de um username (ou de um phone, ou de um bsuid — sempre exatamente um dos três):

curl -X POST "https://whatsusernames.link/api/v1/business/contact/resolve" \
  -H "Content-Type: application/json" \
  -d '{"username": "joao.silva"}'

Normalizar um webhook recebido diretamente da Cloud API, sem teres de escrever o teu próprio parser de payloads:

curl -X POST "https://whatsusernames.link/api/v1/business/webhook/normalize" \
  -H "Content-Type: application/json" \
  -d @webhook-payload.json

Porque normalizar webhooks importa

A Cloud API expõe o BSUID e o username em formas ligeiramente diferentes consoante o tipo de webhook: mensagens recebidas trazem from_user_id e um bloco contacts; atualizações de estado trazem recipient_user_id; falhas omitem o bloco contacts inteiramente. O endpoint webhook/normalize absorve essa variação e devolve sempre a mesma forma — kind, bsuid, phone, username, displayName, raw — para o teu handler de webhook não precisar de conhecer todos os casos.

Documentação completa

Todos os cinco endpoints estão documentados em whatsusernames.link/developers, com exemplos de corpo JSON para cada um, e na especificação OpenAPI 3.1 — agora com doze paths no total, incluindo os schemas novos (BsuidValidation, BsuidParse, ResolvedContact, NormalizedWebhook, entre outros).

Se estás a construir sobre a Cloud API e isto te poupa trabalho, adorávamos saber.