Руководство пользователя: робот и активити «Макс»

Приложение «Уведомление через Макс» добавляет в Битрикс24 действие, которое отправляет сообщение в чат или пользователю через бота Макс.

Одно и то же действие доступно в двух местах:

Где использовать	Название в интерфейсе	Когда выбирать
Роботы CRM (сделки, лиды, контакты и т.д.)	Отправить сообщение через бота Макс	Автоматизация карточек CRM
Бизнес-процессы	Отправить сообщение через бота Макс	Шаблоны БП в дизайнере

Параметры и результат у робота и активити одинаковые.

---

Что нужно заранее

1. Приложение установлено на вашем портале Битрикс24.
2. Есть токен бота Макс (см. ниже).
3. Известен CHAT ID — ID чата или пользователя, куда отправлять сообщения (см. ниже).

Токен и CHAT ID указываются в полях робота/активити. Токен храните как секрет: его нельзя публиковать и передавать посторонним.

---

Где взять токен бота Макс

Токен выдаётся при создании бота и нужен для отправки сообщений от его имени. Без токена робот и активити работать не будут.

Способ 1. Платформа MAX для партнёров (основной)

1. Войдите на платформу MAX для партнёров (нужен верифицированный профиль организации, ИП или самозанятого — резидента РФ).
2. Создайте бота, если его ещё нет (раздел Чат-боты).
3. Откройте список ботов → выберите нужного бота.
4. Нажмите ⋮ (три точки) → Настройки.
5. Скопируйте токен: справа от поля с токеном нажмите значок копирования.

Подробнее: документация API MAX — авторизация.

Способ 2. Мини-приложение или бот «MAX для бизнеса»

Если бот создан в мини-приложении «MAX для бизнеса» после верификации профиля:

• токен можно скопировать там же в настройках бота;
• либо открыть бота «MAX для бизнеса» в мессенджере и выполнить команду «Получить токен».

Важно про токен

• Вставляйте токен в поле «Токен бота Макс» целиком, без пробелов в начале и конце.
• Не публикуйте токен в открытых чатах, тикетах и скриншотах.
• Если токен скомпрометирован или отозван, получите новый в настройках бота и обновите значение в роботе/активити.

---

Где взять CHAT ID

В поле «ID чата или пользователя» указывается числовой идентификатор получателя в Макс. От него зависит, куда уйдёт сообщение.

Личный диалог и группа — разные ID

Куда отправляем	Как выглядит CHAT ID	Пример
Личный диалог с пользователем	Обычно положительное число	1234567890
Групповой чат или канал	Число с минусом в начале (-…)	-76170460923914

Обязательно: для группы (и часто для канала) CHAT ID нужно указывать вместе с минусом в начале.

Примеры правильного и неправильного заполнения для группы:

	Значение в поле
Верно	-76170460923914
Неверно	76170460923914 (без -)

Если убрать минус, API Макс не найдёт нужный чат — сообщение в группу не уйдёт.

Минус — это часть идентификатора, а не «ошибка» или «знак минус». Копируйте ID как есть, включая -.

Как узнать CHAT ID

Официально идентификатор приходит в событиях бота (после подписки на обновления). Метод «получить список всех чатов» больше не используется — ID нужно сохранить из события.

Для группового чата или канала

1. Добавьте бота в нужную группу (или канал) как участника.
2. Убедитесь, что бот может писать в этот чат (права участника/администратора — по правилам вашей группы).
3. Получите событие добавления бота (bot_added) через Webhook или Long Polling — в событии будет поле chat_id.
4. Скопируйте значение chat_id вместе с минусом, если он есть.
5. Вставьте его в поле «ID чата или пользователя» в роботе или активити.

Если бота уже добавили раньше, удалите и добавьте снова (или дождитесь другого события по этому чату), чтобы снова увидеть chat_id в обновлениях.

Подробнее в документации MAX: получение списка чатов через подписки, отправка сообщений.

Для личного диалога с пользователем

1. Пользователь должен начать диалог с ботом (открыть бота и нажать старт / написать сообщение).
2. В событии bot_started (или в сообщении пользователя) придёт chat_id / идентификатор пользователя.
3. Этот ID обычно без минуса — его и указывайте в поле.

Альтернатива для личных сообщений по API: параметр user_id. В нашем роботе/активити используется одно поле «ID чата или пользователя» — для диалога сюда подходит ID из события запуска бота.

Краткая шпаргалка по CHAT ID

1. Группа → ID с - в начале (например -76170460923914).
2. Личка → обычно без минуса.
3. Бот должен быть участником чата (для группы) или пользователь должен запустить бота (для лички).
4. Не округляйте и не сокращайте число — копируйте полностью.

---

Часть 1. Настройка робота в CRM

1. Откройте роботов

1. Откройте нужный раздел CRM (например, Сделки).
2. Перейдите в Автоматизация → Роботы (или Настройки → Роботы, в зависимости от интерфейса портала).
3. Выберите воронку и стадию, на которой должно срабатывать уведомление.

2. Добавьте робота

1. На нужной стадии нажмите Добавить / +.
2. В списке роботов найдите приложение «Отправить сообщение через бота Макс» (группа роботов приложений).
3. Добавьте робота на стадию.

