Nueva API: BSUID y usernames de la WhatsApp Business Platform

Qué acabamos de lanzar

Después de lanzar la API gratuita de enlaces de WhatsApp, nos expandimos al otro lado de WhatsApp: la Business Platform / Cloud API. Cinco nuevos endpoints, todos POST con cuerpo JSON, para quien construye integraciones, bots o CRMs sobre la Cloud API oficial de Meta.

Esta API resuelve un problema concreto: la Cloud API introdujo recientemente el BSUID (Business-Scoped User ID) y los usernames de negocio, y ambos aparecen ahora en webhooks de mensajes y de estado — pero sin herramientas listas para validar, parsear o normalizar esos datos. Eso es lo que completamos.

Qué es un BSUID

Un BSUID es un identificador único de usuario, creado para poder enviar un mensaje a alguien sin saber su número de teléfono. Formato: código de país ISO 3166 + punto + hasta 128 caracteres alfanuméricos — por ejemplo US.13491208655302741918. Las cuentas gestionadas con varios portafolios usan una variante "parent": US.ENT.11815799212886844830.

Los BSUID están limitados a un portafolio: solo los números de negocio dentro del mismo portafolio pueden usar un BSUID dado. Es opaco — no debe dividirse para usarlo en peticiones — pero a veces necesitas parsearlo para depuración, registro o un panel interno. Para eso son los dos primeros endpoints.

Los cinco endpoints

Mismas garantías que la API original: sin clave de API, sin registro, CORS habilitado, 60 peticiones por minuto por IP, errores siempre en JSON con código estable.

Ejemplos rápidos

Parsear un BSUID:

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

Respuesta:

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

Resolver un contacto a partir de un username (o de un phone, o de un bsuid — siempre exactamente uno de los tres):

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

Normalizar un webhook recibido directamente de la Cloud API, sin escribir tu propio parser de payloads:

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

Por qué normalizar webhooks importa

La Cloud API expone el BSUID y el username en formas ligeramente distintas según el tipo de webhook: los mensajes entrantes traen from_user_id y un bloque contacts; las actualizaciones de estado traen recipient_user_id; los fallos omiten el bloque contacts por completo. El endpoint webhook/normalize absorbe esa variación y siempre devuelve la misma forma — kind, bsuid, phone, username, displayName, raw — para que tu manejador de webhooks no necesite conocer todos los casos.

Documentación completa

Los cinco endpoints están documentados en whatsusernames.link/developers, con ejemplos de cuerpo JSON para cada uno, y en la especificación OpenAPI 3.1 — ahora con doce paths en total, incluyendo los nuevos schemas (BsuidValidation, BsuidParse, ResolvedContact, NormalizedWebhook, entre otros).

Si estás construyendo sobre la Cloud API y esto te ahorra trabajo, nos encantaría saberlo.