Как подключить MAX и VK к Chatwoot: двусторонний API‑мост

Что за «двусторонний мост» и зачем он нужен?

Вы, как и многие, уже знакомы с Chatwoot – открытой платформой для омниканального саппорта. В ней удобно собирать запросы из разных мессенджеров, вести диалог с клиентом и хранить историю. Но что делать, если ваш клиент предпочитает «домашние» каналы, такие как MAX (мессенджер с бот‑интерфейсом) или сообщения в группе VK?

Автор статьи решил собрать их в один вход‑выход Chatwoot, чтобы в системе не «разбрасываться» по разным консолям. И сделал это не скрапингом веб‑версий и не «клик‑ботом», а настоящим API‑мостом:

MAX – через официального бота, зарегистрированного в системе мессенджера.
VK – через сообщения сообщества (сообщения от пользователей к публичной странице).

Мостом служит лёгкий сервис на Node.js, который принимает веб‑хуки от обоих мессенджеров, создаёт в Chatwoot нужный контакт и диалог, а затем отправляет ответы обратно в исходный канал.

Как работает поток сообщений

1. Приход сообщения в мессенджер

Мессенджер	Как приходит в мост
MAX	Бот получает событие `message` через свой webhook‑endpoint.
VK	Сообщения сообщества доставляются в webhook, который вы указываете в настройках API VK.

2. Обработка в Node‑сервисе

Маршрут вебхука – отдельный endpoint для каждого канала (/webhook/max, /webhook/vk).
Идентификация отправителя – из полезной нагрузки берём уникальный user_id (MAX) или from_id (VK).
Создание/поиск контакта в Chatwoot
- Если контакт уже существует – берём его inbox_id и conversation_id.
- Если нет – вызываем API Chatwoot POST /api/v1/accounts/:account_id/contacts и сохраняем соответствие в локальном хранилище (обычно простая SQLite или Redis‑таблица).
Создание диалога – аналогично через POST /api/v1/accounts/:account_id/conversations.

3. Перенаправление сообщения в Chatwoot

Сформированный запрос POST /api/v1/accounts/:account_id/conversations/:conversation_id/messages отправляется в Chatwoot. В теле указываем content, message_type (text, image) и, при необходимости, массив attachments.

4. Ответ из Chatwoot обратно в мессенджер

Когда агент пишет ответ в интерфейсе Chatwoot, система генерирует webhook message_created. Наш сервис ловит его, определяет исходный канал по сохранённому соответствию и:

Для MAX – отправляет запрос в Bot API sendMessage.
Для VK – использует метод messages.send API VK, указывая peer_id получателя.

Если в ответе есть вложения (изображения), сервис сначала скачивает их из Chatwoot, а затем загружает в соответствующий мессенджер, передавая полученную ссылку.

Где «мост» пока не стал надёжной шиной

Отсутствие очереди – каждый запрос обрабатывается синхронно. При пиковой нагрузке могут возникать таймауты.
Идемпотентность – сервис проверяет message_id и игнорирует дубли, но в случае падения процесс может повторно отправить одно и то же сообщение.
Хранение соответствий – простая БД без репликации. При сбое данных потребуется пере‑синхронизация контактов.
Обработка ошибок API – сейчас реализовано простое логирование; нет автоматических ретраев с экспоненциальным бэкофом.

Эти «дырки» не критичны для небольших проектов, но если планируете обслуживать сотни запросов в час, придётся добавить очередь (RabbitMQ, Kafka) и более надёжное хранилище (PostgreSQL).

Кому это может пригодиться?

Разработчикам небольших поддержек, которым нужен единый UI для разных каналов.
Стартапам, использующим MAX или VK в качестве клиентского канала и не желающим платить за дорогие коммерческие интеграторы.
Службам поддержки, где часть пользователей общается в мессенджерах, а часть – в веб‑чатах.

Если вы уже пользуетесь Chatwoot, добавить два новых inbox‑а почти не страшно: достаточно создать ботов в MAX и VK, задать их webhook‑URL и запустить сервис.

Что сделать, если захотите повторить

Зарегистрировать ботов
- В MAX – создать бота в личном кабинете, получить токен и указать webhook‑URL.
- В VK – создать сообщество, включить API сообщений и задать URL для событий.
Подготовить сервер Node.js
- Установить express, axios (для запросов к Chatwoot) и любой лёгкий драйвер БД.
- Реализовать два роутера (/webhook/max, /webhook/vk) согласно схеме выше.
Настроить Chatwoot
- Создать отдельный inbox для каждого канала (MAX, VK).
- Включить веб‑хуки message_created и направить их на ваш сервис (/webhook/chatwoot).
Тестировать
- Отправить сообщение из MAX и убедиться, что оно появилось в Chatwoot.
- Ответить в интерфейсе Chatwoot и проверить доставку обратно в MAX.
- Повторить с VK, проверяя работу с изображениями.
Добавить надёжность (по желанию)
- Внедрить очередь (Bull, RabbitMQ) для асинхронной обработки.
- Перейти на PostgreSQL с репликацией.
- Настроить мониторинг (Prometheus + Grafana) и алертинг на ошибки API.

Чего ожидать в дальнейшем

Пока что мост работает как «прототип», но уже решает главную задачу – собрать запросы из MAX и VK в одной системе. При росте нагрузки появятся новые требования: масштабирование, более гибкая маршрутизация (например, разные команды в VK могут попадать в отдельные отделы), и, конечно, отказоустойчивость.

Если вы планируете использовать такой подход в продакшене, готовьтесь к постепенному «заправлению» сервиса дополнительными слоями: очередь, кэш, репликация БД, а также проверку безопасности (подпись запросов, ограничение IP).

В итоге получаете удобный «единоручный» интерфейс, где агент видит всё, а клиент общается в привычном мессенджере. Это экономит время, снижает риск «потерянных» сообщений и делает поддержку чуть менее «потерянной в облаке».

Источник: Как я подключил MAX и VK к Chatwoot: разбираем двусторонний мост