Webhooks¶

Recibe eventos de diálogos de Hotline como solicitudes POST en formato JSON para integración con tus sistemas.

Capacidades¶

El módulo de Webhooks permite:

• Rastrear eventos del sistema — creación, cierre y reapertura de diálogos, recepción y envío de mensajes.
• Procesar comandos personalizados — tanto estándar /mark, /info, como propios /invoice, /user y cualquier otro.
• Devolver respuestas a temas — los resultados de ejecución de comandos se pueden mostrar directamente en temas de clientes.

Configuración¶

Los webhooks se configuran a través del bot de configuración @hotlinetg_bot en el parámetro de conexión WEBHOOKS.

Formato de configuración: objeto JSON donde las claves son URLs de tus scripts y los valores son arrays de eventos a rastrear:

Ejemplo de Configuración JSON¶

{
  "https://someapiserver.com/webhooks/test-hook1": [
    "dialog_created",
    "dialog_reopened", 
    "dialog_closed",
    "message_received",
    "message_sent",
    "message_intercepted"
  ],
  "https://someapiserver.com/webhooks/test-hook2": [
    "/mark", "/info",
    "/invoice", "/client"
  ]
}

Eventos del Sistema¶

Notificaciones automáticas sobre eventos de diálogos. Enviadas sin esperar respuesta de tu servidor.

Eventos de Diálogo Disponibles¶

Eventos de Mensaje Disponibles¶

Escenarios de Uso¶

• Envío de mensajes automáticos por tiempo de espera después de inicio de diálogo
• Monitoreo de tiempo de respuesta del operador a solicitudes
• Verificación de mensajes para cumplimiento de política de empresa
• Recopilación de datos para analíticas externas
• Registro de diálogos para entrenamiento de modelos de IA
• Duplicación de mensajes a base de datos corporativa

Ejemplo de Solicitud: Reapertura de Diálogo¶

{
  "event_type": "dialog_reopened",
  "timestamp": "2025-10-09 00:24:55",
  "instance_id": "13209946874612345",
  "data": {
    "chat_id": -1002146012345,
    "thread_id": 5602541568,
    "topic_id": 5343,
    "topic_link": "https://t.me/c/2146012345/5343",
    "user_id": 5339212345,
    "frontend_chat_id": 5339212345,
    "frontend_topic_id": null,
    "frontend_topic_link": null,
    "frontend_user_id": 6406751371,
    "chat_type": "private",
    "title": "Some User Name",
    "department": "default"
  },
  "api_key": "pQTngMZLh0NmAh"
}

Ejemplo de Solicitud: Mensaje Enviado¶

{
  "event_type": "message_sent",
  "timestamp": "2025-10-09 00:21:57",
  "instance_id": "132099468746812345",
  "data": {
    "backend_chat_id": -1002146012345,
    "backend_thread_id": 5602541568,
    "backend_message_id": 6171918336,
    "sender_user_id": 5339212345,
    "frontend_user_id": 640675123,
    "frontend_message_id": 3260022784,
    "text": "test message",
    "content_type": "messageText",
    "department": "default",
    "backend_reply_message_id": 0
  },
  "api_key": "pQTngMZLh0NmAh"
}

Comandos Personalizados¶

Eventos sobre llamadas de comandos de operador. Tu servidor puede registrar el evento correspondiente y devolver respuesta que se mostrará en el tema del diálogo.

• Especifica comandos estándar del sistema en configuración JSON: /info, /mark, /close
• Establece tus propios comandos: /invoice, /client, /order
• Devuelve resultado de ejecución como texto o JSON si es necesario

Escenarios de Uso¶

• Extender /info con información adicional del cliente de otro CRM
• Registrar cambios de estado via /mark para analíticas
• Crear factura con comando /invoice con devolución de enlace
• Obtener datos del cliente de base de datos por /user
• Automatización de procesos empresariales por disparador de comando

Ejemplo de Solicitud: Comando /mark¶

{
  "event_type": "/mark",
  "timestamp": "2025-10-08 20:41:20",
  "instance_id": "132099468746812345",
  "data": {
    "command_data": "deal",
    "chat_id": -1002146012345,
    "topic_id": 5,
    "topic_link": "https://t.me/c/2146012345/5",
    "message_id": 5850,
    "reply_message_id": null,
    "sender_user_id": 123456,
    "user_id": 7890123,
    "frontend_chat_id": 7890123,
    "frontend_thread_id": null
  },
  "api_key": "pQTngMZLh0NmAh"
}

Formato de Respuesta¶

Tu servidor puede devolver resultado como texto plano o JSON con nodos message o error.

Ejecución exitosa:

{
  "message": "Oferta creada: http://internal.domain.com/crm/deals/76238",
  "status": "ok"
}

Error de ejecución:

{
  "error": "Usuario 12345678 no encontrado en nuestra base de datos"
}

Respuesta de texto:

Puedes devolver solo texto con soporte de Markdown v2:

✅ Factura №12345 creada
Total: 1500
Enlace: https://intranet.example.com/invoice/12345

Seguridad¶

• Almacena api_key y otros tokens en lugar seguro
• Usa HTTPS para todos los endpoints de webhook
• Implementa validación de api_key en tu servidor
• Registra todas las solicitudes recibidas para auditoría
• Configura tiempo de espera de respuesta a 5-10 segundos
• Considera limitar tasa de procesamiento de solicitudes

Recomendaciones¶

• Procesa eventos de manera asíncrona para no bloquear respuesta
• Usa cola de mensajes para procesamiento confiable
• Implementa lógica de reintento para eventos críticos
• Monitorea disponibilidad de tu endpoint
• Prueba webhooks en entorno de prueba antes de producción
• Documenta procesamiento de cada tipo de evento
• Tamaño máximo de mensaje de respuesta — 4096 caracteres (limitación de Telegram)