КонтекстContext
Компаниям нужны Telegram и MAX для заявок, уведомлений, статусов заказов, поддержки и внутренних сценариев. Но у каждого мессенджера собственные вебхуки, форматы сообщений, кнопки, файлы и правила ответов.Companies use Telegram and MAX for enquiries, notifications, order statuses, support and internal flows. Each messenger, however, has its own webhooks, message formats, buttons, files and reply rules.
При прямом подключении различия расползаются по коду сайта или CRM. Каждая новая интеграция увеличивает сроки, усложняет поддержку и создаёт дополнительные риски для токенов, логов и пользовательских данных.With direct integrations, channel differences spread across the site or CRM codebase. Every new integration adds delivery time, support complexity and risks around tokens, logs and user data.
Бизнес-задачаBusiness task
Нужно было создать единый защищённый шлюз между мессенджерами и системой компании. Сайт, CRM или личный кабинет должны получать события в одном формате и отправлять ответы через один механизм.The task was to create one protected gateway between messengers and the company system. A site, CRM or account area should receive events in one format and send replies through one mechanism.
- Скрыть различия Telegram и MAX от бизнес-системы.Hide Telegram and MAX differences from the business system.
- Оставить заявки и правила обработки в системе клиента.Keep enquiries and processing rules in the client system.
- Защитить токены и секреты.Protect tokens and secrets.
- Сделать доставку и ошибки наблюдаемыми.Make delivery and errors observable.
Что было реализованоWhat was built
Bot Gate Service принимает входящие события, нормализует их, отправляет на endpoint клиента и доставляет ответ пользователю. На стороне клиента достаточно принять стандартное событие и вернуть JSON с сообщением.Bot Gate Service receives incoming events, normalises them, sends them to the client endpoint and delivers the response to the user. The client only needs to accept a standard event and return a JSON message.
Сервис закрывает транспортный слой. Бизнес-логика, заявки и статусы остаются в CRM, сайте, личном кабинете или внутренней системе.The service covers the transport layer. Business logic, enquiries and statuses stay in the CRM, site, account area or internal system.
- Подключение и проверка ботов по токену.Bot connection and token checks.
- Автоматическая регистрация вебхуков.Automatic webhook registration.
- Нормализация текста, команд, кнопок, файлов, контактов и геолокации.Normalisation of text, commands, buttons, files, contacts and location.
- Маршруты по endpoint-ам и запасной маршрут.Endpoint routing and a default fallback route.
- Исходящий API, журналы событий и личный кабинет.Outbound API, event logs and a management dashboard.
- Админка, аудит действий и правила хранения.Admin tools, action audit and retention rules.
Как решения помогают бизнесуHow the decisions help the business
| РешениеDecision | ЗадачаProblem | ПользаBusiness value |
|---|---|---|
| Единый формат событийUnified event format | Скрывает различия каналов.Hides channel differences. | Команда интегрирует один контракт вместо нескольких API.The team integrates one contract instead of several APIs. |
| HTTP-обработчик клиентаClient HTTP handler | Упрощает подключение нового бота.Simplifies connecting a new bot. | Не нужно переносить процессы в конструктор.Processes do not need to move into a bot builder. |
| Нормализация типов сообщенийMessage-type normalisation | Приводит разные события к понятной структуре.Turns different events into a clear structure. | Сценарии обрабатываются одинаково в разных каналах.Flows are handled consistently across channels. |
| Маршрутизация по endpoint-амEndpoint routing | Разделяет команды и процессы.Separates commands and processes. | Один бот обслуживает несколько направлений без хаоса.One bot can serve several areas without tangled code. |
| Запасной маршрутFallback route | Принимает события вне отдельных правил.Catches events outside specific rules. | Обращения не теряются при неполной конфигурации.Enquiries are not lost due to incomplete configuration. |
| Защищённое хранение секретовProtected secret storage | Убирает токены из каждой клиентской интеграции.Removes tokens from every client integration. | Снижается риск утечек и ошибок подключения.Leak and setup-error risk is reduced. |
| Логи событий и доставокEvent and delivery logs | Показывает границу сбоя.Shows where a failure occurs. | Поддержка быстрее отличает проблему канала, шлюза или CRM.Support quickly distinguishes channel, gateway and CRM problems. |
| Исходящий APIOutbound API | Даёт системе компании отправлять сообщения.Lets the company system send messages. | Бот работает и как канал уведомлений.The bot also becomes a notification channel. |
| Личный кабинет и админкаDashboard and admin tools | Выносит операционные настройки из кода.Moves operational settings out of code. | Изменения выполняются быстрее и прозрачнее.Changes become faster and more transparent. |
Почему выбрана такая архитектураWhy this architecture
Инфраструктура отделена от бизнес-логикиInfrastructure is separated from business logic
Для системы клиента оба мессенджера выглядят одинаково: стандартное событие приходит, стандартный ответ уходит. Различия API остаются внутри шлюза.To the client system, both messengers look the same: a standard event arrives and a standard response leaves. API differences stay inside the gateway.
Существующую систему не нужно заменятьThe existing system does not need replacing
Заявки, статусы и правила обработки продолжают жить там, где команда уже работает. Шлюз добавляет коммуникационный слой, не становясь новой CRM.Enquiries, statuses and processing rules stay where the team already works. The gateway adds a communication layer rather than becoming a new CRM.
Диагностика встроена в транспортный слойDiagnostics belong in the transport layer
События, ответы и ошибки фиксируются в одной точке. Это сокращает ручной разбор вебхуков и помогает быстрее найти источник проблемы.Events, responses and errors are recorded in one place. This reduces manual webhook investigation and helps locate faults faster.
РезультатResult
Интеграция бота с сайтом или CRM сводится к понятному контракту: принять событие и вернуть ответ. Команде не нужно отдельно реализовывать вебхуки, хранение токенов, отправку файлов и диагностику для каждого канала.Integrating a bot with a site or CRM comes down to a clear contract: accept an event and return a response. The team no longer implements webhooks, token storage, file sending and diagnostics separately for each channel.
Разработчики работают с одним форматом, поддержка видит статусы и ошибки, а бизнес-логика остаётся в системе компании.Developers work with one format, support sees statuses and errors, and business logic stays in the company system.
Где это применимоWhere it applies
Подход подходит компаниям, у которых уже есть сайт, CRM, личный кабинет или внутренняя система, но нужны мессенджеры как управляемый канал.The approach suits companies that already have a site, CRM, account area or internal system and need messengers as a managed channel.
- Заявки через Telegram и MAX.Enquiries through Telegram and MAX.
- Уведомления о статусах заказов.Order-status notifications.
- Сервисные сообщения.Service messages.
- Внутренняя поддержка.Internal support.
- Боты для партнёров и сотрудников.Bots for partners and employees.
- Единое управление несколькими ботами.Unified management of several bots.
ВыводConclusion
Bot Gate Service не заменяет систему компании. Он закрывает транспортный слой: вебхуки, токены, форматы сообщений, маршрутизацию, ответы, логи и безопасность.Bot Gate Service does not replace the company system. It covers the transport layer: webhooks, tokens, message formats, routing, replies, logs and security.
Для бизнеса это означает более быстрый запуск каналов и меньше зависимости от особенностей каждого мессенджера.For the business, this means faster channel launches and less dependence on the specifics of each messenger.