Интеграция с MAX: два пути данных

Короткий ответ: «интеграция с MAX» — это не одна связка, а две разные, и путать их дороже всего. Путь бота опирается на документированный платформой интерфейс: организация получает токен в веб-кабинете «MAX для партнёров» после верификации профиля и модерации, а формат событий и отправки MAX публикует — есть с чем сверяться и на что ссылаться. Путь личного аккаунта такого основания не имеет: официального API или протокола для личных аккаунтов MAX в документации `dev.max.ru` не существует, вся публичная часть посвящена ботам. Значит, канал «MAX личный» опирается на недокументированное поведение, и официальной интеграцией с MAX называть его нельзя.

Важная оговорка, чтобы это различие не прочиталось шире, чем оно есть: речь о том, что платформа документирует, а не о том, как ходят наши данные. Оба MAX-канала попадают в LTVchat через внешний шлюз, ни один не идёт из нашего бэкенда напрямую в API платформы. Документированность интерфейса бота означает предсказуемость его поведения и наличие публичного описания — а не прямую связь с MAX.

Второй короткий ответ, чтобы не тратить ваше время: двусторонних интеграций с внешними CRM у LTVchat нет — ни с amoCRM, ни с Битрикс24, ни с другими, и публичного клиентского API мы не заявляем. Если задача звучит как «пусть переписка из MAX сама попадает в нашу CRM», это дисквалифицирующий критерий, и его лучше проверить первым. Что здесь действительно есть: одна лента переписки на пять видов подключений, роли с серверной проверкой, изоляция рабочего пространства, журнал действий, объединение диалогов одного клиента и импорт истории для личных каналов. Цена — 300 ₽/канал в месяц + 50 ₽/сотрудник в месяц, устройство доступа — на странице безопасности, окно — в демо.

Способы подключения

Каждая строка правой колонки — это оговорка, и её надо прочитать словами.

Токен для бота формируется только после успешной проверки и лежит в расширенных настройках бота на платформе. Он равен прямому доступу к боту: держать его в открытых источниках нельзя, при компрометации — обновлять, а за нарушение правил платформы он может быть отозван. Сама процедура получения бота доступна только юрлицам, ИП и самозанятым — резидентам РФ и включает модерацию до 48 часов по рабочим дням; разбор целиком — на странице про MAX для бизнеса.

Личный канал держится на активной сессии, и главная практическая опасность здесь не в самом разрыве, а в том, как разрыв выглядит снаружи: разлогиненный канал не подаёт признаков аварии, он просто перестаёт приносить сообщения — со стороны это неотличимо от тишины со стороны клиентов. Отсюда требование к процессу: состояние подключённых каналов кто-то должен проверять по расписанию, а не по факту жалобы.

Требования платформы к приёму событий

Эту часть стоит знать даже если вы не будете писать код: она объясняет, почему подключение нельзя сделать «на коленке» и почему требования к инфраструктуре реальные.

• Вебхук — рекомендованный способ. Подписка задаётся адресом, списком типов событий и секретом; в примерах документации это события создания сообщения и начала общения с ботом.
• Только HTTPS. С 25 мая поддержка вебхуков по HTTP и самоподписанных сертификатов прекращена: нужен сертификат доверенного центра, в том числе Минцифры.
• Long polling для production непригоден. Так написано в документации прямо: он ограничен по скорости и сроку хранения событий, и рекомендация — вебхук на всех этапах работы.
• Домен API — `platform-api2.max.ru`, и документация просит использовать именно его. Сертификат Минцифры требуется добавить в список доверенных.
• Авторизация — заголовком. Передача токена через параметры запроса больше не поддерживается.
• Лимиты. Не более 30 запросов в секунду на домен и не более двух сообщений в секунду в один диалог, групповой чат или канал; при превышении отправку надо ставить в очередь или задерживать.

Полный список типов событий платформа публикует: добавление и удаление бота, начало и остановка общения с ботом, удаление диалога, создание, изменение и удаление сообщения, нажатие кнопки, изменение названия чата, добавление и удаление участников и несколько событий про диалог. Практически значимы два: начало общения с ботом и создание сообщения. Первое важнее, чем кажется из названия: до этого события идентификатора получателя у бота нет, и отправлять физически некуда. Иного способа его получить документация MAX не описывает — отсюда и строка «начать диалог из окна: нельзя» в таблице выше, и невозможность рассылки по вашей базе через бота.

Порядок подключения

