Руководство по интеграции вебхуков TG-Staff: автоматизация диалогов, сообщений и операционных процессов

Когда вы управляете командой поддержки Telegram-бота, одна из самых головных болей — разрозненность данных: диалоги в TG-Staff, информация о клиентах в CRM, тикеты в другой системе. Приходится вручную копировать и вставлять или писать скрипты для опроса API TG-Staff, чтобы получить данные — это неэффективно и чревато ошибками.

События вебхуков TG-Staff созданы именно для решения этой проблемы. Это не «кнопка экспорта», которую нужно нажимать вручную, а мост для передачи данных в реальном времени: когда в платформе происходит ключевое событие (например, пользователь отправляет новое сообщение, оператор назначается на диалог, диалог закрывается), TG-Staff активно отправляет данные события на указанный вами URL. Ваш сервер, получив POST-запрос, может автоматически создавать тикеты, обновлять метки пользователей, запускать опросы удовлетворенности — реализуя по-настоящему «событийно-ориентированную» автоматизацию.

Эта статья подробно объясняет настройку вебхуков TG-Staff, типы подписываемых событий и 3 готовых сценария интеграции. Если вы ищете способ связать данные поддержки Telegram с вашими собственными системами, это руководство стоит сохранить.

---

Что такое события вебхуков TG-Staff? — от пассивного приёма к активной интеграции

Проще говоря, вебхук — это «обратный API»: обычно вам нужно активно вызывать API для проверки данных (например, каждые 5 секунд проверять, нет ли новых сообщений), а вебхук — это когда TG-Staff при наступлении события активно отправляет данные на ваш сервер.

Его ключевая ценность — работа в реальном времени и отказ от опроса. Представьте:

• Без вебхуков: вам нужно написать задачу по расписанию, каждые 10 секунд вызывать интерфейс «получить непрочитанные диалоги» TG-Staff, обрабатывать много повторяющихся данных — нагрузка на сервер высока, и есть задержки.
• С вебхуками: когда пользователь впервые отправляет сообщение боту, TG-Staff немедленно отправляет событие conversation.created на ваш URL, и вы сразу узнаёте «пришёл новый клиент», можете автоматически создать лид в CRM.

Для команд B2B SaaS, служб поддержки кросс-граничной электронной коммерции, проектов Web3 это означает возможность бесшовно интегрировать данные поддержки Telegram в существующие системы тикетов (например, Zendesk, Freshdesk), платформы аналитики (например, Mixpanel) или даже внутренние уведомления Slack или DingTalk.

---

Обзор типов подписываемых событий

TG-Staff в настоящее время поддерживает следующие события вебхуков (актуальный список — в официальной документации). Каждое событие соответствует фиксированной строке event_type, которую вы можете использовать для логической маршрутизации на целевом сервере.

Имя события	event_type	Момент срабатывания	Типичное применение
Создание нового диалога	conversation.created	Пользователь впервые связывается с ботом или повторно открывает закрытый диалог	Автоматическое создание лида в CRM, отправка приветственного уведомления
Новое сообщение	message.received	Пользователь или оператор отправляют сообщение (включая текстовый контент, такой как текст, изображения)	Синхронизация сообщений в реальном времени с системой контроля качества или базой знаний
Изменение статуса диалога	conversation.status_changed	Диалог переходит из «Ожидания» → «Назначен» → «В обработке» → «Закрыт»	Запуск обновления статуса тикета, запуск опроса удовлетворённости при закрытии
Изменение статуса оператора	agent.status_changed	Оператор входит/выходит из системы или переключается в статус «Занят»	Обновление панели смены команды, отправка уведомления в Slack

---

Как настроить события Webhook? — Три шага для интеграции

Настройка выполняется в консоли TG-Staff, не требует написания кода, нужен только сервер, принимающий POST-запросы.

Шаг 1: Найдите точку входа для настройки Webhook

Войдите в консоль TG-Staff и перейдите в раздел настроек проекта. В боковом меню найдите пункт «Разработчикам» или «Интеграции» (точное название зависит от версии консоли). Вы увидите блок «Настройка Webhook».

Шаг 2: Укажите целевой URL для получения событий

