Por qué existen los BSUID
WhatsApp está implementando nombres de usuario opcionales en 2026. Cuando un usuario adopta un nombre de usuario, WhatsApp puede mostrar el nombre de usuario en lugar del número de teléfono del usuario y puede omitir el número de teléfono de las cargas útiles de webhook. Cada usuario decide si adopta un nombre de usuario, por lo que las empresas no pueden depender de los números de teléfono como la única forma de identificar a los clientes. Por lo tanto, Meta exige a las empresas y socios de WhatsApp Business Platform, así como a los anunciantes de click-to-WhatsApp, que admitan BSUID para que puedan seguir procesando mensajes de usuarios que adoptan nombres de usuario. Para respaldar este cambio, Meta comenzó a añadir identificadores de usuario con ámbito empresarial (BSUID) a las cargas útiles de webhook a principios de abril de 2026. Un BSUID es un identificador de backend para un usuario de WhatsApp dentro de un portafolio comercial de Meta. Meta lo incluye en los webhooks de mensajes independientemente de si el usuario ha adoptado un nombre de usuario o no, y se puede utilizar para enviar mensajes al usuario cuando su número de teléfono no esté disponible. Los nombres de usuario y los BSUID tienen ciclos de vida diferentes. Un usuario puede cambiar su nombre de usuario sin cambiar su número de teléfono ni su BSUID. Si el usuario cambia su número de teléfono, Meta genera un nuevo BSUID. Almacena estos identificadores por separado y actualiza su asociación cuando recibas un evento de sistema de cambio de número de teléfono. Un número de teléfono aún puede aparecer cuando el número de teléfono comercial ha intercambiado un mensaje o una llamada con el usuario en los 30 días anteriores, o cuando la libreta de contactos de Meta contiene al usuario. Trata los campos de número de teléfono y nombre de usuario como condicionales, y actualiza los analizadores y el almacenamiento de identidades para aceptar BSUID junto con cualquier otro identificador presente. Esta guía cubre las reglas de identidad de BSUID, las solicitudes de mensajes y llamadas, la libreta de contactos de Meta y los campos de webhook que tu integración necesita almacenar.
Comprende los identificadores
Meta genera los BSUID normales automáticamente. Cada BSUID comienza con el código de país de dos letras ISO 3166 alpha-2 del usuario, seguido de un punto y hasta 128 caracteres alfanuméricos. Conserva el valor completo. No elimines ni modifiques el prefijo de país, el punto ni los caracteres del identificador.
Los BSUID tienen estas reglas de ciclo de vida:
- Un BSUID es único para un par específico de portafolio comercial y usuario.
- El BSUID de un usuario cambia cuando el usuario cambia su número de teléfono.
- Un BSUID principal funciona en todos los portafolios vinculados para los que Meta lo haya habilitado.
- Un número de teléfono comercial no puede usar un BSUID normal con ámbito definido para otro portafolio.
Antes de comenzar
- Almacena tu clave de API de YCloud en
YCLOUD_API_KEY. - Usa un número de teléfono comercial de WhatsApp que pertenezca al mismo portafolio que el BSUID normal.
- Suscribe tu endpoint de webhook a los eventos de WhatsApp que utilice tu integración.
- Trata cada nuevo campo de BSUID, BSUID principal, número de teléfono y nombre de usuario como opcional al deserializar webhooks.
- Almacena el BSUID normal y el BSUID principal de forma independiente cuando ambos estén presentes.
Envía un mensaje con un BSUID
Ambos endpoints de mensajes de WhatsApp aceptanrecipient:
Establece
recipient en un BSUID normal o en un BSUID principal. Omite to cuando quieras que YCloud se dirija al usuario por su BSUID.
POST /whatsapp/messages para encolar el mensaje.
Solicitar el número de teléfono de un usuario
Usa un mensaje para solicitar información de contacto cuando tu flujo de trabajo necesite un número de teléfono que no se haya incluido en un webhook. El usuario decide si compartirlo.Usar un botón de plantilla
Añade un botónREQUEST_CONTACT_INFO a una plantilla de utilidad o de marketing. El texto del botón está fijado como Share Contact Info, y el botón no admite parámetros en el momento del envío.
Usar un mensaje interactivo
Envía un mensaje interactivorequest_contact_info cuando no necesites una plantilla:
Gestionar la respuesta de contacto
Cuando el usuario comparte información de contacto, YCloud envía un eventowhatsapp.inbound_message.received cuyo type de mensaje es contacts. Para una respuesta a tu solicitud, contacts[].origin es contact_request.
2xx y procesa el número de teléfono de forma asíncrona. Un contacto compartido directamente desde WhatsApp también puede incluir una vCard.
Comprender la libreta de contactos de Meta
La libreta de contactos de Meta almacena la asociación entre el número de teléfono de un usuario y su BSUID. Con la función habilitada, enviar o recibir un mensaje o llamada utilizando el número de teléfono del usuario registra ambos identificadores. Meta puede entonces incluir esa asociación en los webhooks incluso después de que el usuario adopte un nombre de usuario. Las libretas de contactos pertenecen a carteras comerciales individuales. Las carteras vinculadas no comparten ni sincronizan sus entradas: registra la asociación de forma independiente en cada cartera. Meta conserva las entradas hasta que deshabilites la función o desactives tu cuenta. Puedes deshabilitarla en Meta Business Suite > Configuración del negocio > Información del negocio. Deshabilitar la función elimina las entradas almacenadas y deja de registrar nuevas. Volver a habilitarla empieza a recopilar nuevas entradas; no restaura los datos eliminados.
Solicitudes de contacto y almacenamiento local
Cuando un usuario comparte su número de teléfono a través de un botón para solicitar información de contacto, Meta añade el número de teléfono a la libreta de contactos si la función está habilitada. Para las empresas que usan almacenamiento local, Meta extrae el número de teléfono de la vCard compartida y lo almacena en la libreta de contactos en los centros de datos de Meta. El resto de datos de la vCard no se conservan más allá del periodo de retención estándar. Meta eliminó el requisito previo de enviar un mensaje independiente para registrar esta asociación. Consulta la documentación oficial de BSUID para conocer el comportamiento actual del almacenamiento local.Comprobar una entrada de la libreta de contactos de Meta
UsaGET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid} para comprobar si Meta tiene una entrada de número de teléfono para un BSUID estándar. Esta operación no devuelve el número de teléfono ni modifica la entrada.
403. La WABA debe estar disponible para tu cuenta, el número de teléfono debe estar vinculado a esa WABA y el BSUID estándar debe pertenecer a la misma cartera comercial de Meta. Los BSUID principales que contienen .ENT. no son compatibles. Codifica en formato URL el + inicial del número de teléfono como %2B cuando construyas la ruta manualmente.
Una respuesta correcta siempre incluye el booleano present:
200 con present: false significa que no existe ninguna entrada coincidente. Las entradas no válidas, los fallos de permisos y los errores de origen siguen siendo errores. Un HTTP 404 ascendente no significa present: false.
Eliminar una entrada de la libreta de contactos de Meta
Elimina una entrada de la libreta de contactos de Meta para un BSUID normal a través de un número de teléfono comercial de WhatsApp con:DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}
.ENT. no son compatibles. Codifica en formato URL el + inicial en el número de teléfono como %2B cuando construyas la ruta manualmente.
Una respuesta HTTP 200 siempre contiene success: true. Un valor de deleted de true significa que Meta eliminó una entrada coincidente. Un valor de false significa que Meta procesó la solicitud pero no encontró ninguna entrada coincidente.
Eliminar la entrada no borra los contactos de YCloud, los mensajes ni los registros comerciales de BSUID. Tras la eliminación, los eventos de webhook para los números de teléfono comerciales en la misma cartera comercial de Meta ya no incluirán el número de teléfono del usuario y el BSUID juntos. La caché de 30 días de Meta aún puede suministrar ambos identificadores, y una interacción posterior puede volver a crear la entrada en la libreta de contactos.
Iniciar una llamada con un BSUID
POST /whatsapp/calls/connect también acepta recipient. Se aplican las mismas reglas de destino: proporciona to o recipient, y to tiene prioridad cuando ambos están presentes.
Procesar los campos de webhook de BSUID
Las siguientes cargas útiles de Webhook de YCloud muestran los campos añadidos o modificados para la compatibilidad con BSUID. Actualiza tu analizador para aceptar los nuevos identificadores y gestionar los números de teléfono de clientes faltantes.
Los ejemplos incluyen el contenedor de eventos de YCloud y muestran dónde aparece cada campo. Los campos opcionales siguen las reglas de omisión que figuran más abajo. Elimina los comentarios
// <ADDED> y // <CHANGED> antes de usar una carga útil como datos de prueba JSON.
Aplica estas reglas de omisión:
- Un campo BSUID principal está ausente cuando los BSUID principales no están habilitados.
- Un campo de destino de mensaje enviado o de llamada puede estar ausente cuando te dirigiste al usuario por número de teléfono.
customerProfileaparece en las actualizaciones de mensajessent,deliveredyread, pero no en las actualizaciones defailed.customerProfile.usernameestá ausente cuando el usuario no ha habilitado los nombres de usuario. También está ausente de las actualizaciones de estadosent.- Un número de teléfono puede estar ausente incluso cuando el BSUID correspondiente está presente.
whatsapp.message.updated
whatsapp.message.updated
El ejemplo muestra un mensaje entregado.
<CHANGED> marca to como condicional cuando el número de teléfono no está disponible. El nuevo objeto customerProfile se omite para failed; su username también se omite para sent o cuando el usuario no tiene nombre de usuario.whatsapp.inbound_message.received
whatsapp.inbound_message.received
Almacena los nuevos identificadores del remitente junto con el nombre de perfil existente. El destinatario comercial
to no cambia; el número de teléfono del cliente from puede omitirse. Consulta el ejemplo de cambio de número de teléfono que aparece a continuación para ver un mensaje system.whatsapp.user.preferences
whatsapp.user.preferences
La preferencia permanece en
whatsappUserPreference. Usa los identificadores de usuario proporcionados incluso cuando contactPhoneNumber esté ausente.whatsapp.call.connect
whatsapp.call.connect
Para las llamadas iniciadas por la empresa, los identificadores del cliente son
toUserId y toParentUserId. Para las llamadas iniciadas por el usuario, son fromUserId y fromParentUserId. Solo el campo del número de teléfono del cliente se puede omitir en estos ejemplos.- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.terminate
whatsapp.call.terminate
Para las llamadas iniciadas por la empresa, los identificadores del cliente son
toUserId y toParentUserId. Para las llamadas iniciadas por el usuario, son fromUserId y fromParentUserId. Solo el campo del número de teléfono del cliente se puede omitir en estos ejemplos.- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.status.updated
whatsapp.call.status.updated
Los identificadores del destinatario son elementos del mismo nivel que
recipientPhone bajo callingStatusUpdated.whatsapp.group.participants_update
whatsapp.group.participants_update
Una actualización de un solo participante puede incluir identificadores directamente bajo
whatsappGroup. Los resultados por lotes los incluyen en cada elemento de addedParticipants, removedParticipants o failedParticipants. Procesa la matriz correspondiente a la operación en el evento.- added
- removed
- failed
whatsapp.smb.history
whatsapp.smb.history
Conserva el contenedor específico del evento: el historial entrante utiliza
whatsappInboundMessage, mientras que el historial saliente utiliza whatsappMessage. toUserId y toParentUserId salientes son alias de compatibilidad de recipientUserId y parentRecipientUserId. Estos ejemplos muestran eventos que contienen mensajes; un fragmento de historial solo con metadatos puede omitir ambos objetos de mensaje.- Historial entrante
- Historial saliente
whatsapp.smb.app.state.sync
whatsapp.smb.app.state.sync
Esta carga útil se conserva de la documentación de migración de BSUID heredada. Este evento no figura en el catálogo público actual de eventos a los que es posible suscribirse; no lo agregues a
enabledEvents basándote en este ejemplo. Usa la estructura que aparece a continuación si mantienes una integración que ya recibe esta carga útil heredada.whatsapp.smb.message.echoes
whatsapp.smb.message.echoes
Estos son mensajes enviados desde la aplicación WhatsApp Business o un dispositivo complementario compatible. Los nombres de campo heredados
toUserId y toParentUserId son alias de compatibilidad de recipientUserId y parentRecipientUserId. Mantén el perfil bajo whatsappMessage.Gestionar los cambios de número de teléfono y BSUID
CuandowhatsappInboundMessage.type es system, gestiona ambas variantes
de cambio de identidad:
Usa
system.user_id y cualquier system.parent_user_id suministrado para la nueva identidad. Usa system.previous_user_id y system.previous_parent_user_id para la identidad anterior cuando se proporcionen. Estos campos anidados conservan los nombres originales en snake_case de Meta.
El siguiente ejemplo muestra un cambio de número de teléfono:
wa_id es un número de teléfono sin el + inicial y se puede omitir; para user_changed_user_id, también puede permanecer sin cambios. No borres un número de teléfono existente solo porque el evento lo omita. Conserva los identificadores anteriores y nuevos el tiempo suficiente para conciliar las conversaciones existentes y actualizar de forma idempotente tu almacén de identidades.
Consulta Inbound BSUID change message para ver un ejemplo sin número de teléfono.
Nombres de usuario de la empresa
Un nombre de usuario de empresa ayuda a que los clientes encuentren tu empresa en WhatsApp. No oculta el número de teléfono de tu empresa. Cada número de teléfono puede tener un nombre de usuario, y dos números de teléfono de WhatsApp no pueden compartir un mismo nombre de usuario. El nombre de usuario de un cliente puede cambiar sin que cambie su BSUID. Conserva el nombre de usuario como información de perfil en lugar de utilizarlo como tu clave de identidad. Consulta Claim a business username para conocer las reglas de formato de 3 a 35 caracteres y el proceso de reclamación y revisión.
Nombres de usuario reservados
Puedes reclamar un nombre de usuario apto reservado por Meta o elegir otro nombre de usuario para tu marca. Usa WhatsApp Manager, Meta Business Suite o la API de nombres de usuario. La aprobación no significa por sí sola que un nombre de usuario esté activo para los clientes. Si el nombre de usuario reservado pertenece a tu página de Facebook o cuenta de Instagram, vincula el número de teléfono de tu empresa a esa página o cuenta antes de reclamarlo. Puedes vincularlo mientras reclamas el nombre de usuario en Meta Business Suite o WhatsApp Manager, o añadir el número de teléfono a la página o cuenta. Necesitas control total o acceso parcial básico con el permisomanage_phone.
Prioridad de visualización en la ventana de chat
WhatsApp muestra la identidad de la empresa en este orden:- El nombre guardado en los contactos del cliente.
- El nombre comercial verificado o el nombre de la cuenta oficial de empresa.
- El nombre de usuario de la empresa.
- El número de teléfono.
Lista de comprobación para la migración
- Añade cada campo del Webhook relacionado con el BSUID a tu modelo de deserialización como un campo opcional.
- Almacena los BSUID normales y principales por separado de los números de teléfono y los nombres de usuario.
- Indexa la identidad del cliente por cartera y BSUID. No trates un BSUID como un identificador globalmente portátil.
- Enruta las solicitudes de mensajes y llamadas a través de
toorecipient, y prueba la regla de prioridad deto. - Prueba usuarios solo con nombre de usuario, números de teléfono ausentes, cambios de número de teléfono, cambios de BSUID con un número de teléfono sin cambios, BSUID principales ausentes, webhooks duplicados, y la presencia y recreación en la libreta de contactos.
Ejemplos de estados de mensaje
Inspecciona las cargas útiles de mensajes enviados, entregados, leídos y fallidos.
Ejemplos de mensajes entrantes
Inspecciona contactos, actualizaciones del sistema y otras cargas útiles entrantes.

