MAX · Bot API · FAQ · эскалация

Как собрать ИИ-чат-бота в мессенджере MAX:Bot API, база знаний и эскалация

Q: Где документация Max Bot API?

Ориентир: документация на `dev.max.ru/docs-api` — методы, Authorization, подписки, лимиты. Для создания бота и модерации — раздел create на том же домене документации.

От модерации на business.max.ru до ответов по FAQ и передачи лида менеджеру — без хаоса в токенах и без «галлюцинаций» цен

Собрать бота с командой

Мессенджер MAX уже стал рабочим каналом заявок и поддержки. Ниже — практический маршрут: от верификации на business.max.ru и модерации бота до Bot API, ответов по базе знаний и передачи диалога менеджеру без выдуманных цен.

Коротко. Кнопки закрывают типовые ветки. Свободный текст — нет. Для поддержки и входящих заявок нужен слой, который понимает вопрос и отвечает по вашим документам, а не «из головы».

max-bot-pipeline — zsh

$ verify --profile business.max.ru
# модерация ≤ 48 раб.ч · токен в Authorization

$ connect webhook platform-api2.max.ru
# HTTPS · 200 < 30s · LLM в очередь

$ route msg --rag faq --escalate low_conf
# ответ клиенту ИЛИ лид → менеджер

Где сценарий с кнопками ломается на живом вопросе клиента

Клиент пишет в чат: «А если оплачу сегодня картой юрлица — доставка та же?» Кнопок «Цены / Доставка / Оператор» мало. Сценарный чат-бот либо уводит в меню заново, либо отвечает мимо. В мессенджере MAX такой сбой особенно больно бьёт по доверию: человек уже в диалоге и ждёт нормальный ответ, а не квест.

Чат-боты для бизнеса часто обещают «автоматизацию 24/7», а на деле дают только меню. ИИ-слой меняет задачу: бот читает вопрос, ищет ответ в вашей базе знаний и либо отвечает, либо зовёт менеджера. Так вы не теряете лид на фразе «я не понял». База знаний здесь — это ваши FAQ, прайс, оферта и регламенты в виде коротких фрагментов, по которым бот ищет ответ. Не «вся Википедия», а только то, что вы разрешили.

Кнопки

Типовые ветки и статус заказа. Ломаются на свободном тексте.

ИИ + FAQ/RAG

Ответ по вашим документам или эскалация — без «ответа из головы».

Handoff

Менеджер получает контекст, тег причины и SLA — лид не остывает.

Кому хватит FAQ-кнопок, а кому нужен ИИ с базой знаний

Не каждому проекту нужен ИИ с первого дня. Сначала честно ответьте: клиент кликает по готовым пунктам или пишет своими словами?

Хватит кнопок и коротких сценариев, если:

вопросы повторяются слово в слово («режим работы», «адрес», «статус заказа по номеру»);
вы готовы обновлять ветки вручную при каждом изменении прайса;
риск «придумать скидку» недопустим, а объём диалогов небольшой.

Нужен ИИ с базой знаний, если:

клиент формулирует запрос как попало («а это дороже, чем у вас в сторис?»);
в поддержке много однотипных, но по-разному написанных вопросов;
вы хотите собирать лиды в MAX и не рвать диалог на каждом третьем сообщении.

Как создать ИИ-бота в MAX по смыслу: сначала карточка бота и API, потом слой «поиск по FAQ + ответ модели + правила эскалации». Без второго слоя у вас будет обычный бот с меню, даже если в названии написано «AI».

Сценарный бот vs агент с tools

Сценарный бот — это схема «если нажал А → покажи Б». Он предсказуем и дёшев в сопровождении. ИИ-агент — это бот, который не только отвечает текстом, но и может вызывать инструменты: проверить статус заказа, создать заявку, передать диалог в CRM.

Маркер: простыми словами. Tools (инструменты) — заранее разрешённые действия бота: «создать лид», «найти заказ», «позвать менеджера». Без списка tools модель может только болтать; с tools — менять данные в ваших системах, поэтому без правил опасно.

Практичное правило выбора:

справка и FAQ → сценарий или простой ИИ без tools;
входящие заявки и поддержка с передачей в CRM → ИИ + база знаний + эскалация;
смена заказа, возврат денег, правка ПДн → только человек или жёсткий HITL.

Где обязателен человек в контуре (HITL)

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

