Настройка и проверка интеграции CRM 4DEV с мессенджером Max

1. Назначение

Интеграция позволяет сотруднику подключить личный чат с Max-ботом и получать в нём уведомления CRM 4DEV.

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

2. Предварительные условия

Перед настройкой необходимо проверить:

• используется версия CRM 4DEV, содержащая интеграцию Max;
• сервер 1С имеет исходящий доступ к Max API;
• информационная база опубликована по внешнему адресу HTTPS;
• URL HTTP-сервиса доступен из интернета без VPN;
• у пользователя есть права на персональные настройки CRM;
• для первоначальной настройки интеграции есть право на создание записи в Дев_АктуальныеИтеграции;
• создан Max-бот и получен его токен.

Локальный URL, адрес внутренней сети и URL без корректного HTTPS для webhook использовать нельзя.

3. Создание Max-бота

1. Откройте Max.
2. Найдите @MasterBot.
3. Выполните команду /newbot.
4. Укажите имя и username бота.
5. Сохраните выданный токен.
6. Не передавайте токен посторонним и не публикуйте его в задачах, логах или документации.

4. Первичная настройка интеграции в CRM

1. Откройте Главная → Персональные настройки CRM.
2. Перейдите на вкладку Бот оповещений.
3. Если интеграция Max ещё не настроена, вставьте токен бота.
4. Нажмите Сохранить и подключить.

CRM должна:

1. Проверить токен запросом информации о боте.
2. Создать или обновить активную запись Max в справочнике Дев_АктуальныеИтеграции.
3. Сохранить токен в настройках интеграции.
4. Сформировать адрес HTTP-сервиса для бота.
5. Переустановить webhook в Max API.
6. Создать одноразовый код привязки пользователя.

В Дев_АктуальныеИтеграции ожидаются значения:

• базовая интеграция: Max;
• метод: username бота;
• активность: включена;
• пометка удаления: отсутствует;
• настройки JSON: содержат токен.

Токен нельзя показывать обычным пользователям или прикладывать к отчёту об ошибке.

5. Привязка сотрудника к Max-боту

1. В блоке Max нажмите Подключить Max-бот.
2. CRM должна показать: - QR-код; - ссылку «Открыть бот в Max»; - восьмизначный код привязки; - состояние «Ожидание подключения».
3. Откройте бота по ссылке или QR-коду.
4. Нажмите Старт.
5. Дождитесь подтверждения от бота.
6. Вернитесь в CRM.

Форма CRM автоматически проверяет состояние подключения. После успешной привязки должно отображаться состояние «Подключено».

Код привязки действует 15 минут. При истечении срока сформируйте новый код.

6. Что создаётся при привязке

До подтверждения в Max в регистре Дев_КодыПривязкиMax создаётся временная запись:

• код;
• пользователь CRM;
• срок действия.

После нажатия Старт webhook Max передаёт событие в CRM. CRM проверяет код и создаёт в регистре IDПользователейДляОповещений запись:

• пользователь: текущий пользователь CRM;
• тип мессенджера: Max;
• ID: user_id пользователя Max.

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

7. Настройка уведомлений

Для нужного вида события необходимо проверить настройки оповещения:

• оповещение активно;
• включён флаг «Оповещать через бот Max»;
• заполнен текст сообщения;
• определён сотрудник-получатель или руководитель;
• у получателя есть запись Max в регистре IDПользователейДляОповещений.

Если эти условия не выполнены, создание сделки не приведёт к сообщению в Max, даже если бот успешно подключён.

8. Проверка работы

8.1. Проверка webhook и привязки

1. Отключите Max-бота в персональных настройках, если он уже подключён.
2. Запустите подключение повторно.
3. Убедитесь, что появились новый код и QR-код.
4. Нажмите Старт в Max.
5. Проверьте получение подтверждения в Max.
6. Проверьте состояние «Подключено» в CRM.
7. Проверьте запись ТипМессенджера = Max в IDПользователейДляОповещений.

