Message Gateway — отдельная подсистема RetailCRM для чатов и мессенджеров, со своим API, токенами и логикой. Это не часть REST API v5: у MG другой домен, свои сущности каналов и сообщений и push-модель обмена, которую важно не путать с классическими методами заказов и клиентов.
Что такое Message Gateway
Message Gateway (MG) — шлюз омниканальных коммуникаций RetailCRM. Он агрегирует переписку из разных мессенджеров и чатов в единый интерфейс чатов CRM. Разработчику MG нужен, когда требуется подключить нестандартный канал связи или бота, которых нет среди готовых интеграций.
MG состоит из двух логических API:
- Transport API — для интеграции нового канала (мессенджера) как источника и приёмника сообщений;
- Bot API — для ботов, которые читают и отправляют сообщения внутри уже подключённых каналов.
https://{mg-host}/api/transport/v1/ и /api/bot/v1/, а не на адресе вашего CRM-аккаунта. Это первое, что отличает его от REST API v5.Авторизация и токены MG
MG использует собственные токены, не apiKey от API v5. Транспорт и бот регистрируются в системе и получают токен, который передаётся заголовком:
X-Transport-Token: {token} — для Transport API;
X-Bot-Token: {token} — для Bot API.
Регистрация транспорта или бота — это отдельный шаг, где вы описываете возможности канала: какие типы сообщений он поддерживает (текст, файлы, изображения), может ли редактировать и удалять сообщения. Эти флаги определяют, что MG будет присылать вашему коду и какие действия примет от него.
Transport API: подключение канала
Transport API нужен, чтобы связать внешний мессенджер с чатами RetailCRM. Логика двусторонняя:
- Входящее сообщение из мессенджера ваш сервис передаёт в MG методом создания сообщения, указывая внешний чат и отправителя.
- Исходящее сообщение (ответ менеджера в CRM) MG присылает вам вебхуком, а ваш сервис доставляет его в мессенджер.
Ключевые операции транспорта:
- регистрация и обновление канала с его возможностями;
- отправка входящих сообщений в MG;
- подтверждение доставки и прочтения;
- приём исходящих сообщений через вебхук.
Таким образом ваш транспорт выступает мостом: приводит формат конкретного мессенджера к унифицированной модели сообщений MG.
Bot API: логика внутри чатов
Bot API работает поверх уже подключённых каналов. Бот не привязан к конкретному мессенджеру — он оперирует диалогами MG и может автоматизировать общение:
- отправлять сообщения в существующие диалоги;
- читать входящие сообщения через вебхуки;
- назначать диалоги на пользователей, менять их состояние;
- реагировать на команды и события.
Отправка сообщения ботом — это POST на метод сообщений Bot API с указанием диалога и содержимого. Bot API удобен для сценариев автоответов, маршрутизации обращений и подсказок менеджеру, не завися от того, из какого мессенджера пришёл клиент.
Вебхуки и модель обмена
MG работает в push-модели: значимые события он присылает на ваш webhook-URL, зарегистрированный при подключении транспорта или бота. Типовые события:
| Событие | Когда приходит |
|---|---|
| Новое сообщение | Менеджер или клиент отправил сообщение |
| Изменение сообщения | Сообщение отредактировано или удалено |
| Статус доставки | Обновился статус прочтения/доставки |
Ваш эндпоинт должен быстро отвечать 200 и обрабатывать событие асинхронно, чтобы MG не считал вебхук недоступным. Долгая синхронная обработка приведёт к таймаутам и повторным доставкам.
Чем MG отличается от REST API v5
Разработчику важно держать в голове границу между двумя API, чтобы выбрать правильный инструмент:
| Параметр | API v5 | MG API |
|---|---|---|
| Домен | Аккаунт CRM | Отдельный MG-хост |
| Авторизация | apiKey | Токены транспорта/бота |
| Модель | Запрос-ответ (pull) | Push через вебхуки |
| Сущности | Заказы, клиенты, каталог | Каналы, диалоги, сообщения |
Практическое правило: всё, что касается сделок и данных — это API v5, а всё, что касается переписки в мессенджерах — MG. Они дополняют друг друга, но живут по разным контрактам.
Итог
Message Gateway API — отдельная подсистема для омниканальных коммуникаций с собственным доменом, токенами и push-моделью. Transport API подключает новые мессенджеры как мосты, Bot API добавляет логику внутри диалогов, а вебхуки доставляют события вашему сервису. Главное — не смешивать MG с REST API v5.
Мы разрабатываем кастомные транспорты и ботов для RetailCRM, а также связываем чаты с сайтом и учётными системами на 1С-Битрикс. Если нужно подключить нестандартный канал общения или автоматизировать переписку, поможем спроектировать интеграцию с MG и REST API как единое целое.
Частые вопросы
Message Gateway — это часть API v5?
Нет. Это отдельная подсистема со своим доменом, токенами и push-моделью. API v5 отвечает за заказы и клиентов, MG — за чаты и мессенджеры.
Чем отличаются Transport API и Bot API?
Transport API подключает новый мессенджер как канал (мост в обе стороны), а Bot API добавляет логику ботов внутри уже подключённых диалогов.
Какой авторизацией пользуется MG?
Собственными токенами: X-Transport-Token для транспорта и X-Bot-Token для бота. apiKey от API v5 в MG не работает.
Как MG доставляет исходящие сообщения?
Через вебхуки на ваш зарегистрированный URL. Эндпоинт должен быстро отвечать 200 и обрабатывать событие асинхронно.
Когда нужен собственный транспорт?
Когда требуется подключить мессенджер или канал, для которого нет готовой интеграции в маркетплейсе RetailCRM.
Может ли бот работать с любым мессенджером?
Да, Bot API оперирует диалогами MG независимо от исходного канала, поэтому логика бота едина для всех подключённых мессенджеров.
Что будет, если вебхук отвечает медленно?
MG может счесть эндпоинт недоступным и повторять доставку. Обрабатывайте события асинхронно, отвечая 200 сразу.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.