Маркер: простыми словами. HITL (human-in-the-loop) — правило «человек в контуре»: бот не завершает рискованный шаг сам, а передаёт диалог менеджеру или ждёт подтверждения.

Минимум политики HITL для MAX-бота:

Кнопка «Связаться с оператором» всегда на виду.
Автоэскалация при низкой уверенности ответа.
Запрет отвечать на цену/гарантию/возврат без цитаты из базы.
Стоп-слова: «верните деньги», «жалоба», «суд», «персональные данные удалить».

Карта пайплайна · не hero

Сообщение → FAQ/RAG → уверенность → ответ или менеджер

ИИ-слой в MAX не «угадывает прайс». Сначала поиск по вашей базе, потом ответ строго по найденному — и развилка: высокая уверенность закрывает диалог, низкая передаёт лид человеку с контекстом.

Входящее: клиент пишет в MAX — webhook принимает событие.
RAG по FAQ: только карточки базы, без «воды» из общих знаний модели.
Confidence: порог решает — ответить или эскалировать.
HITL: цена, возврат, претензия, ПДн — сразу менеджеру.

Дальше разберём цепочку ответа, пороги уверенности и handoff в CRM без потери лида.

Редакционная схема: два прохода цикла — типовой FAQ (зелёный ответ) и рискованный запрос (янтарный handoff).

Как пройти business.max.ru и не застрять на модерации

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

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

Профиль ООО / ИП / самозанятый и квоты ботов

Тип профиля	Квота ботов
Организация или ИП	5
Самозанятый	2

После создания бот уходит «на модерацию». Проверка — до 48 часов по рабочим дням. Пока статус модерации, настройки менять нельзя. Дальше возможны статусы «создан» или «требует исправлений». Уведомления приходят от бота «MAX для бизнеса».

Ник генерируется автоматически (для ИП/юрлиц вид idИНН_bot, для самозанятых — se(orgid)_bot). Выбрать или сменить ник сейчас нельзя. Публичная ссылка выглядит как max.ru/idИНН_bot.

Пошагово: создать карточку бота

Шаг 1. Откройте кабинет business.max.ru через верифицированный профиль (ООО, ИП или самозанятый) и раздел создания чат-бота. Ориентир по шагам — официальная инструкция create.

Шаг 2. Заполните описание: кто вы, для чего бот, какие сценарии (поддержка, заявки, FAQ). Пишите по делу — модератору должно быть понятно назначение.

Шаг 3. Отправьте на модерацию и дождитесь статуса «создан» (до 48 рабочих часов). Не пытайтесь править карточку «на модерации».

Шаг 4. После одобрения откройте расширенные настройки / интеграцию и скопируйте токен бота.

Признак успеха. В кабинете статус «создан», есть токен, открывается публичная ссылка вида max.ru/…_bot, бот отвечает на тестовое сообщение после подключения webhook или конструктора.

Типичные ошибки новичка

Ждать «мгновенной» модерации в выходные — считайте рабочие дни.
Пытаться сменить ник вручную — сейчас это не поддерживается.
Начинать ИИ-логику до токена — сначала доступ к API, потом LLM.

Где взять токен и куда его нельзя класть

Токен появляется только после успешной модерации. Он нужен и для Bot API, и для партнёрских конструкторов.

Правила безопасности токена:

храните в переменных окружения / секретнице сервера, не в публичном репозитории;
не вставляйте токен в URL и query-параметры;
не пересылайте токен в чат сотрудникам «на всякий случай»;
при утечке — немедленно перевыпустите.

В API MAX токен передаётся только в заголовке Authorization. Передача через query больше не поддерживается. Если старый гайд показывает ?access_token=… — это устаревшая схема, не копируйте её.

Bot API: webhook или long polling — что выбрать под нагрузку

Рабочий домен API сейчас — platform-api2.max.ru. Запросы нужно направлять сюда, а не на старый platform-api.max.ru, который ещё встречается в пересказах.

Маркер: простыми словами. Webhook — это когда MAX сам присылает событие (новое сообщение) на ваш HTTPS-адрес. Long polling — когда ваш сервер сам периодически спрашивает: «есть обновления?»

Официальная логика выбора:

Production — только webhook (POST /subscriptions).
Dev/тест — webhook или long polling (GET /updates).
Одновременно оба режима нельзя.
Long polling ограничен по скорости и сроку хранения событий — не для production.

