Ejemplos de Webhook de mensajes del historial de la aplicación WhatsApp Business

Para consultar el catálogo exhaustivo derivado del esquema, consulta todos los ejemplos.

Qué es

Gestiona eventos de sincronización del historial de la aplicación WhatsApp Business.

Antes de comenzar

Crea un endpoint HTTPS público en tu aplicación.
Configura un endpoint de Webhook de YCloud para los tipos de eventos que necesites.
Guarda el secreto de firma del endpoint de forma segura.
Haz que el procesamiento de eventos sea idempotente.

Cómo funciona

YCloud envía una solicitud HTTP POST cuando ocurre el evento. Verifica la firma, registra el evento de forma duradera, devuelve una respuesta 2xx y procesa el trabajo lento de forma asíncrona. Para los eventos creados a partir de un fragmento de historial de Meta, YCloud copia el phase y progress del fragmento al evento de nivel superior. Los fragmentos que contienen mensajes incluyen un objeto de mensaje específico de la dirección. Si tanto threads como errors están vacíos, YCloud envía un evento de solo progreso sin whatsappMessage ni whatsappInboundMessage. Las entregas son de al menos una vez y pueden llegar en desorden. Deduplica por el id del evento; no uses phase y progress como una clave de entrega única.

Solicitud

Los siguientes escenarios muestran las solicitudes enviadas a tu URL de Webhook. Trata el id del evento como el identificador de entrega y utiliza type para enrutar el payload.

Respuesta

Devuelve un estado 2xx tras aceptar el evento.

HTTP/1.1 200 OK

Para la configuración del endpoint, la validación de firmas y el comportamiento de reintentos, consulta Configurar webhooks.

Mensaje de texto entrante

En este caso, tu endpoint de Webhook recibió un mensaje de texto entrante:

Contiene texto sin formato enviado por el usuario.
Contiene la información del mensaje mencionado en context.
Para otros tipos de mensajes, puedes consultar whatsappInboundMessage

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeWick"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Los mensajes entrantes son aquellos enviados por los clientes a los números de teléfono de tu empresa.
El campo context (opcional) contiene la información del mensaje mencionado, que se utiliza normalmente para responder a un mensaje anterior enviado por el usuario o por tu empresa.
- context.from es el WhatsApp ID (número de teléfono sin el prefijo ’+’) del usuario que envió el mensaje mencionado.
- context.id es el ID original del mensaje mencionado en la plataforma de WhatsApp, que comienza con wamid..

Mensaje de texto saliente

En este caso, tu endpoint de Webhook recibió un mensaje de texto saliente enviado por un cliente empresarial a un usuario de WhatsApp mediante la aplicación WhatsApp Business o un dispositivo complementario compatible:

Contiene texto sin formato enviado previamente.
Contiene la información del mensaje mencionado en context.
Para otros tipos de mensajes, puedes consultar Ejemplos de Webhook de sincronización de mensajes enviados de la aplicación WhatsApp Business

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId" : "US.13491208655302741918",
    "toParentUserId": "US.11815799212886844830",
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "context": {
      "message_id": "wamid.BgNODYxN..."
    }
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo por id y traslada las tareas lentas o propensas a fallos a un procesador asíncrono.

Fragmento de historial de solo progreso

Cuando un fragmento de historial de Meta no contiene ni hilos ni errores, el evento aún informa sus metadatos de sincronización. El evento no contiene ningún payload de mensaje.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_progressOnly73",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:02.000Z",
  "phase": 1,
  "progress": 73
}'

Respuesta

HTTP/1.1 200 OK

Explicación

Este evento no tiene intencionadamente ningún objeto de mensaje de WhatsApp. Continúa realizando el seguimiento del progreso y confírmalo como cualquier otra entrega de Webhook.

Primeros pasos

Guías

Endpoints

Webhooks

Ejemplos de Webhook de mensajes del historial de la aplicación WhatsApp Business

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Mensaje de texto entrante

Solicitud

Respuesta

Explicación

Mensaje de texto saliente

Solicitud

Respuesta

Explicación

Fragmento de historial de solo progreso

Solicitud

Respuesta

Explicación

​Qué es

​Antes de comenzar

​Cómo funciona

​Solicitud

​Respuesta

​Mensaje de texto entrante

​Solicitud

​Respuesta

​Explicación

​Mensaje de texto saliente

​Solicitud

​Respuesta

​Explicación

​Fragmento de historial de solo progreso

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Mensaje de texto entrante

Solicitud

Respuesta

Explicación

Mensaje de texto saliente

Solicitud

Respuesta

Explicación

Fragmento de historial de solo progreso

Solicitud

Respuesta

Explicación