BSUID de WhatsApp: qué es el Business-Scoped User ID

Un BSUID es un identificador de usuario único y estable dentro de un portafolio empresarial. Permite reconocer y mensajear a una persona de WhatsApp aunque no conozcas su número de teléfono. Meta lo introdujo como parte del soporte de nombres de usuario: como una empresa no controla si sus usuarios adoptan un username, necesita un identificador propio que no dependa del teléfono.

Es un cambio de la WhatsApp Business API (Cloud API): existe en los payloads de webhooks y en las respuestas de la API, no en la WhatsApp Business APP. Meta indica en su documentación que soportar BSUID es requerido para partners, empresas integradas directamente y anunciantes de CTWA.

El BSUID se genera automáticamente y sigue una estructura fija.

<ISO-3166-alpha-2>.<hasta 128 caracteres alfanuméricos>

Ejemplo publicado en la documentación de Meta:

US.13491208655302741918

La regla práctica para diferenciarlo de un número de teléfono es simple: si el valor empieza con dos letras seguidas de un punto, es un BSUID; si tiene formato E.164 (por ejemplo +5491123456789), es un teléfono. Cualquier validación que asuma que un identificador de contacto es siempre numérico va a fallar.

El BSUID aparece en todos los webhooks de mensajes, exista o no un nombre de usuario. No requiere configuración previa.

El payload completo campo por campo, con ejemplos de JSON, está en cómo obtener el BSUID en el webhook de la Cloud API.

Un punto que suele malinterpretarse: el BSUID no es único por número de WhatsApp, sino por portafolio empresarial (antes llamado Business Manager).

• Cualquier número de empresa que pertenezca al mismo portafolio puede mensajear un BSUID de ese portafolio.
• Un intento de mensajear ese mismo BSUID desde un número de otro portafolio falla.
• La misma persona tiene un BSUID distinto en cada portafolio con el que conversa, por lo que dos empresas no pueden cruzar bases usando este identificador.

La estabilidad del identificador es lo que permite usarlo como clave de contacto en un CRM.

Por eso conviene procesar el webhook de cambio: trae el identificador viejo y el nuevo, y es el único momento en que hay que reescribir la clave del contacto. Los patrones de deduplicación están en cómo guardar el BSUID en tu CRM.

Adoptar un nombre de usuario no borra el teléfono de los webhooks de forma automática. Meta define condiciones concretas de inclusión del número.

1. El número de empresa envió un mensaje o una llamada al teléfono del usuario en los últimos 30 días.
2. El número de empresa recibió un mensaje o una llamada desde el teléfono del usuario en los últimos 30 días.
3. El usuario figura en el contact book del portafolio.

Las ventanas de 30 días se evalúan por número de empresa; el contact book, en cambio, es a nivel portafolio. Si no se cumple ninguna condición y el usuario tiene username, los campos contacts[].wa_id y messages[].from pueden omitirse: en ese escenario el BSUID es el único identificador disponible.

Son los dos mecanismos que Meta documenta para conservar u obtener el teléfono cuando el usuario usa un nombre de usuario.

DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book?messaging_product=whatsapp&bsuid=<BSUID>

El BSUID sirve como destinatario de casi cualquier tipo de mensaje dentro del mismo portafolio.

• Se puede usar para mensajes de sesión y para plantillas dentro de las reglas habituales de la ventana de 24 horas.
• Excepción documentada: las plantillas de autenticación one-tap, zero-tap y copy code siguen requiriendo el número de teléfono del usuario.
• El envío falla si el número de empresa pertenece a un portafolio distinto al del BSUID.

Meta ofrece un identificador adicional para casos multi-portafolio, pero no está abierto a todos.

Las empresas gestionadas pueden pedirle a su punto de contacto en Meta que evalúe la elegibilidad para inscribir sus portafolios y recibir parent BSUID. Si se aprueba, los webhooks de mensajes incluyen la propiedad parent_user_id, que identifica al mismo usuario en todos los portafolios inscriptos. La mayoría de las empresas no lo necesita: con un solo portafolio, el BSUID normal alcanza.

Checklist técnico derivado de las reglas anteriores.

1. Persistir siempre el user_id, incluso cuando el teléfono está presente.
2. Tratar los campos nuevos como opcionales en tus modelos de deserialización: user_id, username, recipient_user_id y, si aplica, parent_user_id.
3. Detectar el tipo de identificador antes de validarlo: dos letras + punto = BSUID; + y dígitos = E.164.
4. Manejar contactos sin teléfono: que tu modelo de datos permita un contacto identificado solo por BSUID.
5. Procesar el webhook de cambio de número para reasignar el BSUID viejo al nuevo sin duplicar el contacto.
6. Revisar las plantillas de autenticación: si usas one-tap, zero-tap o copy code, necesitas conservar el teléfono.

Si además vas a revisar la identificación de contactos de punta a punta, la secuencia recomendada está en preparar tu CRM para los nombres de usuario.

Solo hitos publicados en la documentación oficial. Meta aclara que el despliegue de nombres de usuario es gradual durante 2026 y que los cambios están sujetos a modificación.