Webhooks de WhatsApp

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

Categoría: Comunicación
Estado: Disponible
Requisitos: Una cuenta de WhatsApp 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

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

Mensaje entrante hacia el webhook — 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.

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