> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

> [!NOTE]
>
> Para ver el catálogo exhaustivo derivado del esquema, consulta [todos los ejemplos](https://docs.ycloud.com/es/api-reference/guides/examples/webhook-examples/webhook-payload-examples).

## 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

> [!NOTE]
>
> Para configurar el endpoint, la validación de firmas y el comportamiento de reintentos, consulta [Configurar webhooks](https://docs.ycloud.com/es/api-reference/guides/api-fundamentals/configure-webhooks.md).

## 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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.