Модуль Webhooks
Получение событий из диалогов Hotline في شكل POST-запросов в формате JSON на внешний скрипт для последующей обработки.
В установочном боте @hotlinetg_bot через параметр подключения @WEBHOOKS@ можно установить один или несколько адресов для обработки исходящих POST-запросов со стороны Hotline о событиях в диалогах.
ملاحظة: تحتوي هذه الصفحة على أجزاء مع ترجمة آلية. إذا وجدت صعوبة في فهم هذه المعلومات، فحاول تغيير اللغة إلى الإنجليزية أو الروسية واستخدم نظام ترجمة موقع الويب الموثوق به لديك.
Исходящие запросы со стороны Hotline на указанные адреса с указанными типами событий содержат всю базовую информацию о соответствующем топике и/или пользователе для последующей обработки, а также поле api_key соответствующего подключения для проверки отправителя. При необходимости на своей стороне можно настроить дополнительную проверку отправителя по ip нашего прокси-сервера.
مثال JSON для конфигурации параметра @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"
]
}От Хотлайн можно получать запросы двух типов:
Системные события – про появление, закрытие или повторное открытие диалогов, получение входящих или отправку исходящих сообщений операторами, или с параллельных сессий. Эти события удобно использовать для систем аналитики или дополнительного хранения сообщений в своей базе данных (в том числе для ИИ-ассистентов).
Кастомные команды – сообщают про использование операторами указанных команд, начинающихся с символа / (слеш). Могут мониторится как стандартные команды системы (например /mark أو /close), так и любые кастомные команды, например /invoice (сформировать счет), /client (получить информацию о клиенте по его user_id в Telegram). На события второго типа можно вернуть ответ, который будет отображен в топике с соответствующим диалогом. Эти события удобно использовать для реализации своих команд, которые могут значительно расширить функционал Хотлайн или ускорить работу операторам.
Системные события – про появление, закрытие или повторное открытие диалогов, получение входящих или отправку исходящих сообщений операторами, или с параллельных сессий. Эти события удобно использовать для систем аналитики или дополнительного хранения сообщений в своей базе данных (в том числе для ИИ-ассистентов).
Кастомные команды – сообщают про использование операторами указанных команд, начинающихся с символа / (слеш). Могут мониторится как стандартные команды системы (например /mark أو /close), так и любые кастомные команды, например /invoice (сформировать счет), /client (получить информацию о клиенте по его user_id в Telegram). На события второго типа можно вернуть ответ, который будет отображен в топике с соответствующим диалогом. Эти события удобно использовать для реализации своих команд, которые могут значительно расширить функционал Хотлайн или ускорить работу операторам.
Webhooks доступны только платным пользователям системы
Для приобретения платной подписки или подключения триала на несколько дней для тестирования функции обращайтесь к @hotlinetg_support
Тип 1: Системные события
Системные события задаются из фиксированного набора значений. Отправка системных событий происходит без возврата какого либо результата в соответствующий топик с диалогом.
На данный момент доступны следующие виды событий: dialog_created, dialog_reopened, dialog_closed, message_received, message_sent, message_intercepted.
Примеры применения системных события в диалогах:
- отправка пользователю дополнительных сообщений после начала диалога (например, по таймауту)
- дополнительный контроль входящих и исходящих сообщений по ключевым словам или смыслу сообщений на предмет нарушений операторами
- контроль времени ответа операторов на поступающие обращения
- сбор данных для аналитики по диалогам и/или операторам во внешней системе
- запись сообщений во внешней системе для обучения ИИ-модуля
Пример исходящего запроса о повторном открытии диалога:
{
"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"
}Пример исходящего запроса об отправленном сообщении:
{
"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"
}Тип 2: Кастомные команды
Любая команда, которая начинается символа / (слеш) может быть указана в качестве значения для получения событий о ней и информации о соответствующем диалоге.
Можно указывать как уже существующие стандартные команды системы (/info, /mark, /close итп), так и кастомные, за логику действий которых будет отвечать ваш скрипт и при необходимости возвращать результат в топик в виде JSON или текстового сообщения (допускается разметка в формате Markdown v2).
Примеры применения вебхуков про кастомные команды:
- расширение стандартной команды /info дополнительной информацией о пользователе
- логирование смены статусов диалогов операторами через команду /mark
- логирование событий закрытия обращений командой /close
- добавление своих команд, например /invoice, /client или любых других, для которых нужна информация о топике, в котором идет диалог и данные пользователя или чата.
Пример запроса о вызове команды /mark deal deal оператором:
{
"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"
}Для показа результата выполнения команды в топике ответ вашего сервера должен быть либо в формате обычного текста, либо в виде JSON, у которого есть узел с названием message أو error (другие узлы будут проигнорированы).
Пример успешного ответа вашего сервера в формате JSON:
{
"message": "Deal created: http://internal.domain.com/crm/deals/76238",
"status": "ok"
}Пример ответа вашего сервера в формате JSON об ошибке:
{
"error": "User 12345678 not found in our database"
}По вопросам относительно работы вебхуков, а также для подключения платной подписки или триала необходимо написать в службу поддержки @hotlinetg_support.