Recepción de Notificaciones
La plataforma reenvía a tu webhook los eventos entrantes de WhatsApp: mensajes, estados de entrega, eventos de grupos y de Flows, y llamadas.
La plataforma permite recibir los siguientes tipos de notificaciones:
- Mensajes, archivos, ubicaciones y contactos enviados por su cliente, de acuerdo a los siguientes escenarios:
- a. En respuesta a un mensaje enviado por su plataforma.
- b. Si su cliente inicio la conversación.
- Estatus de los mensajes enviados. Se notificará alguno de los siguientes estatus:
- a. Enviado: El mensaje fue enviado exitosamente.
- b. Recibido: El mensaje fue recibido por su cliente.
- c. Leído: El mensaje fue leído por su cliente.
- d. Fallido: El mensaje no se pudo enviar a su cliente.
- e. Eliminado: El mensaje fue eliminado por su cliente.
- Estatus de Registro de Contactos (ver sección 2), en caso de que el servicio haya regresado el estatus processing.
- Eventos de grupos: creación y eliminación de grupos, cambios de participantes, solicitudes para unirse, configuración y suspensión del grupo (ver Grupos).
- Eventos de Flows: cambios de estatus de un Flow y alertas de su endpoint (ver Flows).
- Eventos de llamadas (ver Calling API) y, en general, cualquier otro evento de Meta se reenvía al webhook tal como lo envía Meta.
- Existe la posibilidad de que que lleguen notificaciones duplicadas.
Páginas de esta sección:
- Webhook: cómo se entregan las notificaciones y qué debe responder tu webhook.
- Notificaciones de mensajes: estructura general y mensajes de texto, audio, documento, imagen, ubicación, video, mensaje de voz, sticker y contacto compartido.
- Respuestas de mensajes interactivos: respuestas rápidas, carro de compras y respuestas de WhatsApp Flows.
- Notificaciones de estatus: estatus de los mensajes enviados.
- Cambio de número del usuario: notificación de sistema cuando cambia el número o el BSUID del usuario.
- Notificaciones de grupos: eventos de grupos y estatus de mensajes enviados a un grupo.
- Notificaciones de Flows: cambios de estatus y alertas de un Flow.
Nombres de usuario y BSUID
WhatsApp permite que los usuarios configuren un nombre de usuario (por ejemplo, @testusername) para mostrarse en la aplicación en lugar de su número de teléfono. Cuando un usuario lo activa, su número de teléfono puede dejar de llegar en las notificaciones.
Para que siempre puedas identificar al usuario, Meta asigna a cada usuario un Business-scoped user ID (BSUID):
- Lo genera Meta automáticamente y siempre llega en las notificaciones de mensajería, tenga o no el usuario nombre de usuario.
- Formato: código de país ISO 3166 alfa-2, un punto y hasta 128 caracteres alfanuméricos. Por ejemplo, US.13491208655302741918.
- Es válido solo para los números de teléfono de empresa del mismo portafolio comercial. Si usas el BSUID con un número de otro portafolio, el mensaje no se entrega.
- Si el usuario cambia su número de teléfono, su BSUID se regenera y recibes una notificación de sistema (ver Cambio de número del usuario).
- Si el negocio tiene portafolios vinculados, también llega un BSUID principal (parent_user_id), por ejemplo, US.ENT.506847293015824.
Cuándo llega el número de teléfono
Si el usuario no tiene nombre de usuario, siempre llegan su número de teléfono y su BSUID. Si tiene nombre de usuario, el número de teléfono solo llega si se cumple al menos una de estas condiciones:
- La empresa le envió un mensaje o lo llamó a su número de teléfono en los últimos 30 días.
- El usuario le envió un mensaje o llamó a la empresa en los últimos 30 días.
- El usuario está en la libreta de contactos de la empresa.
Estas condiciones se evalúan por cada número de teléfono de empresa.
Cómo identificar al usuario
- Mensajes entrantes: usa
from(número de teléfono) si llega; si no, usafrom_user_id(BSUID). - Estatus de mensajes enviados: usa
recipient_id(número de teléfono) si llega; si no, usarecipient_user_id(BSUID).
Guarda el BSUID desde el primer mensaje para seguir identificando al usuario aunque active un nombre de usuario o cambie su número.
Enviar mensajes con BSUID
El campo to de los mensajes acepta tanto el número de teléfono como el BSUID; el servicio detecta automáticamente cuál estás usando. Usa el número de teléfono si lo conoces y el BSUID cuando el usuario no comparte su número.
El BSUID no se puede usar con plantillas de autenticación de un solo toque, sin toque o de copiar código; estas requieren el número de teléfono.
