Identificadores de usuario con alcance de negocio

Por qué un contacto llega sin número de teléfono

Cómo se ve un BSUID

{
  "from": {
    "bsuid": "US.13491208655302741918",
    "username": "alexr",
    "display_name": "Alex Rivera"
  }
}

• Pasa el valor completo, sin modificar. Meta rechaza un BSUID modificado, así que ninguna parte es opcional: el código de país, el punto y cada carácter del identificador viajan juntos. Bird valida la forma antes de aceptar un envío, y el código de país debe estar en mayúsculas y ser un código ISO 3166 alfa-2 real; un prefijo en minúsculas o desconocido se rechaza en lugar de corregirse. El límite de 128 caracteres aplica al identificador después del código de país, y después del segmento ENT. en un BSUID padre.
• Tiene alcance a un portafolio de negocio. Cualquier número de teléfono de negocio en el mismo portafolio puede enviar mensajes a ese BSUID; un número en un portafolio diferente no puede, y el envío falla.
• No es permanente. Meta documenta que el BSUID de un contacto se regenera cuando cambia su número de teléfono, así que identifica a un interlocutor en vez de servir como clave de cliente duradera propia.

Cómo transcurre una conversación típica

1. El contacto te escribe. El mensaje entrante trae from.bsuid, y from.phone_number puede estar ausente. Ese mensaje abre la ventana de servicio al cliente, así que puedes responder libremente durante las siguientes 24 horas.
2. Pides el número. Envía una solicitud de información de contacto, un botón único que permite al contacto compartir un número de teléfono. La misma solicitud viaja en una plantilla a través de su botón request_contact_info, que alcanza a un contacto cuya ventana ya se cerró.
3. El contacto toca el botón. El número revelado llega como una tarjeta de contacto entrante con origin establecido en contact_request y el número en phone_numbers. Una tarjeta de contacto revelada puede describir a otra persona u otro número. Almacena esa revelación por separado de la identidad WhatsApp del remitente; usa las identidades que realmente llegan en los mensajes posteriores en lugar de sobrescribir el registro del cliente solo con la tarjeta.

Envío a un BSUID

{
  "to": "US.13491208655302741918",
  "from": "+13124495648",
  "text": { "body": "Your order shipped." }
}

• from debe estar en el portafolio al que está vinculado el BSUID. Es el mismo requisito de portafolio que aplica Meta, y una discrepancia falla en WhatsApp en lugar de en la aceptación.
• Las plantillas de código de verificación de un solo uso necesitan un número de teléfono. Una plantilla gestionada por Bird en la categoría authentication, o una que lleve un botón de código de verificación de un solo uso, se rechaza en la aceptación con un 422 E15014 WhatsAppRecipientNotSupportedForTemplate. Una plantilla creada por tu espacio de trabajo no se verifica en la aceptación: Meta requiere un número de teléfono para las plantillas de autenticación de un toque, cero toques y copia de código, así que ese envío se acepta y luego falla.
• Un valor que no es ni un número de teléfono ni un BSUID bien formado se rechaza en la aceptación, con un 422 E15001 WhatsAppInvalidRecipient.
• El precio se determina por el prefijo de país del BSUID. Un número de teléfono proporciona el país contra el que se tarifica un mensaje, y en un envío por BSUID el prefijo de dos letras lo proporciona en su lugar.

Lectura y filtrado por BSUID

• En un mensaje, from y to llevan cada uno un phone_number, un bsuid, o ambos. Un mensaje entrante nombra al contacto en from; uno saliente lo nombra en to.
• En un webhook, las mismas direcciones van en el payload del evento. Consulta eventos de WhatsApp para ver la estructura.
• En la lista de mensajes, to y from aceptan cada uno un BSUID además de un número de teléfono, y cada uno coincide con un extremo del mensaje. El filtro bsuid coincide con el contacto en cualquier dirección. El filtro anterior phone_number está deprecado: to y from lo reemplazan y coinciden con ambos tipos de identidad.

Próximos pasos

• Recepción de tarjetas de contacto: el canal por el que llega el número compartido
• Solicitudes de información de contacto de WhatsApp: el botón que la pide
• Envío de mensajes de WhatsApp: la estructura de la solicitud, el modelo 202 y reintentos seguros
• Referencia de identificadores de usuario con alcance de negocio de Meta: el despliegue, los BSUID padre y el resto de las superficies de Meta