# Плагин TelegramS

## О плагине

Плагин предназначен для интеграции BGERP с мессенджером Telegram и предоставляет функционал отправки текстовых, Markdown и HTML сообщений в:

- личные чаты пользователей BGERP;

- чаты групп, привязанных к процессам, либо жёстко заданных в JEXL.

## Настройка

Убедитесь в наличии конфигурации с активированным плагином.

В BotFather создать своего бота, прописать его название и токен в конфигурации, например:

    telegram:botStart=1

    # в BotFather создать своего бота, прописать его название и токен
    telegram:token=842416376:AAFGsYLCgqG6eKcsZPy6gLCjge_klgUiWHE
    telegram:botName=TestBgErp_bot

    # настройки прокси, в случае необходимости
    #telegram:proxyHost=111.223.75.181
    #telegram:proxyPort=8888
    # SOCKS5 , HTTP
    #telegram:proxyType=SOCKS5

### Тип процесса

В конфигурации типа процесса может быть настроена автоматизация работы с Telegram с помощью JEXL скрипта простого обработчика событий, вызывающего объект telegram класса org.bgerp.plugin.telegram.ExpressionObject с функциями API плагина.

### Отправка в группу

Добавьте бот в члены группы. Получите Сhat ID группы, открыв её в https://web.telegram.org

Пример отправки непосредственно на Сhat ID:

    STATUS_DONE_ID=4

    GROUP_CHAT_ID=-1001307600319

    onProcessEvent.{@inc:cnt}.events=statusChanged:{@STATUS_DONE_ID}
    onProcessEvent.{@cnt}.doExpression=<<END
        executorsList = u.getObjectList(ctxUserList, process.getExecutorIdsWithRole(0));
        from = u.toString(executorsList);

        text = "Принято изменение [" + process.getId() + "](https://team.bgerp.org/open/process/" + process.getId() + ")";
        text += " от " + from + ":" + NEW_LINE;
        text += telegram.escapeMarkdown(process.getDescription());

        telegram.sendMessage("{@GROUP_CHAT_ID}", text, "MarkdownV2");
    END

Сhat ID может быть сохранён в текстовом параметре процесса, чей ID указывается в ключе конфигурации, например:

    # параметр процесса в котором будет храниться Chat ID
    telegram:processParamId=91

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

    onProcessEvent.{@inc:cnt}.events=statusChanged
    onProcessEvent.{@cnt}.doExpression=<<END
        telegram.sendMessageForProcess(process, "Изменился статус");
    END

### Отправка пользователям

Сhat ID для пользователя в текстовом параметре, который должен быть указан в конфигурации, пример:

    # параметр пользователя в котором будет храниться Сhat ID
    telegram:userParamId=90

    Необязательные параметры (позволяют переопределить текст сообщений бота, к примеру для локализации текста под свой язык):
    # ошибка неверный пароль
    telegram:msgWrongPassword=неверный пароль
    # текст после ввода команды /start
    telegram:msgAskLogin=введите свой логин
    # текст запроса пароля
    telegram:msgAskPassword=введите свой пароль
    # текст успешной привязки Сhat ID к пользоватею
    telegram:msgLinkChange=учетная запись обновлена
    # стандартный ответ на текст вне комманд
    telegram:msgDefaultAnswer=введите /login или /getid
    # тест команды помощи
    telegram:msgUrlHelp=Для получения помощи, обратитесь к разделу справки корпоративного портала (раздел BGERP)

Каждый пользователь для получения увемлений должен найти в Telegram бота и начать с ним диалог, содержащий команду /login

Описание команд бота:

- /getid - команда получения Сhat ID для пользователя

- /login - бот запросит логин и пароль от пользователя BGERP, а затем произведет заполнение параметра пользователя Сhat ID

- /help - команда вывода текста из конфигурации плагина (MsgUrlHelp)

- /start - команда вывода текста по умолчанию из конфигурации (msgDefaultAnswer)

Пример отправки уведомления исполнителям процесса о смене статуса:

    onProcessEvent.{@inc:cnt}.events=statusChanged
    onProcessEvent.{@cnt}.doExpression=<<END
        telegram.sendMessage(process, "Изменился статус");
    END