Клиенты не читают почту. Ну, читают — но когда удобно. Письмо со сметой уходит в папку, тонет среди рассылок, и менеджер потом звонит: «Вы получили наш файл?»
Мы сделали иначе. Теперь смета приходит в MAX — мессенджер от VK, который активно набирает аудиторию в B2B. Как сообщение с файлом, прямо в чат. Клиент видит уведомление моментально.
Рассказываю, как это устроено изнутри — и где мы потеряли время на неочевидных вещах, которых нет в документации.
Что за сервис и зачем это вообще нужно
У нас веб-сервис для составления и отправки смет. Раньше схема была простая: PDF во вложении, тема письма, текст — и отправить. Работало. Но «фоновая» почта у клиентов — это реальная проблема: проверяют раз в день, письмо теряется.
MAX показался логичным шагом с учетом блокировок. Мессенджер, уведомления в реальном времени, привычный интерфейс «написал — получил». Решили попробовать.
Шаг 1. Создаём бота
Бот регистрируется на business.max.ru. После регистрации получаешь два главных артефакта:
• Токен — секретный ключ для вызова API
• Имя пользователя бота — нужно для формирования ссылок
Токен мы добавили в переменные окружения сервера. Если токена нет — все функции MAX просто не показываются в интерфейсе. Никаких ошибок, просто тихо отключено. Удобно для раскатки по окружениям.
Шаг 2. Главная задача — понять, кому слать сообщение
Это оказалось нетривиально. У каждого пользователя MAX есть внутренний числовой ID. Его невозможно узнать заранее — только когда клиент сам напишет боту.
Решение — диплинк с payload. Для каждого клиента формируем уникальную ссылку вида: https://max.ru/имя_бота?start=client_12345
Мастер копирует ссылку и отправляет клиенту любым способом — SMS, WhatsApp, почта. Клиент нажимает, попадает в чат с ботом, жмёт «Начать».
В этот момент MAX отправляет на наш сервер вебхук с событием bot_started. В теле — числовой ID пользователя MAX и тот самый payload. Сервер парсит ID клиента, сохраняет в базу: «клиент №12345 → MAX user 63083371».
Связь установлена. Теперь мы знаем, куда слать.
Шаг 3. Подписываемся на вебхуки
Чтобы MAX присылал события, нужно один раз зарегистрировать URL сервера через один POST-запрос на https://platform-api.max.ru/subscriptions.
Здесь первая неочевидная вещь. В документации написано использовать Bearer TOKEN в заголовке Authorization. На практике MAX принимает токен без префикса Bearer. Просто голый токен. С Bearer — ошибка verify.token и никаких подсказок почему.
Шаг 4. Отправляем смету
Когда мастер нажимает «Отправить в MAX», на сервере запускается асинхронная задача. Вот что она делает по шагам.
• Скачивает PDF из облачного хранилища.
• Загружает файл в MAX. И вот тут второй подводный камень. Документация описывает загрузку как PUT-запрос с бинарными данными. На деле сервер MAX принимает только multipart/form-data с полем file. Выяснили по логам.
• Ждёт обработки. После загрузки файл не сразу готов — MAX обрабатывает его асинхронно. Если сразу отправить сообщение, придёт ошибка attachment.not.ready. Решение: 5 попыток с нарастающей паузой — 2, 4, 6, 8, 10 секунд.
• Отправляет сообщение с текстом и прикреплённым файлом.
Что получилось в интерфейсе
В карточке клиента появился блок «MAX мессенджер»:
• Не подключён → кнопка «Подключить», при нажатии показывается диплинк с кнопкой «Скопировать»
• Подключён → зелёный статус и кнопка «Отвязать»
В редакторе сметы появилась вторая кнопка рядом с «Отправить на почту». Кнопка «Отправить в MAX» видна только если у клиента уже установлена связь с ботом — никаких лишних элементов.
Три грабли, которых нет в документации
Итого по неочевидным моментам, которые стоили нам времени на отладку:
Интеграция заняла около двух дней с учётом отладки. Результат: клиент получает смету прямо в мессенджер с PDF-файлом, мастер видит статус отправки в интерфейсе. Почтовый канал остался как резервный.
Если будете делать что-то похожее с MAX — надеюсь, этот разбор сэкономит вам пару часов.
Подписывайтесь на мой Telegram канал: https://t.me/codeandchay
Строю свой стартап прямо в эфире.
Инструменты, ошибки, размышления без лишнего тех слэнга.