BSUID - ID de contactos, metadatos, endpoints y aplicabilidad en Blip

Índice

1. Qué es el BSUID
2. Dónde encontrar el BSUID en Blip
   1. Metadatos de los mensajes
      1. Propiedades disponibles en los metadatos
      2. Cómo extraer la información de los metadatos
   2. Endpoint de consulta PN > BSUID
      1. Visión general
      2. Datos devueltos en el endpoint
      3. Solicitud
      4. Respuesta
      5. Uso recomendado
      6. Limitaciones

Qué es el BSUID

El BSUID (Business-Scoped User ID) es un identificador creado por Meta para representar la relación entre un usuario y una empresa específica en WhatsApp. El mismo usuario con el mismo número telefónico posee BSUIDs distintos para diferentes empresas (siempre representadas por el Administrador Comercial/Portafolio Empresarial de Meta), a diferencia del número telefónico, que es global. Es decir, si el Portafolio Empresarial con el que un mismo usuario interactúa es diferente, el BSUID también será diferente. Ejemplo:

El BSUID pasa a ser el principal identificador técnico de la interacción especialmente en escenarios sin compartición de teléfono.

Dónde encontrar el BSUID en Blip

Metadatos de los mensajes

El BSUID está disponible en los metadatos de los mensajes (mensajes, notificaciones y ecos, en casos de activaciones de Coexistencia) y estará presente en el objeto metadata de cada sobre (mensaje, notificación o eco) siempre que esta información sea enviada a Blip por Meta en los webhooks correspondientes.

Para consultar la información del BSUID vía metadata:

1. Accede al bot deseado en el Portal

2. Accede al menú superior de Blip

3. Haz clic en el ícono de tres puntos (...)

4. Selecciona la opción Log en el menú

5. Localiza el objeto metadata dentro del sobre del mensaje

Propiedades disponibles en los metadatos

La disponibilidad de los campos depende de la información recibida por Meta. Los campos no informados por Meta en los webhooks no serán llenados.
 

Cómo extraer la información de los metadatos

Para extraer esta información, debes definir dos acciones de salida en el bloque Inicio del Studio:

1. Definir variable de metadata

Define una variable con los siguientes parámetros:

• Nombre de la variable: metadata

• Valor: {{input.message@metadata}}

2. Ejecutar script

Ejecuta un script para obtener solo el valor del #wa.bsuid presente en este metadata. Configuración del script:

function run(metadata){
metadata= JSON.parse(metadata);
return metadata["#wa.bsuid"];
}

Se mostrará el alcance del script, según la imagen a continuación:

• ¡TIP! Usa registro de eventos para mejorar la captura de datos y hacerlos más presentables a partir de reportes personalizados.

Endpoint de consulta PN > BSUID

Visión general

Blip ofrece un endpoint que permite consultar mapeos ya conocidos entre número de teléfono, BSUID e ID Blip.

¡Importante!

El endpoint no consulta a Meta en tiempo real. Solo devuelve datos previamente recibidos y procesados por Blip. Si Blip aún no ha recibido el BSUID de un PN determinado, el endpoint no lo devolverá. La ausencia de respuesta para un número consultado, por lo tanto, no significa error ni inexistencia del contacto. Solo significa que aún no existe una relación PN ↔ BSUID conocida y almacenada por Blip para ese usuario.

Datos devueltos en el endpoint

Siempre que se reciban informaciones de identificación por parte de Meta, Blip almacena y ofrece los siguientes datos a través del endpoint de consulta:

Solicitud

YOUR_TOKEN es la clave de autorización de tu bot.

PHONE_NUMBERS  debe ser la lista de números a buscar. Debe estar en su forma completa (con código de país, código de área y número), con los ítems separados por “;” (punto y coma).

• ATENCIÓN: los números deben estar obligatoriamente separados por “;” (punto y coma) si hay más de uno, con un máximo de 100 ítems. Puede haber el signo “+” (más) y el noveno dígito (para números de Brasil).

Ejemplo: +5531988889999;5531988889999;+553188889999;+553188889999. 
 

{PHONE_NUMBERS} = 5531988889999

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}
 
{
    "id":  "{{$guid}}",
    "method": "get",
    "to": "postmaster@wa.gw.msging.net",
    "uri": “/external-contacts-mapping?phoneNumbers={PHONE_NUMBERS}"
}

En caso de solicitudes por lote:

{PHONE_NUMBERS} = 5531988889999;+553166667777

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}
{
    "id":  "{{$guid}}",
    "method": "get",
    "to": "postmaster@wa.gw.msging.net",
    "uri": “/external-contacts-mapping?phoneNumbers={PHONE_NUMBERS}"
}

Observación: asegúrate de separar los números por “;”. 

Respuesta

Solo se devolverán los números que ya hayan sido identificados y mapeados por la plataforma Blip.

• ATENCIÓN: la respuesta del Id (ID interno Blip) y del waId (número telefónico del contacto) siempre traerá los valores sin el signo “+” y con el noveno dígito (en casos de números de Brasil). Ejemplo: +553188889999 -> 5531988889999.

{
  "type": "application/vnd.lime.collection+json",
  "resource": {
    "total": 1,
    "itemType": "application/vnd.iris.whatsapp.contact-mapping-info+json",
    "items": [
      {
        "id": "5531988889999",
        "bsuid": "BR.11815799212886844830",
        "waId": "5531988889999",
        "lastReadDate": "2026-05-13T00:00:00.000Z"
      }
    ]
  }
 }

Uso recomendado

• Mapeo de base antes del rollout global por Meta

• Desduplicación de contactos en CRMs integrados

• Enriquecimiento de registros y base con BSUID

• Migración gradual de bases de disparo

• Preservación de historial de atención y análisis

⚠️ El endpoint debe utilizarse principalmente durante el período de transición para el enriquecimiento gradual de las bases existentes. Después de la adopción completa del nuevo modelo de identidad, se recomienda que las nuevas implementaciones ya consideren IDs independientes del teléfono. 

Limitaciones

• Hasta 100 números por solicitud (control de TPS)

• El endpoint tiene control de throughput; solicitudes que amenacen la estabilidad de la plataforma pueden ser rechazadas y el fallo será devuelto como el siguiente ejemplo

• Se recomienda implementar retry con backoff en consultas de alto volumen

{
  "method": "get",
  "status": "failure",
  "reason": {
        "code": 38,
         "description": "Max throughput rate reached on endpoint"
       }
}