Webhooks¶

Получайте события из диалогов Hotline в виде POST-запросов в формате JSON для интеграции с вашими системами.

Возможности¶

Модуль Webhooks позволяет:

• Отслеживать системные события — создание, закрытие и повторное открытие диалогов, получение и отправку сообщений.
• Обрабатывать собственные команды — как стандартные /mark, /info, так и ваши собственные /invoice, /user и любые другие.
• Возвращать ответы в топики — результаты вызова команд могут быть показаны прямо в топиках с клиентами.

Настройка¶

Webhooks настраиваются через установочного бота @hotlinetg_bot в параметре WEBHOOKS подключения.

Формат конфигурации: JSON-объект, где ключи — URL-адреса ваших скриптов, а значения — массивы событий для отслеживания:

Пример 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"
  ]
}

Системные события¶

Автоматические уведомления о событиях в диалогах. Отправляются без ожидания ответа от вашего сервера.

Доступные события для диалогов¶

Доступные события для сообщений¶

Варианты использования¶

• Отправка автоматических сообщений по таймауту после начала диалога
• Контроль времени ответа операторов на обращения
• Проверка сообщений на соответствие политикам компании
• Сбор данных для внешней аналитики
• Запись диалогов для обучения AI-моделей
• Дублирование сообщений в корпоративную базу данных

Пример запроса: Повторное открытие диалога¶

{
  "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"
}

Кастомные команды¶

События о вызове команд операторами. Ваш сервер может логировать соответствующее событие и вернуть ответ, который будет показан в топике диалога.

• Укажите в JSON-конфиге стандартные команды системы: /info, /mark, /close
• Задайте собственные команды: /invoice, /client, /order
• Возвращайте результат выполнения в виде текста или JSON, если нужно

Варианты использования¶

• Расширение /info дополнительной информацией о клиенте из другой CRM
• Логирование смены статусов через /mark для аналитики
• Создание счета командой /invoice с возвратом ссылки
• Получение данных о клиенте из базы данных по /user
• Автоматизация бизнес-процессов по триггеру команд

Пример запроса: Команда /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"
}

Формат ответа¶

Ваш сервер может вернуть результат в виде обычного текста или JSON с узлами message или error.

Успешное выполнение:

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

Ошибка выполнения:

{
  "error": "User 12345678 not found in our database"
}

Текстовый ответ:

Можно вернуть просто текст с поддержкой Markdown v2:

✅ Invoice №12345 created
Total: 1500
Link: https://intranet.example.com/invoice/12345

Безопасность¶

Все запросы от Hotline содержат поле api_key соответствующего подключения для проверки отправителя.

• Проверяйте api_key на вашей стороне
• Настройте фильтрацию по IP прокси-сервера Hotline
• Используйте HTTPS для Webhooks URL

Практические сценарии¶

Советы по отладке¶

1. Используйте сервисы для тестирования Webhooks: postman.com, requestbin.com
2. Логируйте все входящие запросы на вашем сервере
3. Возвращайте корректный HTTP-статус ответа (должен быть 200 OK)
4. Следите за таймаутом — ответ должен приходить быстро (рекомендуется до 3 секунд)
5. Обрабатывайте ошибки gracefully и возвращайте понятные сообщения

Ограничения¶

• Таймаут ответа для команд — рекомендуется не более 3 секунд
• Размер ответа — до 4096 символов (ограничение Telegram)
• Повторные попытки — при недоступности вашего сервера запрос может быть повторен
• Rate limits — при большом потоке событий учитывайте возможности вашего сервера

Поддержка¶

По вопросам настройки вебхуков, подключения платной подписки обращайтесь в службу поддержки @hotlinetg_support