Модуль Чат бот

Настройка интеграций с ботами

ВКонтакте

Для интеграции с сообщениями в сообществе необходимо указать токен (Создать токен можно в разделе "Работа с API") и указать идентификатор сообщества.

После указания токена бот начнет читать сообщения в сообществе и взаимодействовать с пользователями. Для отключения бота необходимо удалить токен из настройки.

MAX

Для интеграции необходимо указать токен в настройках системы. Создать бота и получить токен можно через канал @masterbot (https://web.max.ru/masterbot) в соответствии с документацией на сайте MAX https://dev.max.ru/docs/chatbots/bots-coding/prepare

Для получения новых сообщений существует два способа

Long Polling
Webhook

При работе через периодический запрос сервера (Long Polling). Для корректной работы боты необходимо настроить выполнение команды max:new-message (MAX. Новые сообщения).

Для работы через webhook необходимо в настройках бота указать адрес хука на внешнем портале МФЦ. (пример https://webportalmfc.azovkomeks.ru/max/webhook). Внешний портал должен иметь доступ к API mfc-core для обработки сообщения. Если настроена работа через webhook консольная команда max:new-message (MAX. Новые сообщения) будет обрываться, т.к. в очередь сообщения не будут попадать. Если удалить настроенный webhook необработанные сообщения будут потеряны и очередь для long polling будет наполняться только новыми сообщениями.

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

При необходимости можно указать ссылку на бота. Данную ссылку можно вставить в уведомления через метку $$$ЧатБотMax$$$.

Время повторной проверки новых сообщений влияет как часто система будет обращаться к API max. Соответственно это может влиять на отзывчивость бота. Рекомендуем указывать значение 10 секунд.

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

По умолчанию заявителю доступны только публичные сервисы (которые корректно работают без авторизации).

Для входа в личный кабинет необходимо передать номер телефона (карточку пользователя) в разделе "Личный кабинет".

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

Политика конфиденциальности

При необходимости можно запросить у пользователей согласие с политикой конфиденциальности. Для этого необходимо указать текс сообщения (на форме "Настройка интеграций с ботами"), который будет показан пользователю при начале работы с ботом. Пока пользователь не примет условия политики конфиденциальности взаимодействие с ботом будет запрещено.

На форме "Список подписчиков бота" отображается информация о кол-ве чатов с подтвержденной политикой конфиденциальности. При необходимости можно отфильтровать чаты по значению из колонки "Политика конфиденциальности".

Запрос статуса дела через сторонний сервис

При необходимости запроса статуса дела в стороннем сервисе необходимо указать адрес сервиса и префикс в номере дела для отправления запросов.

В адресе стороннего сервиса необходимо указать полный путь до сервиса. К данному адресу в конце будет добавлен номер дела, который ввел пользователь в чат бот.

Пример: Если адрес стороннего сервиса https://externalservice.ru/case-info/ и пользователь передаст номер дела пкпвд-123 итоговая строка запроса будет выглядеть так https://externalservice.ru/case-info/ПКПВД-123. Номер дела будет приведен в верхний регистр.

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

Сторонний сервис должен возвращать ответ в формате:

Для успешных результатов ответ должен быть в формате json со структурой:

{
    "response": {
        "status": 0,
        "statusInfo": "Исполнено",
        "dateCreate": "09.01.2025",
        "subdivision": "Название подразделения",
        "phone": "+7(928)***-08-88"
    }
}

Для обработанной ошибки (где, текст из statusInfo будет отправлен заявителю в чат):

{
  "error": {
    "status": "404",
    "statusInfo": "Дело не найдено"
  }
}

Скилл в Марусе

Необходимо добавить новый скилл для Маруси по адресу https://vk.com/editapp?act=create. В качестве адреса хука необходимо указать фиксированный адрес на внешнем портале https://{portal.mfc}/marusia/webhook. Весь обмен с Марусей происходит через внешний портал. После поступления запроса на внешний портал он будет перенаправлен на mfc-core и обрабатываться через универсальный механизм чат ботов в МФЦ. Соответственно необходимо организовать сетевой доступ от внешнего портала до сервера mfc-core.

Для децентрализованных систем необходимо заполнить в настройках чат ботов список серверов mfc-core, которые будут обрабатывать запросы поступающих от Маруси. Соответственно внешний портал, на который указывает хук должен иметь доступ ко всем серверам.

Для добавления необходимо указать название, которое пользователь должен назвать для выбора. Название необходимо указывать в соответствии с муниципальными образованиями, где установлен сервер МФЦ. В поле URL mfc-core необходимо указать адрес сервера mfc-core в соответствии с форматом поля Адрес сервера с API из общих настроек МФЦ.

При сохранении будет проверена корректность адреса и отправлен тестовый запрос.

Если колонку с Марусей необходимо жестко привязать к определенному серверу МФЦ укажите Идентификатор пользователя, под которым авторизована данная станция. При этом ряд сервисов будет недоступен (выбор мфц и личный кабинет).

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

После настройки хука можно попросить запустить скилл в соответствии с указанным названием. После запуска пользователь попадет либо на основной сервис (на внешний портал которого ведет хук), либо на фиксированный, если его указали в настройках.

По умолчанию заявителю доступны только публичные сервисы (которые корректно работают без авторизации). Для публичных сервисов работает полное голосовое управление, без необходимости открывать чат с Марусей на устройствах.

При запросе сервиса статус дела необходимо назвать номер дела. При этом не будет осуществлена проверка наличия заявителя в участниках дела. Если дело будет найдено, то в ответ будет отправлена краткая информация о нем. Если дело не удастся найти, заявителю будет отправлен соответствующий ответ.

Если данный сервис будет вызван с учетом авторизации, то заявителю будут показаны кнопки со списком всех его дел. При этом пользователь может как нажать кнопку, так и назвать номер дела голосом.

При запросе сервиса "информация о подразделениях" система проанализирует через какое устройство пришел запрос. Для голосовых платформ бот предложит назвать населенный пункт и улицу для поиска подразделения. При запросе через классические чат боты будет показан список офисов с возможностью выбора по номеру офиса из списка.

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

Сервис личный кабинет позволяет авторизовать пользователя для доступа к большему количеству сервисов и автоматизации возможных вариантов выбора с учетом номера телефона.

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

При входе в личный кабинет будет выведена информация о текущем номере телефона. При необходимости пользователь может выйти и войти под другим номером телефона или продолжить работу без авторизации.

Если Маруся используется на децентрализованных системах доступен сервис выбора МФЦ. При этом пользователю необходимо сказать название муниципального образования для переключения на другой сервер МФЦ.

Сервис выбора МФЦ предоставляет разный функционал в зависимости от запуска. Если сервис был запущен на основном МФЦ, то будет предоставлен список МФЦ в которые можно переключиться. При запуске на второстепенном МФЦ будет доступен только выход из текущего МФЦ. При этом пользователь попадет в основной МФЦ и может продолжить работу в нем или переключиться в другой МФЦ.

Навык в Алисе

Необходимо добавить новый навык для Алисы в яндекс диалогах по адресу https://dialogs.yandex.ru/developer.

В качестве адреса хука необходимо указать фиксированный адрес на внешнем портале https://{portal.mfc}/alisa/webhook. Весь обмен с Марусей происходит через внешний портал. После поступления запроса на внешний портал он будет перенаправлен на mfc-core и обрабатываться через универсальный механизм чат ботов в МФЦ. Соответственно необходимо организовать сетевой доступ от внешнего портала до сервера mfc-core.

Принцип работы навыка в Алисе совпадает со скиллом в Марусе. Для подтверждения телефона будет отправляться уведомление через ВК бизнес сообщения, аналогично как в Марусе.

Телеграм

Для управления телеграм ботом реализован модуль "Телеграм". Данный модуль позволяет управлять подпиской заявителей на уведомление и отправлять уведомления заявителям в процессе оказания услуг.

Для работы модуля необходимо создать бота через канал @BotFather (https://t.me/BotFather) и получить токен для доступа к API.

При начале взаимодействия с ботом придет запрос с просьбой отправить номер телефона для дальнейшего отправления уведомлений.

При нажатии на кнопку "Отправить телефон" будет отправлена карточка заявителя на сервер МФЦ.

Когда данные будут обработаны придет уведомление в чат с заявителем. Далее все уведомления с алгоритмом "Отправление сообщений через телеграм бота" будут приходить в этот чат.

Настройка меню в чате телеграм

Для добавления новых пунктов меню необходимо через @BotFather выбрать раздел "Edit Bot"-"Edit Commands" и написать список команд, которые будут доступны в чате.

Рекомендуем добавить как минимум одну команду menu - Меню. При выборе данной команды будет отправлено сообщение к боту и он в зависимости от ситуации выведет список доступных сервисов или предложит продолжить последний активный сервис.

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

В колонке команда для бота указан текст, который боты обработает в автоматическом режиме и если нет активного сервиса сразу запустит этот сервис.

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

Список чатов

Данная форма позволяет просмотреть все чаты заявителей, которые подписались на работу с ботом. Если не указаны номера телефон, то данные заявители не получат сообщения от МФЦ через механизм уведомлений.

История отправленных сообщений

Данная форма отображает информацию о всех сообщениях отправленных ботом и заявителями. Данная форма позволяет анализировать историю взаимодействия с ботом. Время удаления проставляется если на стороне бота были удалены сообщения. Бот удаляет все сообщения до момента получения телефона, т.к. эта информация является технической и не относится к дальнейшим уведомлениям заявителя.

При необходимости можно просмотреть содержимое сообщения для более детального анализа информации

Редактирование шаблонов сообщений

Чат бот поддерживает возможность изменения текста сообщений, которые отправляются пользователям.

Изменения шаблона поддерживает несколько способов замены:

Переопределение базового шаблона
Переопределение персональных шаблонов для каждого бота

Таблица показывает какие шаблоны были переопределены.

При редактировании шаблона можно увидеть Ключ и название шаблона. В поле "системный шаблон" будет показан текст шаблона, который отправляется по умолчанию.

При указании базового шаблона текст будет изменен для всех чат ботов, которые работают в системе.

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

Некоторые шаблоны содержат динамические параметры. Имя метки можно указывать в любом месте шаблона и в момент формирования текста метки будет заменены на значения и отправлены в чат.