Usernames - Preguntas Frecuentes

1. Webhooks y Notificaciones
2. Conciliación de Contactos
3. Identificadores (IDs)
4. Datos del Contacto y Campos
5. Envío de Mensajes
6. Campañas y Envios
7. Flujos en Studio
8. Cronograma y Despliegue
9. Componentes de Plantilla
10. Estrategia de Preparación
11. Casos Especiales
12. Preguntas Generales
13. Recursos Adicionales

Webhooks y Notificaciones

¿Cuándo hay webhook para cambios de identidad?

Meta dispara webhooks solo en dos escenarios:

• BSUID cambia — webhook user_id_update

• El número de teléfono cambia — webhook user_preferences

⚠️ No hay webhook cuando un usuario activa el nombre de usuario o deja de compartir su número de teléfono. Este cambio ocurre silenciosamente en interacciones subsecuentes.

Cómo detectar: Monitorea el metadata de los mensajes. Cuando un mensaje llega sin PN (número de teléfono), pero con BSUID completado, significa que el usuario activó el nombre de usuario.

Conciliación de Contactos

¿Cómo Blip concilia contactos con el nuevo identificador?

Blip mantiene un mapeo continuo entre PN ↔ BSUID ↔ ID Blip, creado desde abril de 2026, y realiza la conciliación automáticamente:

Flujo:

Contacto interactúa (con PN + BSUID)
    ↓
Blip consulta mapeo existente
    ↓
Encontrado → Actualiza contacto existente (historial preservado)
No encontrado → Crea nuevo contacto

Ejemplo: Si un contacto que conoces desde 2025 (con PN 5531999999999) interactúa usando nombre de usuario, Meta envía PN + BSUID juntos. Blip reconoce y actualiza el contacto existente.

⚠️Limitación: Para contactos que nunca han conversado contigo, no hay mapeo automático. El mapeo ocurre solo cuando hay interacción real.

Identificadores (IDs)

¿Cuál es la diferencia entre Blip ID, BSUID, WaId y Username?

¿El ID Blip será depreciado?

No. El Blip ID es una de las nuevas identidades del contacto.

Fue creado justamente para brindar estabilidad e independencia al modelo Meta. Puedes usarlo con seguridad en todas las integraciones.

Datos del Contacto y Campos

¿Los campos extras (CPF, correo electrónico, nombre) seguirán llegando?

Sí, sin impactos. Solo el campo identity del contacto evolucionará. Todos los demás permanecen intactos:

• CPF, correo electrónico, nombre

• Teléfono (cuando esté disponible)

• Campos personalizados

• Extras

Incluso cuando el usuario oculta el PN (activando el nombre de usuario), Blip sigue enviando todos estos datos en los webhooks.

¿Cómo será el payload exacto del mensaje?

Con PN compartido:

