Base de conocimientos

hotline.tg

Módulo de webhooks

Recibir eventos de diálogos Hotline como POST-solicitudes en el formato JSON a un script externo para su posterior procesamiento.
En el bot de instalación @hotlinetg_bot a través del parámetro de conexión @WEBHOOKS@ Puede configurar una o más direcciones para procesar el correo saliente. POST-solicitudes del exterior Hotline sobre los acontecimientos en los diálogos.
Atencion: Esta página contiene fragmentos con traducción automática. Si le resulta difícil comprender esta información, intente cambiar el idioma a inglés o ruso y utilice su sistema de traducción de sitios web de confianza.
Solicitudes salientes desde el lado Hotline a las direcciones especificadas con los tipos de eventos especificados contienen toda la información básica sobre el tema y/o usuario correspondiente para su posterior procesamiento, así como el campo api_key La conexión correspondiente para la verificación del remitente. Si es necesario, puede configurar una verificación adicional del remitente utilizando la dirección IP de nuestro servidor proxy.
ejemplo JSON para configurar el parámetro @WEBHOOKS@:
{
  "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"
  ]
}
Puede recibir dos tipos de solicitudes de Hotline:

Eventos del sistema – sobre la apertura, el cierre o la reapertura de diálogos, la recepción o el envío de mensajes por parte de los operadores, o desde sesiones paralelas. Estos eventos son útiles para sistemas de análisis o para el almacenamiento adicional de mensajes en su base de datos (incluso para asistentes de IA).

Comandos personalizados – informa sobre el uso de comandos específicos por parte de operadores que comienzan con el símbolo / (barra diagonal). Se puede monitorear como comandos estándar del sistema (por ejemplo /mark o /close), así como cualquier comando personalizado, por ejemplo /invoice (generar una factura), /client (obtener información sobre el cliente por su user_id в TelegramLos eventos del segundo tipo pueden devolver una respuesta, que se mostrará en el tema con el cuadro de diálogo correspondiente. Estos eventos son útiles para implementar comandos personalizados que pueden ampliar significativamente la funcionalidad de Hotline o agilizar el trabajo del operador.
Los webhooks están disponibles solo para usuarios pagos del sistema.
Para comprar una suscripción paga o conectar una prueba por varios días para probar la función, comuníquese con @hotlinetg_soporte
Tipo 1: Eventos del sistema
Los eventos del sistema se definen a partir de un conjunto fijo de valores. Se envían sin devolver ningún resultado al tema de diálogo correspondiente.
Actualmente están disponibles los siguientes tipos de eventos: diálogo_creado, diálogo reabierto, diálogo cerrado, message_recibió, message_enviado, message_interceptado.
Ejemplos de uso de eventos del sistema en diálogos:
  • enviar mensajes adicionales al usuario después del inicio de un diálogo (por ejemplo, después de un tiempo de espera)
  • Monitoreo adicional de mensajes entrantes y salientes por palabras clave o el significado de los mensajes para detectar violaciones por parte de los operadores
  • Control de los tiempos de respuesta del operador a las solicitudes entrantes
  • Recopilación de datos para análisis sobre diálogos y/o operadores en un sistema externo
  • Grabar mensajes en un sistema externo para entrenar el módulo de IA
Ejemplo de una solicitud saliente para reabrir un 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 una solicitud saliente para un 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"
}
Tipo 2: Comandos personalizados
Cualquier comando que comience con el símbolo / (barra) se puede especificar como un valor para recibir eventos sobre él e información sobre el diálogo correspondiente.
Puede especificar ambos comandos de sistema estándar existentes (/info, /mark, /close etc.), así como las personalizadas, para la lógica de acciones de las que será responsable su script y, si es necesario, devolver el resultado al tema en el formulario JSON o un mensaje de texto (se permite marcar en el formato) Markdown v2).
Ejemplos de uso de webhooks con comandos personalizados:
  • extensión del comando estándar /info información adicional sobre el usuario
  • Registrar cambios en los estados de diálogo por parte de los operadores mediante un comando /mark
  • Registro de eventos de solicitudes de cierre por parte del comando /close
  • añadiendo tus propios comandos, por ejemplo /invoice, /client o cualquier otro que requiera información sobre el tema en el que se desarrolla la conversación y datos del usuario o del chat.
Ejemplo de una solicitud de llamada de comando /mark deal operador de transacciones:
{
    "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"
}
Para mostrar el resultado de un comando en un tema, la respuesta de su servidor debe ser en texto simple o en el formato JSON, que tiene un nodo con el nombre message o error (los demás nodos serán ignorados).
Un ejemplo de una respuesta exitosa de su servidor en el formato JSON con un mensaje que se mostrará en el tema con el diálogo:
{
    "message": "Deal created: http://internal.domain.com/crm/deals/76238",
    "status": "ok"
}
Un ejemplo de la respuesta de su servidor con el texto de error en el formato JSON, que se mostrará en el tema con el diálogo:
{
    "error": "User 12345678 not found in our database"
}
Si tiene preguntas sobre webhooks o para activar una suscripción paga o una prueba, comuníquese con el soporte. @hotlinetg_soporte.