Resumen: WhatsApp reemplaza los números de teléfono con BSUIDs (Business-Scoped User IDs) en junio de 2026. Almacena ambos campos en tu base de datos, implementa el patrón de respaldo de 3 capas para la resolución de identificadores, y espera que el campo from en los webhooks se vuelva nulo. Formato BSUID: país.alfanumérico — ej.: US.13491208655302741918.
Junio de 2026 romperá los chatbots basados en números de teléfono. WhatsApp está lanzando nombres de usuario y un nuevo sistema de identificación llamado BSUID (Business-Scoped User ID). Los números de teléfono desaparecen; los BSUIDs permanecen. Si tu integración almacena solo números de teléfono, envía mensajes a direcciones E.164, o asume que el campo from siempre contiene un número de teléfono, estás construyendo sobre una base que se desmoronará en semanas.
Esta guía es para desarrolladores backend que ejecutan automatización de WhatsApp en producción: creadores de chatbots, fundadores de SaaS con sistemas de notificación, e ingenieros de integración que mantienen stacks de mensajería empresarial. Necesitas entender qué es BSUID, por qué rompe los sistemas existentes, y exactamente cómo migrar antes de junio de 2026.
Qué es BSUID y por qué junio de 2026 lo cambia todo
Formato BSUID: código de país más entropía que debes almacenar. Un Business-Scoped User ID combina un código de país con una cadena alfanumérica: {país}.{alfanumérico}. Ejemplo: US.13491208655302741918. Este identificador reemplaza al número de teléfono como la dirección principal para las interacciones con WhatsApp Business API.
El cambio no es cosmético. WhatsApp está introduciendo nombres de usuario que los usuarios pueden configurar para ocultar sus números de teléfono de los contactos comerciales. Cuando un usuario oculta su número de teléfono, el BSUID se convierte en el único identificador disponible. Esto es conceptualmente lo mismo que LID (Line Identity), hacia lo que WhatsApp ha estado migrando desde 2024. La diferencia: LID fue una transición interna; BSUID es la realidad orientada al público que tu código debe manejar.
La fuente autoritativa confirma la línea de tiempo: Los nombres de usuario de WhatsApp y BSUID se lanzan en junio de 2026. Como se indica en el FAQ de Whapi.Cloud sobre nombres de usuario de WhatsApp, BSUID es conceptualmente lo mismo que LID — es el nuevo identificador principal para el trabajo con la API. Los sistemas que no se adapten experimentarán fallas silenciosas indistinguibles de los envíos exitosos.
Hemos visto este patrón de migración antes. Cuando WhatsApp cambió la infraestructura interna de direccionamiento basado en teléfono a enrutamiento basado en LID, las bibliotecas de código abierto enfrentaron cambios disruptivos. Los mismos patrones se repiten con BSUID — excepto que esta vez, el impacto es orientado al exterior. Tu mensaje puede reportarse como enviado mientras nunca llega al usuario.
El escenario de falla: cuando los números de teléfono se convierten en fantasmas
Chats fantasmas: mensajes enviados a números que nadie recibe. Esta es la falla concreta que tus usuarios experimentarán si no migras. Cuando WhatsApp habilite completamente la privacidad de nombres de usuario, los usuarios que hayan ocultado sus números de teléfono ya no recibirán mensajes enviados a su dirección E.164. Tu llamada a la API devuelve éxito — HTTP 200, ID de mensaje asignado — pero el mensaje entra en un vacío de entrega.
Así es como se ve el escenario de chat fantasma en la práctica. Tu sistema almacena el número de teléfono de un cliente: +12025551234. Envías un mensaje usando ese número como destino. La API acepta la solicitud. Pero el usuario ha habilitado la privacidad de nombre de usuario, así que su cliente de WhatsApp ya no enruta mensajes dirigidos por número de teléfono. El mensaje se descarta silenciosamente. Los payloads de webhook que recibas también pueden cambiar cuando los usuarios ocultan sus números.
// ESCENARIO DE CHAT FANTASMA — Este código se romperá en junio de 2026
// Enviar a número de teléfono cuando el usuario lo ha ocultado = falla silenciosa
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WHAPI_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '+12025551234', // Número de teléfono — PUEDE NO ENTREGARSE
body: '¡Tu pedido ha sido enviado!'
})
});
// HTTP 200 devuelto, el mensaje aparece como enviado
// Pero el usuario nunca lo recibe — se crea un chat fantasma
console.log('Mensaje enviado:', response.data);
El fenómeno de chat fantasma ya es observable en la fase de migración LID. Los desarrolladores reportan números de teléfono válidos que devuelven null de las APIs de búsqueda, y mensajes enviados a esos números crean conversaciones no entregadas. Cuando la transición a BSUID se complete en junio de 2026, esto se convertirá en el comportamiento predeterminado para usuarios con privacidad habilitada — no un caso extremo.
Consideraciones típicas: Los chats fantasmas son peores que los errores visibles. Una entrega fallida con código de error activa la lógica de reintento y alertas. Un chat fantasma parece éxito en tus logs mientras el cliente no recibe nada. Tus métricas muestran 98% de entrega mientras el alcance real podría ser 60% o menos para usuarios con privacidad habilitada.
Cómo se rompe la API: desde webhooks hasta claves de base de datos
Campo from nulo: tus supuestos de base de datos mueren. El cambio más disruptivo está en los payloads de webhook. Cuando un usuario oculta su número de teléfono, el campo from en los webhooks de mensajes entrantes puede estar vacío o ser nulo. Los sistemas construidos alrededor de la suposición de que cada mensaje tiene un número de teléfono válido como remitente fallarán en la etapa de análisis.
Según Azure Communication Services (2024): "El campo from ahora puede estar vacío o ser nulo cuando un usuario oculta su número de teléfono." Esto no es un riesgo teórico. Es un cambio de comportamiento documentado que afecta cómo analizas webhooks, almacenas el historial de conversación, y vinculas mensajes entrantes a registros de clientes.
El impacto en la base de datos es igualmente severo. E.164 era para siempre hasta que WhatsApp cambió para siempre. Los sistemas existentes a menudo usan números de teléfono como claves foráneas vinculando tablas de conversación a tablas de clientes. Cuando los BSUIDs reemplazan a los números de teléfono como identificadores principales, esas relaciones de clave foránea se rompen. Una búsqueda en base de datos usando WHERE phone = '+12025551234' no devuelve resultados cuando el identificador ahora es US.13491208655302741918.
La incompatibilidad del modelo de datos es el costo oculto de esta migración. Los sistemas que asumen que los campos to y from siempre contienen números de teléfono E.164 experimentarán ruptura de claves foráneas, registros de clientes duplicados creados bajo BSUIDs, y pérdida de threading de conversación. La migración requiere cambios de esquema, no solo actualizaciones de código.
Comparación de Número de Teléfono vs LID vs BSUID:
| Atributo | Número de Teléfono (E.164) | LID (Line Identity) | BSUID (Business-Scoped User ID) |
| Formato | +{país}{número} ej.: +12025551234 |
{alfanumérico} ej.: [email protected] |
{país}.{alfanumérico} ej.: US.13491208655302741918 |
| Visibilidad | Público (si el usuario permite) | Interno | Orientado a API |
| Disponibilidad | Disminuyendo — usuarios pueden ocultar | Transicionando a BSUID | Principal desde junio de 2026 |
| Confiabilidad de búsqueda | Todavía funciona (por ahora) | Devuelve null para usuarios válidos | Directa — sin búsqueda necesaria |
| Requisito de almacenamiento | Conservar para compatibilidad hacia atrás | Obsoleto | Clave primaria obligatoria |
El patrón de respaldo de tres capas
La búsqueda LID falla; los respaldos salvan la producción. Las APIs de búsqueda que resuelven números de teléfono a LIDs ya están devolviendo null para usuarios de WhatsApp válidos. El evento webhook lid-mapping.update se dispara inconsistentemente, impidiendo un mapeo LID-a-teléfono confiable. Un sistema de producción no puede depender solo de la búsqueda. Necesita una estrategia de respaldo cuando la resolución falla.
El patrón de respaldo de 3 capas surgió de la migración LID y aplica directamente a la adaptación BSUID. Hemos observado este patrón en sistemas de producción manejando millones de mensajes. Las capas operan en secuencia: BSUID primero, búsqueda LID segundo, reintento por teléfono tercero. Cada capa maneja el modo de falla de la anterior.
Capa 1 — Envío directo por BSUID: Si tienes el BSUID de una interacción anterior o webhook, envía directamente usándolo. Este es el camino más confiable — sin búsqueda requerida, sin ambigüedad de resolución. El formato BSUID es predecible: país.alfanumérico.
Capa 2 — Búsqueda LID con caché: Si tienes un número de teléfono pero no BSUID, intenta búsqueda LID vía el endpoint /contacts/lids. Almacena los mapeos exitosos en Redis o tu base de datos con TTL. La búsqueda puede devolver null — eso es esperado. Pasa a la capa 3 cuando lo haga.
Capa 3 — Reintento por teléfono con detección de fantasmas: Envía al número de teléfono como respaldo. Monitorea los acuses de recibo. Si un mensaje a un usuario conocido como activo no muestra confirmación de entrega dentro de 24 horas mientras otros mensajes se entregan, marca para revisión manual. Este es tu detector de chats fantasmas.
// PATRÓN DE RESPALDO DE TRES CAPAS para migración BSUID
// Intenta BSUID → Búsqueda LID → Teléfono con detección de fantasmas
async function sendWithFallback(phoneNumber, messageBody) {
// Capa 1: Intenta BSUID en caché primero
const cachedBSUID = await db.get(`bsuid:${phoneNumber}`);
if (cachedBSUID) {
return await sendMessage(cachedBSUID, messageBody, 'bsuid');
}
// Capa 2: Intenta búsqueda LID con almacenamiento en caché
try {
const lidResponse = await fetch(
`https://gate.whapi.cloud/contacts/lids/${phoneNumber}`,
{ headers: { Authorization: `Bearer ${token}` } }
);
const lidData = await lidResponse.json();
if (lidData.lid) {
// Convierte LID a formato BSUID y almacena en caché
const bsuid = `${lidData.country}.${lidData.identifier}`;
await db.setex(`bsuid:${phoneNumber}`, 86400, bsuid);
return await sendMessage(bsuid, messageBody, 'bsuid');
}
} catch (e) {
// Búsqueda fallida — registra y continúa al respaldo
logger.warn(`Búsqueda LID falló para ${phoneNumber}`);
}
// Capa 3: Respaldo por teléfono con bandera de detección de fantasmas
// Sin este respaldo, los usuarios válidos no reciben nada
const result = await sendMessage(phoneNumber, messageBody, 'phone');
await db.sadd('ghost-watch', phoneNumber); // Monitorea la entrega
return result;
}
Los proyectos que omiten el patrón de 3 capas tienden a ver caídas súbitas en la entrega cuando WhatsApp lanza la privacidad de nombres de usuario en nuevas regiones. El patrón de respaldo no es codificación defensiva — es la arquitectura mínima viable para junio de 2026.
Qué debe almacenar tu esquema de base de datos ahora
La ruptura de claves foráneas de base de datos es el dolor de migración que los desarrolladores reportan más a menudo. Los sistemas que asumen números de teléfono E.164 como identificadores inmutables fallarán. Necesitas un esquema que trate los números de teléfono como uno de múltiples identificadores posibles, no la clave primaria.
Cambios de esquema requeridos:
-
Campo de identificador primario: Agrega
bsuid VARCHAR(50)como la clave de búsqueda principal para operaciones de WhatsApp. Formato:XX.XXXXXXXXXXXXXXXXXXX(código de país + punto + 17-20 dígitos numéricos). -
Campo de teléfono secundario: Conserva
phone VARCHAR(20)para compatibilidad hacia atrás y visualización legible, pero elimina las restricciones de clave foránea que apuntan a él. -
Caché de resolución de identificadores: Agrega una tabla de búsqueda
identifier_mappings (phone, bsuid, lid, last_updated, source)para almacenar en caché los resultados de resolución y rastrear procedencia. -
Analizador de webhook null-seguro: Actualiza los manejadores de webhook para aceptar campos
fromanulables. Cuando sea null, extrae la identidad del remitente de los campos BSUID si están presentes. -
Marca de tiempo de migración: Agrega
bsuid_migrated_atpara rastrear qué registros han sido actualizados con BSUIDs.
El patrón que encontramos más a menudo en migraciones: los equipos intentan conservar los números de teléfono como claves primarias y almacenar BSUID como un campo secundario opcional. Esto falla cuando un usuario oculta su número de teléfono — creas un registro de cliente duplicado bajo el BSUID, fragmentando el historial de conversación y los datos de pedidos. BSUID debe ser el identificador canónico; el teléfono es metadata de visualización.
Impacto en la industria: ejemplos de e-commerce y salud
70% de automatización significa cero por ciento si los identificadores se rompen. La migración BSUID no es solo una refactorización técnica — amenaza el valor operativo. Las empresas de comercio electrónico que automatizan el 70% de las consultas de soporte vía WhatsApp verán esa automatización caer a cero si su resolución de identificadores falla. Las clínicas de salud que logran reducción de 40-65% en inasistencias mediante recordatorios de citas perderán esa eficiencia si los mensajes se convierten en chats fantasmas.
Caso de uso de comercio electrónico: El seguimiento de pedidos, la recuperación de carritos abandonados y la automatización de soporte al cliente dependen de la entrega confiable de mensajes. Una configuración típica envía miles de mensajes diariamente. Si el 30% va a usuarios que han habilitado la privacidad de nombre de usuario, y el sistema no ha migrado al manejo BSUID, eso representa cientos de mensajes no entregados por día. Los clientes no reciben notificaciones de envío. El volumen de tickets de soporte aumenta.
Caso de uso de salud: Los bots de recordatorio de citas logran reducción de 40-65% en inasistencias cuando los mensajes llegan confiablemente a los pacientes. La automatización depende de mensajes salientes programados a números de teléfono confirmados. Si el sistema de recordatorios no ha almacenado BSUIDs y la búsqueda LID devuelve null, el recordatorio se convierte en un chat fantasma. El paciente pierde la cita. La clínica pierde ingresos.
Ambos sectores dependen del enrutamiento predecible de mensajes. La migración BSUID introduce impredecibilidad exactamente donde estos flujos de trabajo requieren confiabilidad. La migración no es mantenimiento opcional — es preservación del valor operativo.
Lista de verificación de migración para junio de 2026
Migra ahora o migra en emergencia más tarde. La lista de verificación abajo cubre los pasos esenciales para preparar tu integración de WhatsApp para la transición BSUID. Completa estos antes de junio de 2026 para evitar chats fantasmas y fallas de entrega.
Pre-migración (Completar para mayo de 2026):
-
Auditar el esquema actual de base de datos — identificar todas las tablas usando números de teléfono como claves foráneas
-
Implementar columna BSUID junto a números de teléfono en tablas de clientes y conversaciones
-
Desplegar patrón de respaldo de 3 capas en la lógica de envío de mensajes
-
Actualizar analizadores de webhook para manejar campos
fromnulos con gracia -
Probar el comportamiento del endpoint de búsqueda LID — documentar el manejo de respuestas null
Migración (Completar para el 1 de junio de 2026):
-
Poblar BSUIDs por lotes para contactos existentes vía API de búsqueda LID
-
Cambiar la lógica de envío principal para usar BSUID como identificador de primera prioridad
-
Habilitar monitoreo de chats fantasmas — rastrear mensajes sin confirmación de entrega dentro de 24 horas
-
Actualizar documentación de soporte al cliente para referirse a BSUID en lugar de número de teléfono
Monitoreo post-migración: Vigila registros de clientes duplicados — una señal de que las búsquedas basadas en teléfono están perdiendo registros migrados de BSUID. Monitorea tasas de entrega por tipo de identificador. Espera 95%+ de entrega vía BSUID, 80-90% vía respaldo por teléfono, con la brecha representando el riesgo de chat fantasma.
Por qué Whapi.Cloud maneja BSUID sin romperse
Baileys falló; Whapi.Cloud se preparó. El ecosistema de bibliotecas de código abierto ha luchado con las migraciones de identidad de WhatsApp. Los desarrolladores reportan errores Bad MAC, fallas No Session, y excepciones Invalid PreKey cuando ocurren transiciones LID. Estos no son bugs de capa de aplicación — son fracturas de capa de protocolo que requieren correcciones a nivel de infraestructura.
Whapi.Cloud absorbe los cambios de protocolo aguas arriba para que tu superficie de API permanezca estable. La arquitectura de socket de sesión web — el mismo mecanismo que usa WhatsApp Web — proporciona una base más estable que los enfoques de emulación de navegador. Cuando WhatsApp cambia los formatos de identificador, el equipo de infraestructura de Whapi.Cloud maneja la adaptación de protocolo. Tus llamadas HTTP a la API permanecen sin cambios.
Las integraciones de código abierto se rompen a las 3am sin parte responsable. Whapi.Cloud tiene un equipo de soporte en vivo que ayuda activamente a los clientes a resolver problemas de producción — incluyendo guía de migración para preparación BSUID. Hemos guiado a cientos de integraciones a través de cambios de protocolo. El reconocimiento de patrones de esa historia operacional alimenta mejoras de infraestructura que previenen rupturas. Para equipos decidiendo entre bibliotecas autoalojadas y gateways administrados, la migración BSUID es un punto de decisión. Los stacks autoalojados requieren que monitorees issues de GitHub, apliques parches, pruebes cambios de protocolo, y manejes el tiempo de migración tú mismo. La infraestructura administrada cambia esa carga operativa al proveedor. Dado que WhatsApp hace cambios de protocolo sin aviso, el camino administrado ofrece predecibilidad que el autoalojado no puede igualar a escala pequeña a mediana.
Si encuentras comportamiento inesperado durante tu migración BSUID, contacta al equipo de soporte de Whapi.Cloud vía el widget de chat en whapi.cloud — el equipo ayuda activamente a los clientes a resolver problemas de producción.
No cubriremos la ruta de migración de la API oficial de WhatsApp Business aquí — eso requiere verificación de negocio Meta, flujos de trabajo de aprobación de plantillas, y niveles de precios por mensaje que son incompatibles con la arquitectura de API no oficial. Para equipos comprometidos con la API oficial, consulta la documentación BSP de Meta directamente.