1. Определите, какой путь вам нужен. Точка входа, принадлежащая компании, — путь бота. Накопленная переписка и исходящие контакты — путь личного аккаунта. Часто нужны оба.
2. Получите бота на платформе. Регистрация в веб-кабинете, верификация профиля руководителем или подписантом, карточка бота, модерация, токен после успешной проверки.
3. Подключите канал в LTVchat. Оба вида MAX-каналов присутствуют в каталоге подключений как отдельные слоты; каждый канал хранит собственные реквизиты подключения к шлюзу.
4. Проверьте приём. Напишите боту с посторонней учётной записи и убедитесь, что сообщение появилось в ленте. Это и есть проверка того, что события доходят.
5. Проверьте отправку и медиа. Ответьте текстом, отправьте фото, голосовое и файл. Отправка идёт общим путём шлюза, одинаковым для всех видов каналов, без ветвлений по провайдеру.
6. Решите вопрос истории заранее. Полный импорт истории работает только для личных каналов и только при явно включённой настройке загрузки истории; это отдельный запускаемый процесс. У бот-канала импорта истории нет вовсе — переписка там начинается со дня подключения.
7. Заведите привычку проверять состояние каналов. Раз в день или раз в неделю — зависит от потока. Разлогиненный личный канал снаружи выглядит как тишина.

Чек-лист интеграции

• решено, какой из двух путей закрывает вашу задачу, и понятно, почему не второй
• токен бота хранится как пароль, а не в переписке и не в общем документе
• известно, кто в компании имеет доступ к платформе «MAX для партнёров»
• есть человек, отвечающий за проверку состояния подключённых каналов
• известно, что разлогиненный личный канал выглядит снаружи как отсутствие обращений
• решено, где хранится переписка и что вы сможете из неё забрать
• проверено, что двусторонняя связь с вашей внешней CRM в требованиях не значится
• посчитан бюджет на подключения и людей

Разбор того, что происходит с историей при переездах и разрывах, — в тексте про сохранение истории общения. Проверка собственного состояния — аудит из десяти вопросов.

Ограничения

Ограничения платформы. Списка чатов бота API не отдаёт: метод получения списка групповых чатов и каналов не поддерживается с июня 2026 года, и документация прямо перекладывает сбор идентификаторов на разработчика — включая обработку повторных событий и удаление записи при удалении бота. Историю сообщений по идентификатору чата бот получает только там, где он администратор чата. Адресация двойная и взаимоисключающая: сообщение отправляется либо пользователю, либо в чат или канал, это разные пространства идентификаторов, и передать оба сразу нельзя. Медиа загружается двухшагово: сначала загрузка и получение токена, потом отправка с этим токеном; слишком быстрая отправка возвращает ошибку неготовности вложения, и документация советует делать паузу, повторять с увеличивающимся интервалом и переиспользовать токен для часто используемых файлов. Комбинации вложений ограничены: не больше двенадцати вложений на сообщение, файл можно приложить только вместе с вложением с кнопками — вместе с фото или видео нельзя, и не больше одного файла на сообщение.

Чего нет в LTVchat. Интеграций с внешними CRM. Публичного клиентского API. Воронки и стадий сделки, тегов и произвольных полей клиента. Автоматического распределения обращений и назначения ответственного за диалог. Поиска по словам внутри сообщений — диалог открывается через клиента. Нет шаблонов быстрых ответов, отложенной отправки и авторассылок. Нет сквозной аналитики. Мобильного приложения.

Ограничения работы через шлюз. Оба MAX-канала идут через внешний шлюз, а не напрямую в API платформы из нашего бэкенда. Отправка выполняется только когда канал включён и его реквизиты действительны. Для канала «MAX личный» в бэкенде есть отдельный обходной путь на ошибку шлюза, режущий выборку до тридцати сообщений: это единственный вид канала во всём коде с такой особенностью, и приравнивать его по устойчивости к личному Telegram нельзя. Мгновенную и безусловную доставку мы не обещаем.

Что остаётся работой компании. Дисциплина хранения токена, регулярная проверка состояния каналов, решение о том, где живёт клиентская база. Правовая часть — вопрос к юристу по вашим документам; общий разбор границы — в тексте про 152-ФЗ. Ни сертификаций, ни аттестаций, ни внешних аудитов у сервиса не имеется.

Как считать бюджет

300 ₽/канал в месяц + 50 ₽/сотрудник в месяц, владельцы подключённых каналов не оплачиваются как сотрудники.

• один MAX-канал и четыре сотрудника: 300 ₽ + 200 ₽ = 500 ₽ в месяц
• два MAX-канала, Telegram-бот и девять сотрудников: 900 ₽ + 450 ₽ = 1 350 ₽ в месяц

Расчёт целиком — на странице тарифов.

Что делать дальше

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

Как MAX и Telegram работают рядом и в чём между ними нет симметрии — в отдельном разборе. Где хранить собранную переписку — обзор мест хранения.