Agente externo de WhatsApp

Con el agente externo, Orkestal sigue recibiendo los mensajes de WhatsApp, guardando el historial y dejando que tu equipo atienda desde la bandeja, pero las respuestas las genera tu propio agente (por ejemplo, un workflow de n8n con tu modelo y tus reglas) en lugar del agente nativo de Orkestal.

Es una opción avanzada para equipos técnicos. Si no necesitas esto, deja el modo Agente Orkestal.

Cómo funciona#

1. Un cliente escribe por WhatsApp.
2. Orkestal guarda el mensaje y manda un webhook firmado a tu servicio.
3. Tu agente genera la respuesta y la manda a Orkestal por el callback del evento.
4. Orkestal la envía por WhatsApp y la registra en la conversación.

Configurar#

1. Prepara el webhook#

Publica un Webhook POST con una URL HTTPS pública (usa la URL de producción). Confirma la recepción con un 2xx rápido y procesa al cliente después. Verifica la firma antes de ejecutar tu agente.

2. Actívalo en Orkestal#

1. Ve a Configuración → WhatsApp → Quién responde en WhatsApp.
2. Elige Agente externo (n8n o webhook), pega la URL y genera un secreto. Cópialo a tu receptor antes de guardar.
3. Usa Probar conexión. El evento orkestal.connection.test debe confirmarse sin generar una respuesta al cliente.

3. Crea una API key#

En Integraciones → n8n crea una API key con messages:write. Para leer historial y estados añade messages:read y conversations:read. Guárdala como credencial de tipo Header Auth: Authorization: Bearer TU_API_KEY_DE_ORKESTAL.

El evento que recibes#

{
  "event": "whatsapp.message.received",
  "version": 1,
  "event_id": "UUID_DEL_EVENTO",
  "business_id": "UUID_DEL_NEGOCIO",
  "conversation_id": "UUID_DE_LA_CONVERSACION",
  "channel": "whatsapp",
  "contact": { "id": "UUID", "name": "Ana", "phone": "5215550001111" },
  "message": { "id": "UUID", "content": "Hola", "message_type": "text", "file_url": null, "created_at": "FECHA_ISO" },
  "reply_path": "/api/public/v1/external-agent/events/UUID_DEL_EVENTO/reply",
  "expires_at": "FECHA_ISO"
}

Deduplica por event_id: el mismo evento puede volver a llegar tras un fallo de red. Para dar contexto a tu agente, consulta los últimos mensajes en orden cronológico:

GET /api/public/v1/conversations/UUID_DE_LA_CONVERSACION/messages?limit=50

Devolver la respuesta#

Después de tu nodo de agente, usa un HTTP Request con el reply_path del evento original:

POST /api/public/v1/external-agent/events/UUID_DEL_EVENTO/reply
Authorization: Bearer TU_API_KEY_DE_ORKESTAL

{ "text": "¡Hola, Ana! ¿En qué te ayudamos?" }

• Un 202 confirma que quedó en la cola. Puedes consultar el envío con GET /api/public/v1/external-agent/events/UUID_DEL_EVENTO. El estado sent indica que Meta aceptó el mensaje.
• Devolver texto en la respuesta HTTP del webhook no envía un WhatsApp. Usa siempre el callback.
• Esta primera versión admite una respuesta de texto por turno, de hasta 4,096 caracteres.

Firma del webhook#

Verifica la cabecera X-Orkestal-Signature: es sha256= seguido del HMAC-SHA256 hexadecimal de X-Orkestal-Timestamp + "." + cuerpo original del POST, con tu secreto. Usa los bytes originales, una comparación en tiempo constante y una tolerancia de reloj de 5 minutos. En n8n habilita Raw Body. Ejemplo de código en Webhooks.

Cuando atiende tu equipo#

• Pausar el agente desde la conversación también detiene al agente externo.
• Una respuesta humana invalida el turno pendiente.
• Si llega otro mensaje del cliente, vence el turno anterior: usa el evento nuevo. Los turnos vencen también a los 10 minutos.
• Un callback repetido con el mismo texto no envía otro mensaje. Un texto distinto para el mismo evento devuelve 409.
• Si el estado es send_unknown, revisa WhatsApp antes de responder de nuevo: no se reenvía automáticamente un mensaje cuya entrega es incierta.

Puedes revisar los últimos turnos en Configuración → WhatsApp.

Volver a la IA de Orkestal o a atención humana#

En Quién responde en WhatsApp elige Agente Orkestal para volver a la IA nativa, o Solo atención humana para que tu equipo atienda desde la bandeja sin respuestas automáticas.