Una integración de la WhatsApp Business API identifica a un cliente que usa un nombre de usuario de WhatsApp por un ID de usuario a nivel de empresa (BSUID), un código único para cada par de cliente y portfolio comercial. El webhook sigue incluyendo el número de teléfono cuando el mismo número de la empresa intercambió un mensaje o una llamada con el cliente en los últimos 30 días. El número también se mantiene en los webhooks para los clientes que están en la libreta de contactos (Contact Book), una lista que Meta guarda con los números de teléfono de conversaciones anteriores. Cualquier otro mensaje de un cliente con nombre de usuario llega con un BSUID y sin número de teléfono. Un controlador de webhooks debe aceptar los mensajes que llegan con un BSUID y sin número de teléfono. Si los rechaza, esos mensajes se pierden, y Meta no tiene forma de volver a enviarlos.
Puntos clave
- Meta exige a los socios, a las empresas con integración directa y a los anunciantes de clic a WhatsApp en la plataforma de WhatsApp Business que admitan los BSUID.
- El número de teléfono de un cliente sigue llegando durante 30 días después de un mensaje o una llamada con el mismo número de la empresa, y mientras el cliente siga en la libreta de contactos.
- Un mensaje puede ir a un BSUID, a un número de teléfono o a ambos, y solo las plantillas de autenticación de un solo toque, sin toque y de copiar código todavía necesitan el número de teléfono.
- Una empresa que necesita un número de teléfono puede pedirlo en el chat con un botón, y el cliente decide si lo comparte.
- 360Dialog, un Official Meta Solution Partner, les da a las empresas acceso a la WhatsApp Business API, que acepta los BSUID como destinatarios de los mensajes.
¿Qué es un ID de usuario a nivel de empresa (BSUID)?
Un ID de usuario a nivel de empresa (BSUID) es un identificador que WhatsApp genera para cada par de cliente y portfolio comercial, y llega en los webhooks tenga o no el cliente un nombre de usuario. Guardarlo le da a una integración una clave de cliente única que sigue funcionando cuando un cliente deja de compartir su número de teléfono.
Un nombre de usuario es un nombre único y opcional que un usuario de WhatsApp puede mostrar en lugar de su número de teléfono, y WhatsApp está lanzando los nombres de usuario de forma gradual.[1] Nuestra guía sobre nombres de usuario de WhatsApp para empresas explica qué cambia para los clientes y para los equipos que les responden.
Meta exige a todos los socios y a las empresas con integración directa en la plataforma de WhatsApp Business que admitan los BSUID, y el requisito se extiende a los anunciantes de clic a WhatsApp.[2] Los BSUID aparecen en los webhooks desde principios de abril de 2026. En la Cloud API, el valor está en el campo user_id de cada webhook messages.
Guarda y envía cada BSUID completo, porque una solicitud con una parte faltante o modificada falla. Una columna de base de datos para el BSUID necesita espacio para el código de país de dos letras, el punto y hasta 128 letras y dígitos después. Cada BSUID funciona dentro de un portfolio comercial, antes llamado Business Manager, y solo los números de teléfono de empresa de ese portfolio pueden enviarle mensajes. Por eso, el mismo cliente tiene un BSUID distinto en cada portfolio.
¿Cuándo sigue devolviendo la API el número de teléfono de un cliente?
Los webhooks siguen trayendo el número de teléfono de un cliente cuando ese número de teléfono de empresa intercambió un mensaje o una llamada con el cliente en los últimos 30 días, o cuando el cliente está en la libreta de contactos de la empresa. Saber qué caso aplica le indica a un equipo qué conversaciones necesitan primero el manejo de BSUID.
Cinco situaciones deciden qué identificadores trae un webhook, según la documentación de Meta sobre los BSUID.
| Situación | Número de teléfono | BSUID |
|---|---|---|
| El cliente no tiene nombre de usuario | Incluido | Incluido |
| El cliente tiene nombre de usuario, y este número de la empresa intercambió con él un mensaje o una llamada en los últimos 30 días | Incluido | Incluido |
| El cliente tiene nombre de usuario y está en la libreta de contactos del portfolio | Incluido | Incluido |
| El cliente tiene nombre de usuario y comparte su número con el botón Solicitar información de contacto | Incluido en un webhook contacts | Incluido |
| El cliente tiene nombre de usuario y no cumple ninguna de las condiciones anteriores | Omitido | Incluido |
La verificación de 30 días se hace por número de teléfono de empresa, mientras que la libreta de contactos cubre todo el portfolio. Un cliente que regresa fuera de ambos casos puede aparecer como una conversación nueva. Las llamadas cuentan igual que los mensajes, incluidas las llamadas hechas con la WhatsApp Calling API. Una conversación que empieza desde anuncios de clic a WhatsApp sigue las mismas condiciones.
¿Cómo funciona la libreta de contactos en la API?
La libreta de contactos es una lista que Meta aloja para cada portfolio comercial, y guarda el número de teléfono de un cliente junto a su BSUID una vez que el cliente y la empresa intercambian un mensaje o una llamada. Mientras un cliente siga en ella, los webhooks siguen trayendo su número de teléfono después de que se cierra la ventana de 30 días. Dos llamadas a la API le permiten a una integración verificar y eliminar entradas individuales.
La libreta de contactos no necesita configuración, y las entradas se mantienen hasta que la empresa desactiva la función en Meta Business Suite, en Configuración del negocio > Información del negocio, o desactiva su cuenta. Al desactivarla se borran todas las entradas para siempre. Solo registra las interacciones ocurridas después de que Meta la lanzó, y sus números de teléfono aparecen únicamente en las cargas útiles de los webhooks.
Meta agregó la llamada de verificación el 24 de agosto de 2026 y cambió la respuesta de la llamada de eliminación el 25 de agosto de 2026.[3] Ambas llamadas aceptan un BSUID estándar y rechazan los BSUID principales.
| Llamada | Solicitud | Respuesta |
|---|---|---|
| Verificar | GET /<BUSINESS_PHONE_NUMBER_ID>/contact_book?messaging_product=whatsapp&bsuid=<BSUID> | contacts con bsuid y present (true o false), nunca el número de teléfono |
| Eliminar | DELETE en la misma ruta | success y deleted, con deleted en false para cualquier BSUID sin entrada |
Un valor deleted en false se ve igual para un BSUID desconocido, uno no válido y uno de otro portfolio. Después de una eliminación, el número de teléfono todavía puede aparecer dentro de la ventana de 30 días o después de una nueva interacción.
¿Cómo pides un número de teléfono con el botón Solicitar información de contacto?
El botón Solicitar información de contacto le pide a un cliente que comparta su número de teléfono en el chat, y el número vuelve en un webhook contacts junto al BSUID. Permite que cualquier flujo que necesite un número de teléfono lo obtenga dentro de la conversación, con el consentimiento del cliente.
El botón está disponible desde principios de julio de 2026 en plantillas de utilidad y de marketing, y en un mensaje interactivo. Un número compartido de esta forma también entra automáticamente en la libreta de contactos cuando la empresa la usa. Las pautas de Meta piden que los bots que necesitan un número lo soliciten y que atiendan a los clientes que prefieren no compartirlo.
¿Cómo envías mensajes a un BSUID?
Una empresa envía un mensaje a un BSUID con la misma solicitud de envío que usa para los números de teléfono, con el BSUID en un campo propio. Enviar mensajes por BSUID le permite a una empresa seguir hablando con clientes cuyo número de teléfono nunca recibió.
Meta fecha el envío por BSUID a partir de julio de 2026. Una solicitud identifica al cliente por número de teléfono, por BSUID o por ambos, y el número de teléfono tiene prioridad cuando están los dos.
Todos los tipos de mensaje funcionan con un BSUID, excepto las plantillas de autenticación de un solo toque, sin toque y de copiar código, que todavía necesitan un número de teléfono. La Marketing Messages API también acepta los BSUID, y Meta recomienda usar números de teléfono ahí porque así los webhooks siguen devolviendo el número.
Nuestra documentación sobre nombres de usuario y BSUID muestra la solicitud de envío completa, la respuesta y los códigos de error en la API de 360Dialog.[4]
¿Qué cambia en los webhooks?
Los webhooks ahora traen el BSUID del cliente en cada mensaje entrante y en los estados enviado, entregado y leído, y el número de teléfono aparece solo cuando se cumple una de las condiciones de número de teléfono de Meta. Un analizador que trata el BSUID como el identificador obligatorio sigue procesando todos los mensajes.
El BSUID está junto al número de teléfono en las mismas cargas útiles, en campos propios. Los campos de número de teléfono aparecen cuando el cliente no tiene nombre de usuario, cuando se cumple una condición de número de teléfono o cuando el mensaje se envió a un número de teléfono, y el nombre de usuario del cliente llega como dato de perfil cuando tiene uno. Los campos que no aplican se omiten de la carga útil.
Un cambio de número de teléfono le da al cliente un BSUID nuevo, que se informa en el webhook messages como un mensaje del sistema de tipo user_changed_number o user_changed_user_id. Ambos incluyen previous_user_id, el BSUID anterior. Una integración lo usa para encontrar el registro de cliente que ya tiene guardado. Meta no documenta ningún campo de webhook user_id_update aparte.
¿Cómo administras un nombre de usuario de empresa a través de la API?
Una empresa configura, consulta y elimina el nombre de usuario de cada número de teléfono de empresa con la API de nombres de usuario (Username API) de Meta, que también informa los cambios de estado por webhook. Integrar estas llamadas en una plataforma le permite a un equipo controlar los nombres de usuario de muchos números en un solo lugar.
Una empresa puede configurar o cambiar un nombre de usuario para cada número de teléfono de empresa, consultar su estado, aprobado o reservado, y eliminarlo, y una llamada de sugerencias devuelve nombres reservados con más probabilidades de aprobación. Un nombre de usuario aprobado se activa cuando los nombres de usuario están disponibles en el país de la empresa. Los clientes de 360Dialog lo hacen con los puntos de conexión de nombre de usuario de empresa de nuestra referencia de la API.[5]
Cada número de teléfono de empresa puede configurar 2 nombres de usuario nuevos en cualquier período de 14 días consecutivos, o 10 cuando el resultado tiene estado reservado, y una solicitud que supera el límite falla. El conteo se lleva por número, y eliminar un nombre de usuario no lo modifica.
El webhook business_username_updates, al que se suscribe cada app, informa los estados aprobado, eliminado y reservado. Cuando Meta revoca un nombre de usuario, el webhook lo indica, y el nombre de usuario se elimina o se reemplaza por uno generado.
¿Cómo funcionan los BSUID principales en varios portfolios?
Un BSUID principal es un identificador por cliente que puede usar cada portfolio comercial inscrito en la misma cuenta de BSUID principal. Permite que una empresa administrada con varios portfolios reconozca al mismo cliente en todos ellos.
Meta ofrece los BSUID principales a empresas administradas, y el contacto de Meta de la empresa verifica la elegibilidad. Después, los webhooks traen el BSUID principal junto al BSUID normal, en parent_user_id, from_parent_user_id y recipient_parent_user_id. Un BSUID principal agrega ENT después del código de país, y cualquier número de teléfono de empresa de un portfolio inscrito puede enviarle mensajes.
La inscripción no cambia los controles de acceso, la facturación ni la administración de cada portfolio. Las libretas de contactos siguen separadas por portfolio. Para listar los portfolios inscritos, una empresa llama a GET https://api.facebook.com/<BUSINESS_ID>/parent-bsuid-accounts, que devuelve parent_bsuid_account_id y enrolled_business_portfolios.
Las plataformas que operan una integración de WhatsApp multicliente mantienen los BSUID de cada cliente dentro del portfolio de ese cliente.
¿Qué debería manejar tu integración ahora?
Una integración lista para los BSUID guarda el BSUID como identificador central del cliente, trata el número de teléfono como opcional y pide un número solo donde un flujo lo necesita. Estos cambios mantienen cada conversación vinculada al registro de cliente correcto.
En la práctica, los analizadores de webhooks y las columnas de base de datos aceptan mensajes que traen solo un BSUID, y cada registro de cliente guarda el BSUID junto al número de teléfono. Así, los sistemas de CRM, campañas, medición y facturación también identifican a los clientes por BSUID. Los flujos que necesitan un número lo piden con el botón Solicitar información de contacto y mantienen una alternativa para los clientes que prefieren no compartirlo, y la herramienta de prueba de webhooks de Meta verifica el analizador en cada caso. Los equipos que planean respuestas asistidas por IA pueden leer cómo funciona el agente de IA con la API en nuestra guía completa de Meta Business Agent. Cuando cada sistema identifica a los clientes por BSUID, cada conversación llega al registro de cliente al que pertenece, y el agente que la responde ve el historial completo.
360Dialog es un Official Meta Solution Partner para la WhatsApp Business API, y nuestra documentación sobre nombres de usuario y BSUID ofrece la lista de verificación de integración paso a paso, con las solicitudes de envío y las cargas útiles de webhooks en la API de 360Dialog. Obtener acceso a la API te permite crear y probar el manejo de BSUID en tu propio número de la WhatsApp Business API. Habla con nosotros para preparar tu integración de la WhatsApp Business API para los BSUID.
Preguntas frecuentes
¿Una empresa puede enviar mensajes a un cliente por su nombre de usuario?
Una empresa no puede usar un nombre de usuario como dirección de mensaje en la WhatsApp Business API. Las solicitudes de envío aceptan un número de teléfono en el campo to o un BSUID en el campo recipient. El nombre de usuario llega en los webhooks como dato de perfil, y el cliente puede cambiarlo cuando quiera. El BSUID se mantiene y es el identificador que conviene guardar.
¿Los mensajes de autenticación todavía se envían a números de teléfono?
Las plantillas de autenticación de un solo toque, sin toque y de copiar código todavía van al número de teléfono del cliente, y enviar una a un BSUID falla con el error 131062. Una empresa que solo tiene un BSUID puede pedir primero el número con el botón Solicitar información de contacto. Cuando el cliente lo comparte, la empresa envía la plantilla de autenticación a ese número.
¿Cómo pruebas un controlador de webhooks para BSUID?
La herramienta de prueba de webhooks de Meta envía al controlador cargas útiles de ejemplo con BSUID desde el Panel de apps. Abre Casos de uso, luego Conectarse con los clientes a través de WhatsApp, Personalizar y Configuración, y selecciona Probar junto al campo messages. Cubre cuatro casos: sin nombre de usuario, nombre de usuario sin número de teléfono, nombre de usuario con número y carga útil con BSUID principal.
¿Los socios deben actualizar las integraciones de sus clientes para los BSUID?
Los socios de la plataforma de WhatsApp Business deben admitir los BSUID, igual que las empresas con integración directa y los anunciantes de clic a WhatsApp. La app de un socio puede enviar mensajes a los BSUID de un cliente desde los números de empresa de ese cliente. Usar el BSUID de un cliente con el número del socio falla, porque cada BSUID pertenece a un solo portfolio comercial.
Fuentes
[1] WhatsApp Help Center, «About usernames,» https://faq.whatsapp.com/658755553162769/ (accessed October 29, 2026).
[2] Meta for Developers, «Business-scoped user IDs,» updated October 23, 2026, https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/ (accessed October 29, 2026).
[3] Meta for Developers, «Changelog,» https://developers.facebook.com/documentation/business-messaging/whatsapp/changelog/ (accessed October 29, 2026).
[4] 360Dialog documentation, «Usernames & BSUID,» https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-bsuid (accessed October 29, 2026).
[5] 360Dialog documentation, «Business Username,» https://docs.360dialog.com/docs/messaging-api/api-reference/business-username (accessed October 29, 2026).
