Ejemplos de Webhook para sincronización de mensajes enviados en WhatsApp Business App

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

Qué es

Gestiona eventos de sincronización de mensajes enviados en WhatsApp Business App.

Antes de comenzar

Crea un endpoint público HTTPS en tu aplicación.
Configura un endpoint de webhook de YCloud para los tipos de evento 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 las tareas lentas de forma asíncrona.

Solicitud

Los siguientes escenarios muestran solicitudes enviadas a la URL de tu webhook. Trata el evento id 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 configurar el endpoint, la validación de firmas y el comportamiento de reintentos, consulta Configurar webhooks.

Mensaje de texto saliente

En este caso, el endpoint de tu webhook recibió un mensaje de texto saliente enviado por un cliente comercial a un usuario de WhatsApp mediante la aplicación WhatsApp Business o un dispositivo complementario compatible: Lee el texto enviado desde whatsappMessage.text.body.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_example_smb_echoes",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "username": "example_customer"
    }
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, elimínalo de forma duplicada mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Mensaje de imagen saliente

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

Contiene la imagen enviada previamente.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Se puede acceder directamente a image.link en unos pocos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para descargar este archivo en un plazo de 30 días.

Mensaje de video saliente

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

Contiene el video enviado previamente.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "video/mp4"
    }
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Se puede acceder directamente a video.link en unos pocos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para descargar este archivo en un plazo de 30 días.

Mensaje de audio saliente

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

Contiene el audio enviado previamente.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "audio/ogg; codecs=opus"
    }
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Se puede acceder directamente a audio.link en unos pocos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para descargar este archivo en un plazo de 30 días.

Mensaje de documento saliente

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

Contiene el documento enviado previamente.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "caption": "图片",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Se puede acceder directamente a document.link en unos pocos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para descargar este archivo en un plazo de 30 días.

Mensaje de Business App creado

Usa whatsapp.smb.message.created cuando se envíe un mensaje de WhatsApp Business App.

Solicitud

{
  "id": "evt_example_smb_created",
  "type": "whatsapp.smb.message.created",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Lee el mensaje saliente desde whatsappMessage. Su type selecciona el objeto de contenido; este ejemplo de texto utiliza text.body. Enruta este evento por separado de whatsapp.smb.message.echoes compartiendo el análisis del mensaje cuando corresponda. Estos son eventos de coexistencia de Business App, no eventos de eco de Meta Business Agent.

Primeros pasos

Guías

Endpoints

Webhooks

Ejemplos de Webhook para sincronización de mensajes enviados en WhatsApp Business App

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Mensaje de texto saliente

Solicitud

Respuesta

Explicación

Mensaje de imagen saliente

Solicitud

Respuesta

Explicación

Mensaje de video saliente

Solicitud

Respuesta

Explicación

Mensaje de audio saliente

Solicitud

Respuesta

Explicación

Mensaje de documento saliente

Solicitud

Respuesta

Explicación

Mensaje de Business App creado

Solicitud

Respuesta

Explicación

​Qué es

​Antes de comenzar

​Cómo funciona

​Solicitud

​Respuesta

​Mensaje de texto saliente

​Solicitud

​Respuesta

​Explicación

​Mensaje de imagen saliente

​Solicitud

​Respuesta

​Explicación

​Mensaje de video saliente

​Solicitud

​Respuesta

​Explicación

​

​Mensaje de audio saliente

​Solicitud

​Respuesta

​Explicación

​Mensaje de documento saliente

​Solicitud

​Respuesta

​Explicación

​Mensaje de Business App creado

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Mensaje de texto saliente

Solicitud

Respuesta

Explicación

Mensaje de imagen saliente

Solicitud

Respuesta

Explicación

Mensaje de video saliente

Solicitud

Respuesta

Explicación

Mensaje de audio saliente

Solicitud

Respuesta

Explicación

Mensaje de documento saliente

Solicitud

Respuesta

Explicación

Mensaje de Business App creado

Solicitud

Respuesta

Explicación