С мая 2026 для webhook нужны HTTPS и сертификаты доверенных УЦ (в том числе Минцифры). HTTP и самоподписные сертификаты для вебхуков больше не подходят.

Важный лимит: ваш endpoint должен вернуть HTTP 200 за 30 секунд. Если внутри webhook вы ждёте долгий ответ LLM, MAX посчитает доставку ошибкой и будет ретраить. Практичный паттерн: в webhook быстро принять событие, ответить 200, а тяжёлый RAG/LLM отдать в очередь.

Официальные ориентиры по подготовке к Bot API — в разделе prepare и в документации API.

Лимиты запросов и получение chat_id

Лимит нагрузки на platform-api2.max.ru — около 30 запросов в секунду (rps). При превышении получите HTTP 429. На старте разумно держать запас ниже потолка и добавить backoff при 429.

Маркер: простыми словами. RPS (requests per second) — сколько запросов в секунду ваш бот шлёт в API. 30 rps — потолок платформы, не «цель на каждый день».

chat_id для чата или канала берётся только из событий подписки — например bot_added или bot_started. Метод GET /chats с июня 2026 не поддерживается. Не ищите «список всех чатов» старым способом: добавьте бота, поймайте событие, сохраните id.

Диплинки для старта диалога: https://max.ru/<bot>?start=<payload>, payload до 128 символов, событие bot_started. Клавиатура: до 210 inline-кнопок, до 30 рядов, до 7 кнопок в ряду.

Как выдать боту права админа в чате или канале

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

Практический порядок:

Добавьте бота в чат или канал.
Выдайте права администратора.
Дождитесь события добавления и сохраните chat_id.
Проверьте, что тестовое сообщение доходит до вашего webhook.

Если бот «молчит» в группе, в большинстве случаев нет админ-прав или вы не сохранили chat_id из события.

Маркер: простыми словами. chat_id — внутренний номер чата или канала для API. Без него бот не знает, куда слать сообщение. В MAX этот номер приходит из событий, а не из «списка чатов».

Цепочка ответа: входящее сообщение → база знаний → LLM → уверенность

Соберите пайплайн так, чтобы модель не фантазировала:

Пришло сообщение из MAX.
(Опционально) классификация: FAQ / продажа / жалоба / «хочу оператора».
Поиск по базе знаний (RAG) — только ваши фрагменты.
Генерация ответа строго по найденному контексту.
Оценка уверенности / покрытия базы.
Если уверенность низкая или тема рискованная — эскалация менеджеру с историей диалога.

Маркер: простыми словами. RAG — «сначала найди кусок из ваших документов, потом ответь по нему». Без RAG модель достраивает ответ из общих знаний и легко выдумывает цены и сроки.

В реальных кейсах поддержки около 90% обращений — типовые: цены, оплата, доставка, тарифы. Именно их выгодно закрывать ИИ. Сложные и нетиповые — сразу человеку. Так вы режете нагрузку на операторов, не обещая «полностью заменить отдел».

Как собрать FAQ, чтобы RAG не тащил «воду»

Плохая база: длинные PDF «как есть», дубли, устаревшие акции, маркетинговые абзацы без фактов. Хорошая база: короткие карточки с одним фактом.

Шаблон карточки FAQ:

Вопрос клиента (как его реально пишут).
Короткий ответ (1–5 предложений).
Жёсткие цифры (цена, срок, условия) — только актуальные.
Дата актуальности и владелец правки.
Тег эскалации (если тема опасная — «только менеджер»).

Перед запуском задайте себе пять вопросов к данным:

Есть ли в базе ответ на топ-20 реальных вопросов из переписки?
Нет ли двух разных цен на один товар?
Удалены ли акции с истёкшим сроком?
Помечены ли темы, где боту молчать обязательно?
Кто обновляет базу после смены прайса — и за сколько часов?

Когда бот обязан замолчать и позвать менеджера

Маркер: простыми словами. Confidence (уверенность) — внутренняя оценка: «насколько найденный фрагмент базы реально отвечает на вопрос». Низкая уверенность = лучше передать человеку, чем угадать.

Эскалация обязательна, если:

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

Формулировка бота при эскалации должна быть честной: «Передаю менеджеру — он ответит с учётом вашей ситуации», а не «сейчас всё решу сам».

Как передать диалог менеджеру и не потерять лид

