# Webhooks de WhatsApp

Reenviar los mensajes y estados de WhatsApp a una URL propia, al instante, con espera o por intervalos.

Fuente: https://ardumaker.com/docs/webhooks-whatsapp/

- Categoría: Comunicación
- Estado: Disponible
- Requisitos: Una cuenta de [WhatsApp](https://ardumaker.com/docs/whatsapp-business-api) en la empresa; Una URL que acepte POST con JSON
- Herramientas MCP (Solo leen): `listar_numeros_whatsapp`
- Herramientas MCP (Escriben o modifican): `crear_webhook_whatsapp`, `editar_webhook_whatsapp`, `simular_mensaje_sandbox_whatsapp`
- Herramientas MCP (Destructivas): `eliminar_webhook_whatsapp`

## ¿Qué permite hacer?

Configurar una o varias URLs que reciben los mensajes entrantes y los cambios de estado de todos los números de la cuenta. Es la pieza que conecta WhatsApp con un bot propio.

## ¿Cuándo conviene usarlo?

- Un bot tiene que contestar mensajes.
- Otro sistema necesita registrar las conversaciones.
- Se quiere agrupar varios mensajes seguidos de un contacto antes de procesarlos.

## ¿Cómo funciona en ArduMaker?

| Modo | Cuándo envía |
| --- | --- |
| `instant` | En cuanto el mensaje está listo. Un audio sale cuando termina de transcribirse. |
| `debounce` | Después de `debounce_seconds` sin mensajes nuevos en ese chat (0 a 3600, 10 por defecto). |
| `interval` | Cada `interval_seconds`, con todos los chats pendientes (0 a 86400, 60 por defecto). |

El cuerpo es un JSON con la cuenta, el modo y una lista de conversaciones (`headers`) con sus mensajes. Los archivos llegan como URL pública firmada; la ruta interna del archivo nunca se envía. `send_incoming` y `send_status` eligen qué se manda.

Con `notify_audio_received` el webhook recibe enseguida un aviso con `"event": "audio_received"` y la cabecera `X-Event: audio_received`, antes de la transcripción. El mensaje definitivo sale después, sin `event`.

## ¿Qué cambia realmente?

- Se guarda la configuración del webhook en la cuenta de WhatsApp de la empresa.
- Cada entrega queda registrada por mensaje, con el código HTTP, la duración y la espera de la plataforma.
- Un mensaje de prueba agrega `"sandbox": true` y la cabecera `X-Sandbox: 1`; un reenvío manual agrega `"resend": true`.

## Esquema

**Mensaje entrante hacia el webhook**

```text
WhatsApp
  ↓
Twilio (avisa a ArduMaker)
  ↓
ArduMaker (guarda y transcribe si es audio)
  ↓
Entrega según el modo (instant, debounce o interval)
  ↓
Tu URL (POST con JSON)
```

En `instant` la entrega sale en el acto; un barrido periódico es la red de seguridad y nunca manda dos veces el mismo mensaje.

## Resultado esperado

El servidor propio recibe cada mensaje una vez. En el chat se ve cuánto tardó cada entrega y qué código devolvió el webhook.

## Errores y resolución

- **El webhook estaba caído**: la entrega automática no repite. Desde el chat, un mensaje puntual se puede reenviar a los webhooks; el reenvío no altera lo pendiente.
- **El audio se cuenta dos veces**: el aviso `audio_received` y el mensaje final son dos POST; hay que distinguirlos por `event`.
- **400 `invalid_data`**: algún campo es inválido; la respuesta nombra cuáles.
- **Por qué rechaza algo mi webhook**: el sandbox devuelve el código y el cuerpo con que contestó cada webhook.

## Relación con MCP

Requiere acceso a la empresa. Ver [/mcp/docs](https://ardumaker.com/mcp/docs).

| Tipo | Herramientas |
| --- | --- |
| Lectura | `listar_numeros_whatsapp` |
| Modifican | `crear_webhook_whatsapp`, `editar_webhook_whatsapp`, `simular_mensaje_sandbox_whatsapp` |
| Destructiva | `eliminar_webhook_whatsapp` |

> **PRECAUCION:** Un webhook recibe el tráfico real de clientes: quien cambia la URL decide a dónde van los mensajes. Para pausarlo, `editar_webhook_whatsapp` con `is_active=false` en lugar de borrarlo.

## Funciones relacionadas

- [WhatsApp Business API](https://ardumaker.com/docs/whatsapp-business-api/)
- [Historial de chats](https://ardumaker.com/docs/historial-de-chats/)
- [Router IA](https://ardumaker.com/docs/router-ia/)