Webhooks
Conectar canales de WhatsApp y Telegram a un agente
Kelova no te envía webhooks salientes — los "webhooks" de esta página son los que WhatsApp y Telegram envían a Kelova cuando alguien le escribe a tu bot. Tú no implementas nada del lado del receptor: conectas el canal con un solo request y Kelova se encarga del registro y la verificación de firma.
Todos los endpoints de esta página requieren JWT y rol admin.
Conectar un canal
PUT /agents/{id}/channels/{channel_type}channel_type es web, telegram o whatsapp. El body depende del canal.
curl -X PUT https://api.kelova.app/agents/{id}/channels/telegram \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"bot_token": "123456:ABC-DEF..."}'Al conectar, Kelova:
- Genera un
secret_tokenaleatorio (X-Telegram-Bot-Api-Secret-Token) que Telegram debe incluir en cada webhook entrante. - Registra el webhook con la API de Telegram (
setWebhook) usandohttps://api.kelova.app/webhooks/telegram/{agent_id}como URL destino. - Si Telegram rechaza el
bot_token(inválido), la conexión falla con400 CHANNEL_CONNECT_FAILEDy no se guarda nada — no queda un canal a medio configurar.
curl -X PUT https://api.kelova.app/agents/{id}/channels/whatsapp \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"phone_number_id": "1234567890",
"system_user_token": "EAAG...",
"app_secret": "a1b2c3d4...",
"verify_token": "un-token-que-tu-eliges"
}'Estos cuatro valores salen de tu app de WhatsApp Business en Meta for Developers. app_secret se usa para validar la firma HMAC-SHA256 de cada webhook entrante; verify_token es el que Meta te pide al configurar la URL de webhook en su panel — debe coincidir exactamente con el que envías aquí.
curl -X PUT https://api.kelova.app/agents/{id}/channels/web \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{}'El canal web no requiere credenciales de un proveedor externo — el widget se embebe directamente en tu sitio usando allowed_origins del agente (ver Agentes) para validar el origen de cada mensaje.
Respuesta (200) en los tres casos: {}. El canal conectado aparece en active_channels al listar el agente (GET /agents, ver Agentes).
La configuración se cifra con AES-256-GCM antes de persistir — Kelova nunca almacena bot_token, system_user_token ni app_secret en texto plano.
Desconectar un canal
curl -X DELETE https://api.kelova.app/agents/{id}/channels/telegram \
-H "Authorization: Bearer <token>"Responde 204 No Content. Para Telegram, Kelova intenta desregistrar el webhook (deleteWebhook) antes de borrar la config — es best-effort: si falla, la desconexión igual se completa (el webhook huérfano en Telegram deja de importar porque el bot ya no tiene config activa en Kelova).
Verificación de firma — qué hace Kelova por ti
No necesitas verificar nada del lado del cliente; esto es lo que ocurre en cada mensaje entrante una vez que el canal está conectado:
| Canal | Cómo se verifica cada webhook entrante |
|---|---|
| Telegram | Kelova exige el header X-Telegram-Bot-Api-Secret-Token con el secret_token generado al conectar, comparado en tiempo constante |
Kelova valida la firma X-Hub-Signature-256 (HMAC-SHA256 sobre el body, con tu app_secret) en cada POST; el GET inicial de verificación de Meta se responde con tu verify_token |
Estos endpoints (/webhooks/telegram/{agent_id}, /webhooks/whatsapp/agent/{agent_id}) son de infraestructura — los llama Meta/Telegram, no tu integración — por eso no llevan JWT (solo la validación de firma propia de cada proveedor). No los necesitas para nada salvo entender por qué un mensaje no llega: revisa error_message reconectando el canal si la firma nunca valida.