Эскалация — не «бот сломался», а штатный этап воронки. Плохой handoff: клиент пишет в пустоту, менеджер не видит контекст, лид остывает. Хороший: в CRM уже есть имя и телефон (если даны), суть вопроса, что уже ответил бот, и таймер ответа.

Правила handoff: тег, контекст, SLA ответа

Минимальный пакет передачи:

тег причины: low_confidence / price_dispute / want_human / refund;
последние N реплик диалога;
найденные (или не найденные) фрагменты базы;
контакт и источник (диплинк, реклама, органика);
SLA: кто отвечает и за какое время (например, 15 минут в рабочее окно).

Сообщите клиенту ожидаемое время. Молчание после «передаю оператору» убивает конверсию сильнее, чем средний ответ бота.

Связка с CRM без «чёрного ящика»

Не обязательно тащить тяжёлую платформу «ради галочки». Нужен прозрачный контур:

Событие эскалации создаёт задачу или сделку.
Менеджер видит историю в одном месте.
Ответ менеджера (или статус) можно вернуть в тот же чат MAX.
Логи хранятся с контролем доступа — особенно если есть телефон и имя.

Маркер: простыми словами. ПДн — персональные данные: имя, телефон, адрес, переписка, по которой человека можно опознать. Не складывайте сырые логи с телефонами в открытые таблицы и не гоните их в сторонние LLM без договора и маскирования.

Если бот запрашивает контакт через API, заранее продумайте согласие, срок хранения и кто имеет доступ. Для МСП безопасность данных — один из главных барьеров к ИИ; закройте этот страх процессом, а не слоганом.

Конструктор или свой сервер: где платите временем, где — деньгами

Три рабочих пути:

Путь	Когда брать	Чем платите	Риск
Конструктор сценариев / no-code	Кнопки, FAQ, простые ветки	Подписка и время на схему	Ломается на свободном тексте
Гибрид: сценарий + эскалация	Малый поток, нужен оператор	Настройка + дисциплина SLA	ИИ «для галочки» без базы
Свой сервер + Bot API + LLM/RAG	Входящие заявки, поддержка, контроль качества	Разработка и токены LLM	Сложнее старт, нужен HITL

В реестре партнёров MAX фигурируют десятки конструкторов (SaleBot, Aimylogic, Botmother, Just AI, BotHelp и др.). Типовой алгоритм no-code: создали бота и токен в business.max.ru → подключили канал MAX в конструкторе → собрали сценарий. Это нормальный старт, если вам не нужна сложная логика уверенности и бюджета токенов.

Свой сервер имеет смысл, когда вы хотите:

жёсткий RAG «только из найденных фрагментов»;
очередь под лимит webhook 30 секунд;
свои метрики confidence и стоимости диалога;
контроль, какие tools разрешены агенту.

Не смешивайте цели. Если задача — выдать справку, хватит сценария. Если бот стоит на входящих заявках и свободном тексте — нужен ИИ-слой с правилами эскалации.

Тесты, которые ловят враньё по цене и оферте

Галлюцинация цены — самая дорогая ошибка бизнес-бота. Клиент получает выдуманную скидку, менеджер потом «отказывается», репутация падает.

Соберите пакет из 50–100 тест-кейсов до рекламного трафика. В каждый кейс: вопрос клиента → ожидаемый источник в базе → допустимый ответ → «должен эскалировать? да/нет».

Чек-лист промптов и запретных тем

В системных правилах бота зафиксируйте:

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

Прогоните «враждебные» вопросы:

«Сделайте как в прошлом месяце минус 30%»;
«А на сайте у конкурента дешевле — вы же тоже так можете?»;
«Гарантируете результат за 3 дня?»;
«Удалите все мои данные прямо сейчас в чате».

Если бот уверенно отвечает без опоры на карточку FAQ — это баг релиза, не «особенность ИИ».

Бюджет токенов LLM: где раздувается счёт

В кейсах автоматизации поддержки значимая доля затрат уходит на LLM и инфраструктуру (порядка половины бюджета сервиса в публичных разборах). Считайте экономику просто:

стоимость диалога ≈ токены × длина переписки × число диалогов + инфраструктура

Где обычно раздувается счёт:

в контекст пихают весь FAQ целиком вместо 2–5 релевантных кусков;
хранят бесконечную историю чата в каждом запросе;
нет классификации: дорогая модель на любой «привет»;
ретраи из‑за таймаута webhook (LLM внутри 30 секунд) множат вызовы.

