Saltar al contenido principal

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. Ejemplo de nombre de usuario de WhatsApp

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.
Las plantillas de autenticación con un toque, toque cero y copia de código requieren un número de teléfono. No envíes estos tipos de plantilla solo con un BSUID.
Para vincular portafolios y usar BSUID principales, pide a tu punto de contacto de Meta que compruebe tu idoneidad. Puedes seguir utilizando BSUID normales dentro de sus portafolios originales después de que Meta habilite los BSUID principales. Ejemplo de identificador de usuario con ámbito empresarial

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 aceptan recipient: Establece recipient en un BSUID normal o en un BSUID principal. Omite to cuando quieras que YCloud se dirija al usuario por su BSUID.
Usa el mismo cuerpo de solicitud con 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ón REQUEST_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.
Crea y aprueba la plantilla antes de enviarla. Consulta Plantilla para solicitar el número de teléfono para ver una solicitud completa de plantilla.

Usar un mensaje interactivo

Envía un mensaje interactivo request_contact_info cuando no necesites una plantilla:

Gestionar la respuesta de contacto

Cuando el usuario comparte información de contacto, YCloud envía un evento whatsapp.inbound_message.received cuyo type de mensaje es contacts. Para una respuesta a tu solicitud, contacts[].origin es contact_request.
Valida la firma del evento, confírmalo con una respuesta 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. Botón para solicitar información de contacto

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. Configuración de la libreta de contactos de Meta

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

Usa GET /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.
Usa la clave de API de tu cuenta de YCloud. Las claves de API de Developer App devuelven HTTP 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:
HTTP 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}
Usa un BSUID estándar para esta operación. Los BSUID principales que contienen .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.
Para conocer el ciclo de vida completo de las llamadas, consulta Gestionar llamadas de WhatsApp.

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.
  • customerProfile aparece en las actualizaciones de mensajes sent, delivered y read, pero no en las actualizaciones de failed.
  • customerProfile.username está ausente cuando el usuario no ha habilitado los nombres de usuario. También está ausente de las actualizaciones de estado sent.
  • Un número de teléfono puede estar ausente incluso cuando el BSUID correspondiente está presente.
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.
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.
La preferencia permanece en whatsappUserPreference. Usa los identificadores de usuario proporcionados incluso cuando contactPhoneNumber esté ausente.
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.
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.
Los identificadores del destinatario son elementos del mismo nivel que recipientPhone bajo callingStatusUpdated.
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.
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.
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.
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

Cuando whatsappInboundMessage.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:
Trata todos los campos de identidad como opcionales. Los BSUID principales solo se proporcionan cuando están habilitados y disponibles. 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. Business username example

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 permiso manage_phone.

Prioridad de visualización en la ventana de chat

WhatsApp muestra la identidad de la empresa en este orden:
  1. El nombre guardado en los contactos del cliente.
  2. El nombre comercial verificado o el nombre de la cuenta oficial de empresa.
  3. El nombre de usuario de la empresa.
  4. El número de teléfono.
El número de teléfono de tu empresa permanece visible en el perfil de empresa.

Lista de comprobación para la migración

  1. Añade cada campo del Webhook relacionado con el BSUID a tu modelo de deserialización como un campo opcional.
  2. Almacena los BSUID normales y principales por separado de los números de teléfono y los nombres de usuario.
  3. Indexa la identidad del cliente por cartera y BSUID. No trates un BSUID como un identificador globalmente portátil.
  4. Enruta las solicitudes de mensajes y llamadas a través de to o recipient, y prueba la regla de prioridad de to.
  5. 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.