{
  "contact": {
    "identity": "5531999999999@wa.gw.msging.net",
    "phoneNumber": "5531999999999",
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "metadata": {
    "#wa.bsuid": "BR.1234567890123456",
    "#wa.username": "@meuUsername"
  }
}

Sin PN compartido (username activo):

{
  "contact": {
    "identity": "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net",
    "phoneNumber": null,
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "metadata": {
    "#wa.bsuid": "BR.1234567890123456",
    "#wa.username": "@meuUsername"
  }
}

Cambios clave:

• contact.identity puede ser GUID o PN

• contact.phoneNumber puede ser nulo

• Nuevos campos en metadata: #wa.bsuid, #wa.username

• Todos los demás campos permanecen

Envío de Mensajes

¿Podré enviar mensajes por BSUID, ID Blip y PN?

Sí. Las APIs de envío ahora aceptan los tres:

Por PN (ya funciona):

POST /messages
{
  "to": "5531999999999@wa.gw.msging.net",
  "content": { "type": "text", "text": "¡Hola!" }
}

Por BSUID (nuevo):

POST /messages
{
  "to": "BR.1234567890123456@wa.gw.msging.net",
  "content": { "type": "text", "text": "¡Hola!" }
}

Por ID Blip (nuevo):

POST /messages
{
  "to": "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net",
  "content": { "type": "text", "text": "¡Hola!" }
}

¿El endpoint GET /accounts seguirá funcionando?

Sí, evolucionado. Seguirá aceptando consultas por PN y ahora también por BSUID:

GET /accounts?phoneNumbers=5531999999999
GET /accounts?bsuids=BR.1234567890123456

La respuesta sigue igual:

{
  "items": [
    {
      "id": "5531999999999",
      "bsuid": "BR.1234567890123456",
      "waId": "5531999999999"
    }
  ]
}

Sin cambios. Funciona para usuarios antiguos y nuevos.

Campañas y Envios

¿Podré enviar campañas a números de teléfono normalmente?

Sí, indefinidamente. Incluso contactos con nombre de usuario activo pueden seguir recibiendo mensajes por PN.

Importante: Cuando inicias la conversación por PN, Meta devuelve PN + BSUID en la respuesta. Blip mapea y actualiza el contacto.

Detalle importante: Cuando envías por PN a un contacto que oculta el teléfono:

• Puedes enviar (aunque el PN no se comparta visualmente)

• En la respuesta, Meta devuelve PN + BSUID (aunque el usuario no comparta)

• Blip actualiza el contacto automáticamente

Recomendación: Sigue usando PN para bases existentes. Usa BSUID cuando no tengas PN.

¿Y si solo tengo BSUID de un contacto que nunca conversó conmigo?

No es posible enviar a quien nunca ha conversado solo con BSUID. BSUID solo existe cuando hay interacción entre ese usuario y tu empresa. Si quieres contactar a alguien que nunca conversó:

1. Necesitas el PN

2. O envía el primer mensaje por PN

3. Así, Meta proporcionará el BSUID en la respuesta

¿Puedo enviar campañas usando números y BSUID mezclados?

Sí. Para campañas masivas (CSV), puedes mezclar:

recipient,nombre
+55319XXXXXXXX,Carlos
BR.1234567890,Ana
+55319XXXXXXXX,Pedro

⚠️ Atención: Si PN y BSUID del mismo usuario están presentes en la misma base, se realizarán 2 envíos para el mismo usuario. Garantizar la deduplicación es tu responsabilidad.

Flujos en Studio

¿Contact.identity puede contener GUID en lugar de PN?

Sí, a partir del 01/06/2026.

HOY:

contact.identity = "5531999999999@wa.gw.msging.net" (siempre PN)

A PARTIR DE 01/07:

contact.identity = puede ser:
  • "5531999999999@wa.gw.msging.net" (PN cuando esté disponible)
  • "e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net" (GUID si no hay PN)

⚠️ EL RIESGO: Si extraes el teléfono así:

const phone = contact.identity.split("@")[0];

Puede devolver un GUID en lugar de teléfono cuando el usuario no comparte el PN.

LA SOLUCIÓN: Usa nuevas variables:

contact.whatsAppWaId    // Devuelve PN cuando está disponible, null si no
contact.whatsAppBsuid   // Devuelve BSUID (siempre disponible)

Acción recomendada:

1. En Studio → Analizar Flujo

2. La herramienta marca bloques con riesgo

3. Revisa y ajusta usando nuevas variables

4. Prueba en homologación

¿Cuáles son las nuevas variables del Studio?

Nuevas variables :

• contact.whatsAppBsuid → BSUID (siempre completado)

• contact.whatsAppParentId → Parent BSUID (cross-BM)

• contact.whatsAppUserName → Nombre de usuario adoptado por el usuario

• contact.waId → Corresponde al número del usuario en WhatsApp (cuando está disponible)

Antiguas (continúan, pero pueden cambiar formato):

• contact.identity → Ahora puede ser PN o GUID

• contact.phoneNumber → Puede ser null cuando no hay PN

• tunnel.originator → Ahora puede ser PN o GUID

• tunnel.identity → Ahora puede ser PN o GUID

No se afectan:

• contact.name, contact.email, contact.extras (CPF, etc.)

Cronograma y Despliegue

¿Cuál es el cronograma oficial?

Meta:

• Junio y Julio 2026: Alpha en algunos países seleccionados (no afecta a México)

• Segundo semestre 2026: despliegue progresivo global por Meta (incluyendo México)

Importante: La adopción es por usuario, no por empresa.

• No hay "fecha de cambio universal"

• Es gradual conforme cada persona activa el username

• Empresa A puede tener 100k usuarios SIN PN el primer día; Empresa B puede tener 10

¿Hay fecha límite para adecuarse?

No hay obligatoriedad con fecha fija, pero se recomienda acción inmediata.

• La adopción de los nombres de usuario está prevista a partir de mediados de septiembre

• El número de usuarios sin PN compartido crecerá orgánicamente

• No hay fecha de "desactivación del PN"

Recomendación:

• Adáptate lo antes posible

• Valida con el ambiente de pruebas

• Monitorea impactos en el segundo semestre

Componentes de Plantilla

¿Meta proporcionará una plantilla para solicitar PN al usuario?

Sí, a través de un componente específico de solicitud de contacto.

Estructura ya conocida:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

Workflow:

1. La marca crea plantilla con botón REQUEST_CONTACT_INFO

2. Blip envía plantilla → usuario ve "Compartir Contacto"

3. Usuario hace clic → comparte PN

4. Webhook se dispara con #wa.contactOrigin: "contact_request"

¿Cuándo estará disponible? Ya está disponible vía API.

Limitaciones de personalización:

• Tipo de botón: siempre "REQUEST_CONTACT_INFO"

• Texto del botón: siempre "Share Contact Info" (Meta traduce automáticamente)

• Se puede personalizar: texto del cuerpo, idioma, categoría

Estrategia de Preparación

Tengo 1 millón de contactos antiguos. ¿Cómo hago el mapeo?

Escenario 1 - Envío activo de mensajes:

Envías: Envío activo por PN
Meta envía reporte de notificación: Meta envía PN + BSUID
Blip: Mapea automáticamente
Historial preservado

Escenario 2 - Mapeo orgánico:

Usuario inicia contacto
Meta envía BSUID (y PN o nombre de usuario, cuando están disponibles)

Escenario 3 - Quieres forzar el mapeo:

Usa: Endpoint GET /external-contacts-mapping
Devuelve: de-para PN ↔ BSUID para contactos que Meta ya envió

⚠️ Limitación: No hay endpoint para consultar BSUID de un PN que nunca tuvo interacción. La conciliación ocurre solo con contactos que ya interactuaron con la empresa.

Mi CRM usa PN como clave primaria. ¿Qué hago?

No necesitas cambiar ahora, pero prepárate.

Corto plazo (hasta dic/2026):

• Mantén PN como referencia principal

• Agrega campos: BSUID, ID Blip

• Mapea PN → BSUID conforme ocurran interacciones

Mediano plazo (a partir de 2027):

• Migra a ID Blip como clave principal

• Usa PN como campo secundario "cuando esté disponible"

• BSUID como campo de referencia Meta

Ejemplo de migración:

-- ANTES
PRIMARY KEY: phone_number
-- DESPUÉS
PRIMARY KEY: blip_id (guid)
UNIQUE KEY: bsuid
INDEX: phone_number (nullable)

Puedes hacerlo de forma gradual.

Casos Especiales

¿Qué es Parent BSUID?

Un identificador para consolidar identidad entre múltiples Business Managers de la misma organización.

Ejemplo:

Tu Empresa (RFC: 123456789)
├─ Business Manager 1 (Ventas)
│  └─ BSUID: BR.111111111111111
├─ Business Manager 2 (Soporte)
│  └─ BSUID: BR.222222222222222
└─ Parent BSUID: BR.ENT.999999999999999 ← Identifica que es la misma empresa

Cuando un usuario interactúa con cualquier Business Manager de tu empresa, el Parent BSUID identifica que es la misma persona en contextos diferentes.

Restricciones:

• Requiere aprobación de Meta

• No todos los Business Managers son elegibles

• Cuando está disponible, viene en el metadata de los mensajes

¿Un BSUID se repite en diferentes empresas?

No, es único por empresa.

Usuario Juan
├─ Empresa A: BSUID = BR.111111111111111
├─ Empresa B: BSUID = BR.222222222222222
└─ Empresa C: BSUID = BR.333333333333333

La misma persona, BSUIDs completamente diferentes. Esto es por diseño (privacidad + seguridad).

¿Cuál es el formato de un GUID?

Un GUID es un número de 128 bits (16 bytes) representado por 32 caracteres hexadecimales.

Formato estándar con guiones:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 Ejemplo real:
e4b11bdd-a9bf-46ad-a9b0-34116dece5fe

Preguntas Generales

¿El teléfono desaparecerá de WhatsApp?

No. Toda cuenta de WhatsApp sigue vinculada a un teléfono.

Lo que cambia es que el número puede dejar de compartirse automáticamente en algunas interacciones con usuarios que activen el nombre de usuario.

¿Qué campos de plantilla están bloqueados para PN?

⚠️ Las plantillas de autenticación (one-tap, zero-tap, copiar código) requieren obligatoriamente el número de teléfono.

Para mensajes de texto, multimedia, botones y plantillas de marketing, el BSUID funciona normalmente.

¿Cómo saber si un contacto compartió su teléfono vía CTA?

Revisa el metadata de los mensajes:

{
  "metadata": {
    "#wa.contactOrigin": "contact_request",
    "#wa.sharedWaId": true
  }
}

Si ambos están presentes y con esos valores, el contacto compartió su propio teléfono a través del botón REQUEST_CONTACT_INFO.

Recursos Adicionales

• Documentación oficial Meta

• Artículos técnicos completos en Blip Help

• Blip Academy — Ruta de Usernames

• Comunidad Blip

¿Necesitas más ayuda? Explora nuestros contenidos en Blip Academy o Blip Community, mira tutoriales en nuestro canal de YouTube o resuelve tus dudas en nuestro canal de atención 😃