• URL должен использовать протокол HTTPS (TG-Staff не отправляет данные на HTTP-эндпоинты).
• Если ваш сервер требует аутентификации, добавьте пользовательские заголовки в разделе «Заголовки запроса» (например, Authorization: Bearer your-secret-token).
• После нажатия «Сохранить» TG-Staff отправит на указанный URL тестовый запрос ping для проверки соединения. Если сервер вернёт 200, конфигурация вступит в силу.

Шаг 3: Выберите типы событий для подписки

Вам не нужно подписываться на все события. Отметьте только те, которые необходимы для вашей интеграции. Например:

• Нужно создавать запись в CRM при первом обращении пользователя → отметьте только conversation.created
• Нужно синхронизировать все сообщения с внутренней системой → отметьте message.received
• Нужно отслеживать полный жизненный цикл диалога → отметьте conversation.created + conversation.status_changed + message.received

Проверка работоспособности Webhook

После настройки проще всего проверить: отправьте сообщение вашему боту с другого Telegram-аккаунта и проверьте журналы целевого сервера.

Часто возникающие проблемы:

• URL недоступен: проверьте, разрешён ли в брандмауэре трафик с исходящих IP-адресов TG-Staff (список IP можно найти в консоли).
• Тайм-аут ответа: TG-Staff ожидает ответ 200 в течение 5 секунд. Если логика обработки сложная, рекомендуется сразу возвращать 200, а затем обрабатывать данные асинхронно (например, через очередь).
• Ошибка проверки подписи: если TG-Staff поддерживает ключи подписи (сверьтесь с официальной документацией), убедитесь, что вы проверяете HMAC-подпись в заголовке X-TG-Staff-Signature.

Рекомендации по безопасности: проверка подписи и механизм повторных попыток

• Проверка подписи: если TG-Staff предоставляет ключ подписи, обязательно проверяйте подпись запроса на стороне получателя, чтобы предотвратить подделку callback-запросов. Обычно подпись вычисляется как HMAC-SHA256 от тела запроса и сравнивается со значением в заголовке.
• Стратегия повторных попыток: если целевой сервер возвращает код, отличный от 200, TG-Staff по умолчанию повторяет отправку до 3 раз с интервалами примерно 30 секунд, 2 минуты и 5 минут. Если все попытки неудачны, событие отбрасывается (исходные данные остаются в платформе TG-Staff без потерь). Рекомендуется, чтобы ваш сервер всегда возвращал 200, подтверждая получение.

---

Типовые сценарии интеграции: от поддержки до автоматизации

Ниже описаны 3 сценария, демонстрирующие, как события Webhook связывают TG-Staff с вашими бизнес-системами.

Сценарий 1: Новый диалог → автоматическое создание заявки в CRM

Событие: conversation.created

Процесс: Когда пользователь впервые отправляет сообщение боту, TG-Staff отправляет событие на ваш сервер → сервер извлекает из события ID пользователя, ID диалога, текст первого сообщения → автоматически создаёт лид или заявку в CRM (HubSpot, Salesforce и т.д.) с заголовком «Новое обращение от пользователя Telegram [имя пользователя]» и ссылкой на диалог.

Преимущества: операторам не нужно вручную вводить данные клиента, отдел продаж сразу видит источник лида.

Сценарий 2: Ответ оператора → синхронизация сообщения с системой контроля качества

Событие: message.received

Процесс: Каждый раз, когда оператор отправляет сообщение, событие отправляется в систему контроля качества (например, внутреннюю платформу комплаенс) → система проверяет сообщение на наличие рискованных слов (может работать совместно с профессиональной версией TG-Staff по контролю контента) → если обнаружено чувствительное слово, сообщение автоматически помечается, а контролёр получает уведомление.

Преимущества: реализация контроля качества диалогов в реальном времени, особенно важно для отраслей с высокими требованиями к комплаенсу, таких как Web3 и финансы.

Сценарий 3: Закрытие диалога → запуск опроса удовлетворённости

Событие: conversation.status_changed (статус меняется на closed)

Процесс: Когда оператор закрывает диалог, TG-Staff отправляет событие → сервер проверяет, что статус стал closed → автоматически отправляет пользователю ссылку на опрос удовлетворённости (через функцию массовой рассылки TG-Staff или отдельного бота) → результаты опроса передаются в платформу анализа данных.

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

---

Интеграция с другими функциями TG-Staff

События Webhook не изолированы; они могут работать совместно с существующими возможностями TG-Staff, создавая дополнительную ценность.

