¶ Инструкция по настройке чат-бота МАХ в БЮЛ ЕПС
¶ 1. Назначение инструкции
Инструкция описывает полный порядок настройки чат-бота МАХ для работы с конфигурацией БЮЛ ЕПС.
После выполнения настройки чат-бот должен принимать обращения пользователей из МАХ, передавать их в БЮЛ ЕПС через опубликованный HTTP-сервис и возвращать пользователю ответ.
Сервис чат-бота МАХ предоставляется по подписке и является платным. Для использования функционала необходимо наличие действующей подписки на сервис.
¶ 2. Предварительные требования
Перед началом настройки необходимо убедиться, что:
- Версия программы БЮЛ ЕПС — не ниже 5.0.4.2.
- Есть доступ к конфигуратору 1С с правами администратора.
- Есть доступ к серверу IIS, на котором выполняется публикация HTTP-сервиса.
- Есть доступ к MAX для партнеров для регистрации организации и создания чат-бота.
- Есть ключи на использование:
- Мессенджер Макс: чат-бот;
- Мессенджер Макс: уведомления.
¶ 3. Общий порядок настройки
Настройка выполняется в следующем порядке:
- Проверить версию программы.
- Зарегистрировать организацию в МАХ.
- Создать чат-бота в МАХ.
- Создать пользователя 1С для интеграции с МАХ.
- Настроить и опубликовать HTTP-сервис.
- Настроить чат-бота в БЮЛ ЕПС.
- Настроить поведение чат-бота.
- Активировать ключи на чат-бота и уведомления.
- Проверить работу чат-бота.
¶ Шаг 1. Проверить версию программы
Перед началом настройки необходимо проверить версию программы БЮЛ ЕПС.
Версия должна быть не ниже 5.0.4.2.
Как посмотреть название и версию программы, описано в отдельной инструкции:
Как посмотреть название и версию программы
Если версия ниже 5.0.4.2, сначала необходимо установить обновление.
¶ Шаг 2. Зарегистрировать организацию в МАХ
Для создания чат-бота необходимо подключить организацию в MAX для бизнеса.
- Откройте сайт MAX для бизнеса.
- Нажмите «Подключить».
- Выполните вход по номеру телефона.
- Укажите ИНН организации.
- Подтвердите организацию в MAX для бизнеса.
Важно: подтверждение организации выполняется на стороне MAX для бизнеса. Следуйте подсказкам сервиса.
Важно: к одной организации можно привязать только один номер телефона.
После подтверждения и проверки организация будет доступна для создания чат-бота.
¶ Шаг 3. Создать чат-бота в МАХ
После подтверждения организации необходимо создать чат-бота в MAX для бизнеса.
- На главной странице MAX для бизнеса выберите карточку «Чат-боты».
- Нажмите «Добавить бота».
- Заполните форму создания бота.
В форме необходимо заполнить:
| Поле | Что указать |
|---|---|
| Логотип | Изображение 500×500 px, размером не более 5 Мб. Будет использоваться как аватар бота. |
| Название | Понятное название бота, например «Ломбард Выбор». |
| Ник | Уникальный идентификатор бота. Система предложит вариант автоматически. |
| Телефон компании | Номер телефона, связанный с ботом. |
| Сайт | Ссылка на сайт компании. Поле необязательное. |
| Описание | Описание задач бота, его функций и преимуществ. |
- Внизу формы нажмите «Создать».
- После создания бота перейдите на вкладку «Интеграция».
- Скопируйте и сохраните токен бота.
Токен понадобится дальше при настройке чат-бота в БЮЛ ЕПС.
¶ Шаг 4. Создать пользователя 1С для интеграции с МАХ
В БЮЛ ЕПС необходимо создать отдельного технического пользователя, под которым будет работать интеграция с МАХ.
Настройка выполняется в три этапа:
- Создать профиль групп доступа.
- Создать пользователя.
- Назначить пользователю созданный профиль доступа.
¶ 4.1. Создать профиль групп доступа
- Откройте раздел Настройки и сервисы.
- Перейдите в Настройки пользователей и прав.
- Раскройте блок Группы доступа.
- Откройте Профили групп доступа.
- Нажмите Создать.
- В поле Наименование укажите:
MAX
- На вкладке Разрешенные действия (роли) установите флаг напротив роли:
Базовые права мессенджер Макс
- Нажмите Записать и закрыть.
¶ 4.2. Создать пользователя
- Вернитесь в Настройки пользователей и прав.
- В блоке Пользователи откройте Пользователи.
- Нажмите Создать.
- В поле Полное имя укажите:
Чат-бот MAX
- Установите флаг Аутентификация 1С:Предприятия.
- Нажмите Установить пароль.
- В окне Установка пароля укажите пароль и подтверждение пароля.
- Нажмите Установить пароль.
- При необходимости снимите флаг Показывать в списке выбора, чтобы технический пользователь не отображался в списке выбора пользователей.
- Нажмите Записать.
¶ 4.3. Назначить пользователю профиль доступа
- В карточке пользователя нажмите Права доступа.
- В списке Профили пользователя установите флаг напротив профиля:
MAX
- Нажмите Записать.
Логин и пароль этого пользователя понадобятся при настройке публикации HTTP-сервиса в файле default.vrd.
Другие профили и роли пользователю назначать не требуется.
¶ Шаг 5. Настроить и опубликовать HTTP-сервис
Для работы чат-бота необходимо опубликовать HTTP-сервис ЧатБотМакс.
Публикация HTTP-сервиса выполняется по отдельной инструкции:
Инструкция по публикации HTTP-сервиса ЧатБотМакс
Важно: опубликованный webhook должен быть доступен извне по HTTPS через порт 443. Если порт 443 недоступен, МАХ не сможет отправить обращение в опубликованный HTTP-сервис.
Необходимо использовать сертификаты от доверенных центров, в том числе сертификаты Минцифры. Доменное имя в URL Webhook-endpoint должно совпадать с CN или SAN сертификата
При публикации необходимо учитывать следующие параметры:
| Параметр | Значение |
|---|---|
| HTTP-сервис | ЧатБотМакс |
| Корневой URL | max |
| Пользователь подключения | пользователь, созданный на шаге 4 |
После публикации адрес webhook формируется по шаблону:
https://"адрес сервера публикации"/"название публикации"/hs/max
¶ Шаг 6. Настроить чат-бота в БЮЛ ЕПС
После публикации HTTP-сервиса необходимо подключить созданного чат-бота к БЮЛ ЕПС.
Настройка выполняется в справочнике «Чат-боты мессенджера MAX».
- Откройте раздел Настройки и сервисы.
- Откройте справочник «Чат-боты мессенджера MAX».
- Создайте новый элемент.
- Заполните поля:
| Поле | Что указать |
|---|---|
| Наименование | Понятное название чат-бота. Например, Чат-бот MAX. |
| Токен | Токен бота, полученный в MAX для бизнеса на вкладке «Интеграция». |
| Секретный ключ | Уникальное кодовое слово латиницей. Используется для идентификации чат-бота. |
| Адрес сервиса обработки веб-хуков | Адрес опубликованного HTTP-сервиса 1С ЧатБотМакс. |
Поле «Адрес сервиса обработки веб-хуков» заполняется по шаблону:
https://"адрес сервера публикации"/"название публикации"/hs/max
Где:
| Параметр | Описание |
|---|---|
"адрес сервера публикации" |
адрес сервера, на котором опубликован HTTP-сервис |
"название публикации" |
имя публикации, указанное при публикации HTTP-сервиса |
hs/max |
путь к HTTP-сервису ЧатБотМакс |
Пример:
https://server.domain.ru/webhook/hs/max
Важно: адрес webhook должен быть доступен извне по HTTPS через порт 443. Если адрес недоступен, МАХ не сможет отправлять обращения в БЮЛ ЕПС.
Поле «Секретный ключ» должно состоять из допустимых символов. При заполнении программа проверяет значение поля. Чтобы посмотреть введенный секретный ключ, нажмите кнопку с изображением глаза справа от поля.
- Нажмите «Записать», чтобы сохранить созданного чат-бота.
- Нажмите «Подписать бота на обновления».
После нажатия кнопки программа передаст в MAX адрес сервиса обработки веб-хуков. С этого момента MAX сможет отправлять обращения чат-бота в опубликованный HTTP-сервис БЮЛ ЕПС.
После успешной подписки статус должен измениться с «ОТПИСАН ОТ ОБНОВЛЕНИЙ» на статус подписанного бота.
¶ Шаг 7. Настроить поведение чат-бота
Далее необходимо настроить, какие сообщения, кнопки и данные чат-бот будет показывать пользователю.
Настройка выполняется в справочнике «Настройки чат-ботов мессенджера MAX».
- Откройте раздел Настройки и сервисы.
- Откройте справочник «Настройки чат-ботов мессенджера MAX».
- Создайте новый элемент.
- В поле Чат-бот выберите чат-бота, созданного на предыдущем шаге.
- В поле Адрес сайта для перехода из бота укажите ссылку на сайт организации.
Если поле «Адрес сайта для перехода из бота» заполнено, в чат-боте будет отображаться кнопка «Наш сайт». Если поле не заполнено, кнопка не добавляется.
¶ Настроить шаблоны сообщений
На вкладке «Настройки шаблонов текстовых сообщений» задаются тексты, которые чат-бот будет показывать пользователю при разных событиях.
Для каждого типа шаблона можно указать свой текст. В шаблонах поддерживаются подставляемые поля, например %НомерТелефона%.
Пример шаблона для типа «Начало работы с ботом»:
Здравствуйте!
С помощью данного чат-бота ломбарда «Мой ломбард» можно:
Посмотреть состояние ваших залоговых билетов
Получить уведомление об истекающем сроке залога
Оформить заявку на продление льготного срока
Получить информацию об адресах и режимах работы отделений
Пример шаблона для типа «Профиль»:
Вы авторизованы в боте.
Номер телефона —%НомерТелефона%
ФИО —%ФИО%
¶ Заполнить организации
На вкладке «Организации» укажите организации, которые будут использоваться при поиске активных залоговых билетов по авторизованному пользователю.
¶ Заполнить филиалы
На вкладке «Филиалы» укажите филиалы, которые будут отображаться пользователю по кнопке «Режимы работы отделений».
¶ Заполнить дополнительные настройки
На вкладке «Дополнительные настройки» можно разрешить клиентам самостоятельно продлевать льготный период по билету через оформление документа «Заявка на продление льготного срока».
Чтобы включить эту возможность:
- Установите флаг «Разрешить продление билетов».
- Заполните поле «Количество продлений».
- Заполните поле «Срок продления».
Поле «Количество продлений» определяет, сколько раз клиент сможет оформить продление дистанционно в рамках одного билета.
Поле «Срок продления» определяет срок продления по умолчанию в днях.
После заполнения настроек нажмите «Записать и закрыть».
Важно: если настройки для чат-бота не заполнены, при попытке начать взаимодействие в MAX пользователь увидит пустой чат — кнопки и сообщения отображаться не будут.
¶ Шаг 8. Активировать ключи на чат-бота и уведомления
Для работы чат-бота необходимо активировать подписки и связать их с созданным чат-ботом.
В программе используются две подписки:
| Подписка | Для чего используется |
|---|---|
| Мессенджер Макс: чат-бот | Используется для обработки обращений пользователей к чат-боту. Подписка действует в течение определенного срока. |
| Мессенджер Макс: уведомления | Используется для отправки сообщений через Мессенджер Макс, например при рассылке уведомлений или при электронном подписании билетов. Подписка действует по количеству операций. |
- Откройте раздел Настройки и сервисы.
- В блоке Управление подписками откройте Управление подписками.
- Активируйте имеющиеся ключи.
Дальнейшие действия необходимо выполнить отдельно для каждой подписки:
- Мессенджер Макс: чат-бот
- Мессенджер Макс: уведомления
Для каждой подписки выполните следующие действия:
- Откройте подписку.
- Нажмите «Связать ключ и чат-бот».
- Выберите чат-бота, созданного на шаге 6.
- Нажмите «Подключить чат-бот к подписке».
Если подключение выполнено успешно, появится сообщение об успешном подключении, а ключ будет связан с выбранным чат-ботом.
Важно: связь нужно создать отдельно для подписки «Мессенджер Макс: чат-бот» и отдельно для подписки «Мессенджер Макс: уведомления».
Повторно добавить связь для этого ключа нельзя.
¶ Шаг 9. Проверить работу чат-бота
После завершения настройки необходимо проверить, что чат-бот принимает обращения из МАХ и передает их в БЮЛ ЕПС.
- Откройте чат-бота в МАХ.
- Отправьте любое сообщение или команду.
- Дождитесь ответа чат-бота.
Любой ответ чат-бота считается успешной проверкой.
Если чат-бот ответил, значит:
- МАХ отправил обращение на webhook.
- Опубликованный HTTP-сервис принял обращение.
- Запрос дошел до БЮЛ ЕПС.
- БЮЛ ЕПС обработала запрос.
- Ответ вернулся пользователю в МАХ.
Если чат-бот не ответил, проверьте:
- Доступен ли опубликованный webhook извне по HTTPS через порт 443.
- Webhook удостоверен TLS-сертификатом, выданным доверенным центром сертификации, или TLS-сертификатом Минцифры. Самоподписанные сертификаты не поддерживаются.
- Доменное имя в URL Webhook-endpoint совпадает с CN или SAN сертификата
- Сервер предоставляет полную цепочку сертификатов
- Правильно ли указан адрес сервиса обработки веб-хуков в справочнике «Чат-боты мессенджера MAX».
- Нажата ли кнопка «Подписать бота на обновления».
- Указаны ли в файле
default.vrdлогин и пароль пользователя, созданного для интеграции с МАХ. - Назначен ли пользователю профиль доступа с ролью «Базовые права Макс».
- Активированы ли подписки «Мессенджер Макс: чат-бот» и «Мессенджер Макс: уведомления».
- Связаны ли обе подписки с нужным чат-ботом.
- Нет ли ошибок в журнале регистрации 1С.
- Нет ли ошибок на стороне IIS.
Настройка считается выполненной успешно, если пользователь отправляет сообщение чат-боту в МАХ и получает ответ.