Этот сценарий подтверждает работоспособность входящего webhook.

8.2. Проверка уведомления CRM

1. Выберите конкретный настроенный вид оповещения.
2. Убедитесь, что в нём включён канал Max.
3. Привяжите к Max пользователя, который будет получателем.
4. Создайте тестовый объект с уникальным названием, например MAX-ТЕСТ-2026-06-19.
5. Выполните действие, являющееся триггером: запись, проведение, создание сделки или переход этапа — согласно настройкам выбранного оповещения.
6. Проверьте сообщение в личном чате с ботом Max.

Ожидаемый результат:

• сообщение приходит правильному пользователю;
• текст соответствует шаблону оповещения;
• данные тестовой сделки корректны;
• сообщение приходит один раз;
• другой пользователь без подписки сообщение не получает.

9. Диагностика

Ошибка Field 'url' is not a valid URL

Max API отклонил адрес webhook. Необходимо проверить внешний адрес публикации, путь HTTP-сервиса, наличие https://, отсутствие пробелов и корректное объединение адреса с методом интеграции.

Состояние остаётся «Ожидание подключения»

Проверьте:

• не истёк ли код;
• нажата ли кнопка Старт именно у нужного бота;
• доступен ли webhook из интернета;
• соответствует ли метод HTTP-сервиса username бота;
• есть ли входящий запрос Max в журнале обмена;
• нет ли нескольких старых webhook у того же бота.

Подключение успешно, но уведомление не приходит

Проверьте:

• активен ли вид оповещения;
• включён ли канал Max;
• является ли подключённый пользователь получателем;
• есть ли у пользователя запись ТипМессенджера = Max;
• заполнен ли токен активной интеграции;
• сформирован ли непустой текст сообщения;
• действительно ли выполнено событие-триггер.

Сообщение приходит несколько раз

Возможные причины:

• зарегистрировано несколько webhook;
• событие CRM вызывается повторно;
• один пользователь одновременно является сотрудником и руководителем-получателем;
• повторная обработка произошла после сетевой ошибки.

Необходимо проверить идемпотентность события и список webhook. При настройке CRM переустанавливает webhook, поскольку простое добавление новой подписки может оставить старую активной.

10. Журналы

Для технической диагностики используйте регистр ЖурналОбменаAPI и журнал регистрации 1С.

Ищите события:

• Max.setWebhook — регистрация webhook;
• Max.<username бота> — входящий запрос Max;
• CRM_РаботаСМессенджеромMax.bot_started — обработка подключения пользователя;
• Не выполнена отправка в бот Max — ошибка исходящего уведомления.

Для входящего webhook ожидается успешный HTTP-ответ. Ошибки токена, URL, сетевого соединения и Max API должны быть зафиксированы в журнале.

11. Минимальный чек-лист приёмки

• [ ] Активная интеграция Max создана без дублей.
• [ ] Webhook зарегистрирован на правильный адрес текущей базы.
• [ ] QR-код и ссылка открывают нужного бота.
• [ ] Код привязки ограничен сроком действия.
• [ ] После Старт пользователь получает подтверждение.
• [ ] В CRM отображается состояние «Подключено».
• [ ] В IDПользователейДляОповещений записан корректный Max user_id.
• [ ] Настроенное событие CRM формирует сообщение.
• [ ] Сообщение приходит правильному получателю один раз.
• [ ] Ошибки фиксируются в журналах без раскрытия токена.

12. Ограничения

• Интеграция требует внешней доступности HTTP-сервиса CRM.
• Подключение выполняется отдельно для каждого пользователя CRM.
• Наличие подключённого бота не включает все уведомления автоматически.
• Конкретный текст и момент отправки зависят от настроенного вида оповещения.
• Перед проверкой в рабочей базе используйте тестовую сделку и согласованного получателя.

Автор инструкции: Кирилл Озорнин.