TelegramBotIntegration

Репозиторий шаблона разработки «Чат-бот Telegram». Код микросервиса для обработки сообщений.

Функционал, предоставляемый шаблоном решения:

Главное меню чат-бота.

1. Регистрация в чат-боте.

Регистрация сотрудника в чат-боте может быть произведена:

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

2. Самим сотрудником в том случае, если в его записи справочника "Сотрудники" в Directum RX указан адрес электронной почты, и в конфигурационном файле чат-бота указаны настройки для отправки писем:

   • Чат-бот запрашивает у пользователя в чате адрес почты. Далее происходит проверка, есть ли в Directum RX действующая запись справочника "Сотрудники", в которой поле "Эл. почта" совпадает с электронной почтой, введенной пользователем.
   • В случае, если сотрудник в Directum RX найден, на адрес почты, введенной пользователем, отправляется код подтверждения. Если сотрудник верно вводит код подтверждения в чате, то в Directum RX создается новая запись справочника "Пользователи чат-бота".
     

2. Авторизация в чат-боте.

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

1. В случае, если запись справочника "Пользователи чат-бота не найдена", чат-бот предлагает пользователю пройти процедуру регистрации.
2. В случае, если запись справочника "Пользователи чат-бота найдена" и находится в состоянии "Закрыта", пользователю выводится сообщение "Ваша учетная запись заблокирована".
3. В случае, если запись справочника "Пользователи чат-бота найдена" и находится в состоянии "Действующая", пользователь может выполнять действия в чат-боте.

3. Получение информации о контрагентах.

1. Чат-бот запрашивает наименование контрагента.
   
2. В чат выводится список контрагентов, наименования которых содержат введенную пользователем строку.
   
3. Если список найденных контрагентов занимает больше 5 строк, то в список кнопок добавляются «Далее» и «Назад» для перехода по списку записей. Список записей, получаемых из сервиса интеграции, ограничивается 200 записями, т.к. при большем количестве найденных записей перемещаться по ним будет неудобно.
4. При нажатии на кнопку с наименованием нужного пользователю контрагента, выводится информация о нем в текстовом виде.
   

4. Поиск документов.

1. Чат-бот предлагает выбрать тип документа, по которому пользователь хочет осуществить поиск. Для этого чат-бот получает список типов документов из справочника "Типы документов" в Directum RX и выводит их наименования в виде кнопок клавиатуры в чат с пользователем.
   
2. После выбора типа документа чат-бот предлагает ввести наименование документа.
   
3. После ввода наименования документа чат-бот отправляет запрос в сервис интеграции Directum RX для получения списка документов с фильтром по типу документа и наименованию. Список ограничивается 200 документами, т.к. при большем количестве найденных записей перемещаться по ним будет неудобно. Если найдено более 5 документов, то в список кнопок добавляются «Далее» и «Назад» для перехода по списку записей. В список попадают только те документы, на которые у текущего сотрудника есть права на просмотр.
   
4. После того, как пользователь выберет нужный документ, чат-бот отправляет последнюю версию данного документа в чат.
   

5. Отправка задач на исполнение заявок в Directum RX.

1. Чат-бот запрашивает у пользователя описание заявки в свободной форме.
2. После ввода текста заявки бот дает возможность пользователю прикрепить к сообщению вложения (например, фото или видео).
3. После нажатия кнопки "Отправить" чат-бот отправляет запрос в Directum RX на формирование задачи на исполнение заявки: сотрудникам, входящим в роль "Ответственные за заявки" отправляется простая задача от имени сотрудника, отправившего заявку через чат-бот. Вложения, прикрепленные к сообщению в чате, автоматически заносятся в Directum RX с типом "Простой документ" и прикрепляются к задаче. В тексте задачи указывается текст, введенный пользователем в чат-боте.

Настройка.

Конфигурация чат-бота задается в файле _ConfigSettings.xml (необходимо создать копию файла _ConfigSettings.xml.example):

1. LOGS_PATH - Путь к папке для записи логов.
2. TELEGRAM_BOT_API_KEY - API ключ телеграм-бота. Создать нового бота или получить его ключ можно через телеграм-бота @BotFather.
3. INTEGRATION_SERVICE_URL - адрес сервиса интеграции Directum RX.
4. INTEGRATION_USER_LOGIN - логин пользователя Directum RX, через которого будут отправляться запросы к сервису интеграции.
5. INTEGRATION_USER_PASSWORD - пароль пользователя Directum RX
6. SMTP_ADDRESS - адрес ящика электронной почты для отправки кода подтверждения при регистрации пользователя.
7. SMTP_LOGIN - логин ящика электронной почты.
8. SMTP_PASSWORD - пароль от ящика электронной почты.
9. SMTP_HOST - адрес сервера электронной почты.
10. SMTP_PORT - порт сервера электронной почты.
11. SMTP_SECURE - тип шифрования подключения к почтовому серверу. Возможные значения: Auto, None, SslOnConnect, StartTls, StartTlsWhenAvailable.
12. ENTITIES_ON_PAGE - количество сущностей, выводимых на одной "странице" при выводе списка сущностей в виде кнопок клавиатуры. Значение по умолчанию - 4.
13. MAX_TOTAL_LENGTH_IN_MARKUP - максимальное суммарное количество символов в кнопках клавиатуры, рахмещаемых в однй строке. При превышении данного значения, кнопка переносится на следующую строку. Значение по умолчанию - 50.
14. USER_CHECK_INTERVAL - Интервал в секундах для проверки авторизации пользователя в Directum RX. Значение по умолчанию - 60.

Порядок запуска микросервиса средствами ServiceRunner (только для Windows):

1. Выполнить публикацию проекта Self-Contained.
2. Содержимое заархивировать в zip, назвать BotWorkerService.zip
3. Скопировать архив в \etc_builds_package
4. На основе _ConfigSettings.xml.example создать _ConfigSettings.xml в папке \etc\services_config\BotWorkerService
5. Добавить в конфиге ServiceRunner'а (\etc_services_config\ServiceRunner) строку:
   <ServiceSetting Name="BotWorkerService" Config="BotWorkerService\_ConfigSettings.xml" Package="BotWorkerService.zip" ConfigWatcherEnabled="false" Disabled="false" />

Варианты использования на проекте:

A. Использование готового функционала шаблона

1. Склонировать репозиторий в локальную папку, либо скачать zip-архив;
2. Собрать проект с помощью dotnet;
3. Настроить конфигурацию чат-бота и логирования;
4. Запустить сервис.

B. Доработка функционала шаблона

Fork репозитория

1. Сделать fork репозитория TelegramBotIntegration для своей учетной записи;
2. Склонировать созданный в п. 1 репозиторий в папку;

Копирование репозитория в систему контроля версий

Рекомендуемый вариант для проектов внедрения.

1. В системе контроля версий с поддержкой git создать новый репозиторий;
2. Склонировать репозиторий TelegramBotIntegration в папку с ключом --mirror;
3. Перейти в папку из п. 2;
4. Импортировать клонированный репозиторий в систему контроля версий командой: git push --mirror <Адрес репозитория из п. 1>

Примеры расширения функциональности на проектах

1. Расширение списка сущностей для получения их справочной информации в чат-боте.
2. Структурирование и расширение сбора информации для отправки заявок.
3. Вывод свойств документа при отправке в чат.