3. Заполните параметры

Поле	Обязательно	Что указать
Токен бота Макс	да	Токен бота (см. Где взять токен)
ID чата или пользователя	да	CHAT ID получателя. Для группы — обязательно с минусом в начале (см. Где взять CHAT ID)
Текст сообщения	да	Текст уведомления. Можно вставлять поля документа через кнопку Вставка (название сделки, ответственный и т.д.)
Тип сообщения	нет	Формат текста: Обычный текст (по умолчанию), Markdown или HTML
Вложение (файл)	нет	Файл из поля карточки CRM (тип «Файл») — через Вставка
Вложение (ссылка)	нет	Прямая ссылка на файл (http:// или https://)

Рекомендации:

• Заполняйте только одно поле вложения. Если указаны оба, приоритет у «Вложение (файл)».
• Для файла из сделки: Вложение (файл) → Вставка → выберите файловое поле сделки.
• Для файла по внешней ссылке: используйте Вложение (ссылка).

4. Сохраните и проверьте

1. Сохраните настройки робота.
2. Создайте или переведите тестовую сделку на нужную стадию.
3. Убедитесь, что сообщение пришло в Макс.
4. При ошибке откройте журнал выполнения робота — там будут сообщения вроде «Отправка сообщения в Макс…», «Сообщение отправлено в Макс» или текст ошибки.

---

Часть 2. Настройка активити в бизнес-процессе

1. Откройте дизайнер БП

1. Перейдите в Автоматизация → Бизнес-процессы (или в настройки нужного раздела).
2. Откройте шаблон бизнес-процесса в дизайнере.

2. Добавьте активити

1. В списке действий найдите «Отправить сообщение через бота Макс» (действия приложений).
2. Перетащите действие на схему процесса в нужное место.

3. Заполните параметры

Параметры те же, что у робота (см. таблицу выше):

• Токен бота Макс
• ID чата или пользователя
• Текст сообщения
• Тип сообщения
• Вложение (файл) / Вложение (ссылка)

В тексте и в полях можно использовать значения полей документа и переменные БП через кнопку вставки.

4. Используйте результат (по желанию)

После выполнения активити в процесс возвращаются значения:

Параметр	Значение
Успешно (success)	Да (Y) — сообщение отправлено; Нет (N) — ошибка
ID сообщения в Макс (message_id)	Идентификатор отправленного сообщения (если отправка успешна)

Их можно:

• сохранить в переменную БП;
• проверить условием («Если успешно = Нет — уведомить администратора»);
• записать в поле документа.

5. Сохраните шаблон

Опубликуйте / сохраните бизнес-процесс и запустите тестовый экземпляр.

---

Примеры текста сообщения

Обычный текст:

Новая сделка: {=Document:TITLE}
Ответственный: {=Document:ASSIGNED_BY_PRINTABLE}

(конкретные коды полей зависят от сущности — удобнее вставлять через кнопку «Вставка» в конструкторе.)

Markdown (тип сообщения = Markdown):

**Новая сделка**
Сумма: 150 000 ₽

HTML (тип сообщения = HTML):

<b>Новая сделка</b><br>
Статус изменён

---

Вложения

Сценарий	Какое поле использовать
Файл лежит в поле сделки / лида (тип «Файл»)	Вложение (файл) + Вставка этого поля
Файл доступен по прямой ссылке	Вложение (ссылка) — URL вида https://...
Вложение не нужно	Оставьте оба поля пустыми

Тип вложения для Макс (image, file, video, audio) определяется автоматически по файлу — отдельно указывать его не нужно.

---

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

Робота / активити нет в списке

• Убедитесь, что приложение установлено на портале.
• После обновления приложения его нужно переустановить, чтобы появились новые поля.
• Для робота смотрите раздел роботов приложений; для БП — действия приложений.

Сообщение не приходит в Макс

Проверьте:

1. Верный токен бота (скопирован целиком из настроек бота).
2. Верный CHAT ID.
3. Для группы: ID указан с минусом в начале (например -76170460923914, а не 76170460923914).
4. Бот добавлен в чат (для группы) и имеет право писать; для лички пользователь запустил бота.
5. Журнал робота / БП — там будет текст ошибки.

Ошибка с вложением

• Для файла из CRM используйте именно «Вложение (файл)» и кнопку Вставка, а не ручной ввод ID.
• Для ссылки URL должен начинаться с http:// или https://.
• Не заполняйте оба поля вложения сразу без необходимости.

Как понять, что отправка прошла успешно

В журнале БП / робота появятся записи:

• «Отправка сообщения в Макс…»
• «Сообщение отправлено в Макс» — успех
  или «Ошибка отправки в Макс» / описание проблемы — сбой.

В активити можно дополнительно проверить возвращаемое поле Успешно.

---

Краткая шпаргалка

1. Установите приложение на портал.
2. Скопируйте токен бота из настроек на платформе MAX (или «MAX для бизнеса»).
3. Узнайте CHAT ID: для группы — с - в начале; для лички — обычно без минуса.
4. Добавьте робота на стадию CRM или активити в шаблон БП.
5. Заполните токен, CHAT ID и текст; при необходимости — вложение.
6. Сохраните, прогоните тест, при ошибке смотрите журнал выполнения.