• Диверсионные ссылки + событие нового диалога: когда пользователь переходит по рекламной диверсионной ссылке (Diversion Link) и попадает к боту, событие conversation.created содержит поле referrer (например, источник рекламы, параметры URL). Вы можете анализировать эффективность различных каналов.
• Изменение статуса оператора + внутренние уведомления: если оператор отсутствует более 30 минут, событие agent.status_changed может инициировать уведомление через Slack или DingTalk-бота, напоминая руководителю скорректировать расписание.
• Обогащение данных профиля пользователя: в callback-событии TG-Staff передаёт ID пользователя. Вы можете вызвать API профиля пользователя (требуется профессиональная версия) для получения тегов и краткой истории диалога, объединить с данными события и записать во внешнюю базу данных.

Важно: избегайте дублирования данных и циклов

Это часто упускаемый из виду момент. Если ваш целевой сервер Webhook также отправляет запросы в TG-Staff (например, через API TG-Staff для отправки сообщений), а это сообщение в свою очередь вызывает событие message.received, возникает бесконечный цикл A → B → A.

Решение: в логике обработки события проверяйте источник сообщения. Например, в полезной нагрузке события определите, является ли sender_type значением agent или system. Если сообщение отправлено оператором, пропускайте операцию записи, чтобы избежать дублирования.

---

Часто задаваемые вопросы

Вопрос: Поддерживает ли TG-Staff Webhook пользовательские поля или фильтры?
Ответ: В настоящее время события TG-Staff отправляются на основе фиксированных типов событий и не поддерживают пользовательские поля. Однако вы можете использовать ID сессии или ID пользователя в событии и после получения вызвать другие API (например, API профиля пользователя) для дополнения данных. Фильтрацию рекомендуется реализовывать на стороне целевого сервера.

Вопрос: Что произойдет, если отправка события Webhook не удалась? Есть ли механизм повторных попыток?
Ответ: Да, по умолчанию TG-Staff выполняет до 3 повторных попыток (с интервалами около 30 секунд, 2 минут и 5 минут). Если все попытки неудачны, событие отбрасывается, но это не приводит к потере данных (поскольку исходные данные остаются на платформе TG-Staff). Рекомендуется, чтобы целевой сервер возвращал код 200.

Вопрос: Можно ли настроить несколько URL-адресов Webhook для получения одного и того же события?
Ответ: В настоящее время каждый проект TG-Staff поддерживает только один URL-адрес Webhook. Если необходимо распределить события по нескольким системам, рекомендуется настроить внутреннюю пересылку на целевом сервере (например, с помощью очередей сообщений или промежуточного ПО).

Вопрос: Содержат ли события Webhook личные данные пользователей (например, номера телефонов, email)?
Ответ: События Webhook в основном передают метаданные, такие как статус сессии, ID сообщения, ID пользователя, и не содержат конфиденциальную информацию пользователя из Telegram (например, номер телефона). Пользовательские данные в профилях (например, теги) могут содержать бизнес-данные — обрабатывайте их в соответствии с вашей политикой конфиденциальности.

Вопрос: Как проверить, работает ли конфигурация Webhook?
Ответ: На странице конфигурации Webhook в консоли обычно есть кнопка «Отправить тестовое событие». Если её нет, вы можете вручную создать новую сессию (например, отправив сообщение через тестового бота) и проверить, получил ли целевой сервер соответствующий POST-запрос.

---

Начните интеграцию с данными Telegram-поддержки

События TG-Staff Webhook — это «скоростная магистраль» для соединения данных поддержки с бизнес-системами. Хотите ли вы автоматически создавать тикеты в CRM, проверять качество сообщений в реальном времени или строить сквозной анализ поведения пользователей — Webhook избавит вас от необходимости опроса и позволит данным действительно течь.

• Бесплатная пробная версия: Зарегистрируйтесь и получите 3 дня бесплатного доступа. Функция Webhook доступна в тарифах Standard и выше (подробности на официальном сайте).
• Ознакомьтесь с документацией: Получите актуальный список событий, описание полей и примеры проверки подписи → Официальная документация TG-Staff
• Свяжитесь с поддержкой: Есть вопросы по интеграции? Напишите @tgstaff_robot, и техническая команда поможет вам с настройкой.

Попробуйте интеграцию событий Webhook прямо сейчас и превратите управление Telegram-поддержкой из «ручной работы» в автоматизированный рабочий процесс на основе событий.