Держите дешёвую модель на классификации и маршрутизации, более сильную — на сложных ответах. Биллинг смотрите по диалогам, а не «в среднем за месяц непонятно за что».

Ошибки, из‑за которых бот «молчит» или сливает токен

Токен в URL/query. Сейчас нужен заголовок Authorization. Старые примеры с query ломают интеграцию и повышают риск утечки в логах.
Неверный домен API. Канон — platform-api2.max.ru.
Long polling в production. Для боя — webhook + HTTPS.
LLM внутри HTTP-handler webhook. Не уложились в 30 секунд → ретраи, дубли ответов, лишний расход.
Нет админ-прав / нет chat_id из события. Бот добавлен «для вида», события группы не обрабатываются.
Нет HITL. Бот сам обещает возврат денег или меняет условия оферты.
Раздутый контекст RAG. В промпт летит вся база — растёт счёт и падает точность.
Устаревший прайс в базе. Даже идеальный RAG будет «уверенно» врать, если документ протух.

Исправление почти всегда одно: вернуть официальный маршрут (токен, api2, webhook), сузить базу, включить эскалацию.

Частые вопросы про бота в MAX

Можно ли создать чат-бота в мессенджере MAX бесплатно?

Создание карточки бота через верифицированный профиль доступно в рамках квот платформы. Отдельно вы платите за конструктор (если берёте), хостинг своего сервера и токены LLM. «Бесплатно навсегда с ИИ» обычно значит «пока маленький тест».

Как создать чат-бот в MAX физлицу?

Нужен подходящий тип профиля на платформе. Самозанятый резидент РФ по официальной таблице может создать до 2 ботов; ООО/ИП — до 5. Обычный «просто аккаунт без верификации бизнеса» для боевого Bot API не используйте как основной путь.

Где документация Max Bot API?

Ориентир: документация на dev.max.ru/docs-api — методы, Authorization, подписки, лимиты. Для создания бота и модерации — раздел create на том же домене документации.

Webhook или long polling — что выбрать?

Для production только webhook. Long polling — для отладки.

Нужен ли ИИ, если есть конструктор?

Если хватает кнопок и жёстких веток — нет. Если клиент пишет свободным текстом и вы теряете заявки — нужен слой FAQ/RAG и эскалация.

Что делать, если бот выдумал цену?

Срочно отключить автоответы по прайсу, починить базу, добавить запрет отвечать без найденного фрагмента, прогнать тест-кейсы, вернуть диалоги менеджеру.

Как не потерять лид при эскалации?

Передавайте в CRM причину, историю и контакт; обещайте клиенту SLA; не оставляйте чат без статуса.

Чек-лист запуска: от профиля до первого эскалированного диалога

Пройдите список сверху вниз и отмечайте только факты, не «почти готово».

Профиль на business.max.ru верифицирован (ООО / ИП / самозанятый), квота не превышена.
Бот создан, модерация пройдена (до 48 рабочих часов), статус «создан».
Токен сохранён в секретах, в коде только через Authorization.
API бьётся в platform-api2.max.ru.
Для боя настроен webhook на HTTPS; long polling выключен.
Endpoint отвечает 200 быстрее 30 секунд; LLM вынесен в очередь.
Бот добавлен куда нужно; для групп и каналов — права админа; chat_id сохранён из события.
FAQ собран карточками; устаревшие цены вычищены.
Цепочка RAG → ответ → confidence → эскалация работает на тестах.
Есть кнопка «оператор» и автоэскалация на риск-темы.
Handoff пишет задачу в CRM или таблицу с контекстом и SLA.
Прогнаны 50+ тест-кейсы на цены и оферту; бюджет токенов ограничен и измеряется.

Измеримый результат первого запуска. Не «бот существует», а: 20–50 реальных диалогов, доля автоответов по FAQ, доля эскалаций, ноль инцидентов с выдуманной ценой, среднее время ответа менеджера после handoff.

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

Что проверяли по источникам

Официальная документация MAX: создание бота, квоты, модерация, Bot API, webhook и long polling, Authorization, chat_id.
Практические разборы автоматизации поддержки с LLM: бюджет токенов, доля типовых вопросов, эскалация.
Сравнение путей «конструктор / свой сервер» по открытым гайдам без устаревших советов про query-токен и «бот без верификации».