Identificadores de usuario por empresa
Un identificador de usuario por empresa (BSUID) te permite escribir a un contacto de WhatsApp sin su número de teléfono. Identifica al contacto dentro de tu portfolio empresarial de Meta.
Nombres de usuario de WhatsApp
Los contactos de WhatsApp que tienen un nombre de usuario pueden escribirte sin compartir su número de teléfono. Sus mensajes incluyen from.bsuid; from.phone_number puede faltar. Los contactos sin nombre de usuario también pueden tener un BSUID.
Meta incluye el número de teléfono si el contacto está en tu libreta de contactos de Meta o ha intercambiado mensajes o llamadas con tu número de empresa en los últimos 30 días. La regla de 30 días se aplica por número de empresa.
from.username y from.display_name son opcionales. No puedes enviar mensajes a ninguno de esos valores.
Formato del BSUID
Un BSUID tiene un código de país ISO 3166 alpha-2 en mayúsculas, un punto y hasta 128 letras o dígitos. Por ejemplo: US.13491208655302741918.
Guarda y envía el valor completo sin modificarlo. Usa un número de remitente del mismo portfolio empresarial. Meta rechaza los mensajes enviados desde otros portfolios.
El BSUID cambia cuando el contacto cambia de número de teléfono, así que guárdalo bajo tu propio identificador de cliente.
Un BSUID principal funciona en los portfolios que una empresa gestionada haya inscrito. Añade ENT. después del código de país: US.ENT.11815799212886844830. El límite de 128 caracteres se aplica a la parte posterior a ENT.. Bird acepta ambos formatos.
Pedir un número de teléfono
Estos ejemplos de la API de mensajes muestran solo los campos necesarios para este intercambio.
1. El contacto te escribe
Este mensaje incluye el BSUID del contacto, pero no su número de teléfono.
Tienes 24 horas para responder sin una plantilla.
{
"direction": "inbound",
"from": {
"bsuid": "US.13491208655302741918"
},
"to": {
"phone_number": "+14155550100"
},
"text": {
"body": "Can I book a repair?"
}
}2. Pide su número
Envía una solicitud de datos de contacto al BSUID. WhatsApp muestra un botón para compartir un número de teléfono.
Fuera del plazo de 24 horas, envía una plantilla con un botón request_contact_info.
{
"direction": "outbound",
"from": {
"phone_number": "+14155550100"
},
"to": {
"bsuid": "US.13491208655302741918"
},
"interactive": {
"type": "request_contact_info",
"body_text": "Share your number."
}
}3. El contacto pulsa el botón
Recibes una tarjeta de contacto con origin: "contact_request" y el número compartido en phone_numbers.
En esta respuesta, from también incluye el número de teléfono del contacto.
{
"direction": "inbound",
"from": {
"bsuid": "US.13491208655302741918",
"phone_number": "+14155550101"
},
"contact_cards": [
{
"origin": "contact_request",
"phone_numbers": [
{
"phone_number": "+14155550101"
}
]
}
]
}Si el contacto cierra la solicitud, no recibes ningún mensaje ni webhook. Define un tiempo de espera para que tu aplicación pueda continuar sin el número.
Enviar un mensaje
Asigna el BSUID a to y tu número de empresa de WhatsApp a from:
{
"to": "US.13491208655302741918",
"from": "+14155550100",
"text": { "body": "Your repair is booked." }
}Si el mensaje entrante solo tiene un BSUID, responde a ese BSUID desde el mismo número de empresa. Un número de teléfono de tus propios registros puede no tener una ventana de atención abierta y provocar 422 E15044.
- Las plantillas de autenticación requieren un número de teléfono. Una plantilla gestionada por Bird devuelve
422E15014. Una plantilla creada por tu espacio de trabajo se acepta, pero después falla en Meta. - Una plantilla con un precio máximo se acepta para un BSUID, pero después falla con el error de Meta
131062. Envíala a un número de teléfono. - Un número de teléfono o BSUID no válido devuelve
422E15001. - El precio del mensaje depende del código de país del BSUID.
La ventana de atención al cliente también se aplica a los BSUID. Una respuesta 202 significa que la API ha aceptado tu solicitud. Comprueba el estado del mensaje para confirmar la entrega.
Buscar mensajes
En los mensajes y webhooks, from identifica al remitente y to al destinatario. Cada uno puede contener phone_number, bsuid o ambos.
Para listar mensajes, filtra por:
fromotopara un remitente o destinatario, usando su número de teléfono o BSUID.bsuidpara mensajes enviados al mismo usuario de WhatsApp o recibidos de él.
El filtro phone_number está obsoleto. Usa from o to en su lugar.
Guías relacionadas
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.