Кейс SiteHelper: как устроены сбор заявок, очередь уведомлений и статусы
SiteHelper — Telegram-бот Skycode, который помогает клиенту описать задачу и передать её администратору в структурированном виде. В этом кейсе важен не набор кнопок, а внутренняя надёжность: заявка не должна зависеть от одного запроса к Telegram API или повторной доставки webhook.
Мы разделили процесс на три части: сбор данных в диалоге, устойчивое сохранение заявки и независимую очередь уведомлений. Ниже — устройство этой связки без выдуманных показателей и маркетинговых обещаний.
1. Задача: превратить диалог в структурированную заявку
Бот последовательно собирает выбранные услуги, тип сайта, описание задачи, техническое задание, бюджетный диапазон, срочность, контакт и источник перехода. Эти поля складываются в состояние текущего диалога, а перед подтверждением пользователь видит собранную информацию.
После подтверждения создаётся отдельная запись заявки. Техническое задание может быть передано как документ или фотография, а сведения о вложении связываются с той же заявкой. Такой формат удобнее свободного сообщения: менеджер получает одинаковую структуру и быстрее понимает контекст.
2. Webhook принимает только проверенные обновления
Публичная точка webhook проверяет секретный заголовок Telegram и отклоняет запрос, если конфигурация неполная или проверка не пройдена. Ошибки PHP не показываются посетителю, а записываются в закрытый журнал вне публичной части сайта.
После проверки входных данных FastCGI может вернуть Telegram ответ HTTP 200 до завершения дальнейшей обработки. Это снижает риск повторной доставки обновления из-за медленного внешнего API, но не отменяет отдельную защиту от дублей.
3. Повторное обновление не создаёт вторую операцию
Каждое обновление Telegram имеет идентификатор. SiteHelper пытается записать его в таблицу обработанных обновлений с уникальным ключом. Если такой идентификатор уже существует, webhook подтверждает запрос и прекращает повторную обработку.
Для подтверждения самой заявки используется отдельный уникальный токен черновика. Даже если пользователь или сеть повторят финальную операцию, система возвращает существующую запись вместо создания второй. Старые идентификаторы обновлений периодически очищаются, чтобы служебная таблица не росла бесконечно.
4. Заявка сохраняется раньше уведомления
Заявки хранятся в отдельной SQLite-базе вне веб-каталога. Запись содержит структурированные поля, исходный JSON и служебные даты. Для рабочего процесса предусмотрены три состояния: новая, в работе и закрыта.
Сначала выполняется сохранение, и только затем формируются задания на уведомление администратора. Это тот же принцип, который мы разбирали в статье о пути заявки от сайта до менеджера: внешний канал доставки не должен быть единственным местом, где существует обращение.
5. Outbox отделяет приём заявки от Telegram API
SiteHelper не отправляет административное сообщение напрямую в момент создания заявки. Вместо этого он добавляет в таблицу outbox описание метода Telegram API и необходимые параметры. В очередь отдельно попадают основное уведомление и, если есть, вложенное техническое задание.
У каждой задачи есть состояние, число попыток, время следующего запуска, отметка блокировки и последняя ошибка. Благодаря этому временная недоступность Telegram не превращается в потерю заявки, а историю сбоя можно проверить.
6. Отдельный worker отвечает за доставку и повторы
Фоновый worker запускается по расписанию каждую минуту. Он атомарно забирает готовую задачу, переводит её в обработку и после успешного ответа отмечает отправленной. За один запуск обрабатывается ограниченная партия, чтобы процесс не удерживал сервер бесконечно.
Если доставка не удалась, worker увеличивает счётчик и назначает повтор с растущей задержкой, ограниченной одним часом. После восьми неудачных попыток задача получает состояние failed. Зависшие блокировки старше пяти минут возвращаются в очередь, поэтому аварийное завершение worker не оставляет задание навсегда в состоянии processing.
7. Администратор управляет заявками из бота
Администратор получает карточку с номером заявки, услугами, задачей, бюджетом, срочностью, контактом и источником. Если клиент прикрепил техническое задание, оно доставляется отдельным сообщением и связано с номером обращения.
Внутри бота доступен список последних заявок и счётчики по состояниям. Инлайн-кнопки позволяют перевести обращение в работу, вернуть в новые или закрыть. Обработчик административных команд проверяет идентификатор администратора на сервере, поэтому одного скрытия кнопок в интерфейсе недостаточно.
Что дала такая архитектура
В результате приём заявки, доставка уведомления и работа со статусами стали независимыми этапами. Сбой Telegram API не удаляет сохранённые данные, повтор webhook не дублирует операцию, а менеджер видит единый статус обращения. Конфигурация, база, состояния и журналы находятся вне публичного каталога.
Такая схема подходит не только Telegram-боту: те же принципы применимы к формам сайта, CRM и внутренним кабинетам. Важно заранее определить источник истины, правила повторов и ответственного за ошибки. Опишите свой сценарий в брифе — мы предложим архитектуру сбора и обработки заявок под ваш процесс.
