Интерактивные оповещения Telegram

Функционал Telegram API даёт возможность создавать кнопки к сообщениям. Бот оповещений поддерживает общение с сервисами посредством использования кнопок.

Текстовая разметка

Текстовая разметка располагается в конце отправляемого сообщения. Код разметки следует вводить в фигурных скобках с собачкой @{ /*код разметки*/ }@. ## Закрывающая фигурная скобка с собачкой должна являтся концом сообщения, дальше него не должны быть какие либо символы (включая пробелы, перенос строки, и другие специальные символы).

Для корректной работы функционала в разметке запрещается использовать сочитания символов @{ и }@

Пример сообщения с разметкой

Процесс: №1234567
Тип: Заявка на проведение ППР NEW
Статус: Отмена
@{
[Отправить в обработку](setStatus:1234567:15)
[Ссылка на процесс](https://erp.core.ufanet.ru/user/process#1234567)
}@

При отправке данного сообщения пользователь получит уведомление:

telegram interactive notification example1

Кнопки

Вид кнопок

Кнопки имеют следующий вид

[название кнопки](команда с аргументами / ссылка)

Пример:
// Кнопка "отправить в обработку" выполняет команду setStatus с аргументами 1234567 и 15
[Отправить в обработку](setStatus:1234567:15)

// Кнопка-ссылка "ссылка на процесс". Ссылка должна начинаться с "http" либо "https"
[Ссылка на процесс](https://erp.core.ufanet.ru/user/process#1234567)

Между скобками кнопки не должно быть лишних символов (в том числе пробелов)

// Нельзя
[кнопка1]1234(действие1)

// Нельзя
[кнопка1] (действие1)

// Правильно
[кнопка1](действие1)

В названиях кнопок нельзя использовать знаки квадратных скобок [ ] а в действиях круглых скобок ( ). Также лучше не оставлять лишних пробелов, чтобы команда распозналась

// Не делайте так
[Скобкануть]](смешно))) )

// Правильно
[Скобкануть](не_смешно_но_правильно)

Положение кнопок

Разметка поддерживает разметку положения кнопок, она совпадает со строковым положением.

Разметка кнопок на новой линии = Кнопки сообщения на новой линии

[Действие1](setStatus:1234567:15)[Действие2](setStatus:1234567:20)
[Действие3](setStatus:1234567:10)

telegram interactive notification example2

Скрытие кнопок после действия

Разметка поддерживает функцию скрытия действий после их выполнения.

Для этого нужно обернуть кнопку в треугольные скобки.

Данная функция не поддерживается ссылками, и не стоит проверять это!!!

<[Действие1](setStatus:1234567:15)><[Действие2](setStatus:1234567:20)>
[Действие3](setStatus:1234567:10)

Теперь после нажатия на Действие1 при успешной операции кнопка сообщения скроется.

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

//Можно так
<[Действие1](setStatus:1234567:15)[Действие2](setStatus:1234567:20)>
[Действие3](setStatus:1234567:10)

//Можно так
<[Действие1](setStatus:1234567:15)
[Действие2](setStatus:1234567:20)>[Действие3](setStatus:1234567:10)

Действия

Установить статус (setStatus)

Данное действие позволяет установить статус процесса от имени пользователя через телеграм уведомление.

[ButtonName](setStatus:processId:newStatusId)

ButtonName: Название кнопки действия
processId: ID процесса
newStatusId: ID нового статуса для процесса

Пример:
[Отправить в обработку](setStatus:1234567:15)
//При нажатии на клавишу "Отправить в обработку" процесс с id 1234567 сменит свой статус на 15(В обработке)

Примеры

Пример создания интерактивного уведомления с помощью автоматизации правил

Данное правило отправляет создателю процесса уведомление о смене статуса с кнопкой отменить процесс

telegram interactive notification example3

Текст сообщения

Процесс №{{process.id}}
Тип: {{process.typeTitle}}
Статус: {{process.statusTitle}}
@{
<[Отменить процесс](setStatus:{{process.id}}:20)>
[Ссылка на процесс](https://erp.core.ufanet.ru/user/process#{{process.id}})
}@

Пример кода в Jexl

Пример с onProcessEvent.doExpression. При смене статуса оповещает пользователя и даёт ему возможность изменить статус на Отправить в обработку либо Отменить в зависимости от текущего статуса процесса

onProcessEvent.{@cnt}.events=statusChanged:10,15,244,17,20,8,22,13
onProcessEvent.{@cnt}.doExpression=<<END
    var pvdao = new('ru.bgcrm.dao.ParamValueDAO', conSet.getConnection());
    var telegramId = pvdao.getParamText(user.getId(), 1799);
    var processId = process.getId().toString();

    changeProcessStatusMsg = "\u270F Процесс №" + processId + NEW_LINE;
    changeProcessStatusMsg += "\uD83D\uDD16 Тип: " + process.getTypeTitle() + NEW_LINE;
    changeProcessStatusMsg += "\uD83D\uDD16 Статус: " + process.getStatusTitle() + NEW_LINE;

    /*    TELEGRAM КНОПКИ    */
    changeProcessStatusMsg += "@{" + NEW_LINE;

    if (process.getStatusId() == 20) {
        changeProcessStatusMsg += "<[Отправить в обработку](setStatus:" + processId + ":15)>" + NEW_LINE;
    } else if (process.getStatusId() == 15) {
        changeProcessStatusMsg += "<[Отменить](setStatus:" + processId + ":20)>" + NEW_LINE;
    }

    changeProcessStatusMsg += "[Ссылка на процесс](http://erp.core.ufanet.ru/user/process#" + processId + ")" + NEW_LINE;

    changeProcessStatusMsg += "}@";

    ru.bgcrm.plugin.ufanet.telegram.core.TelegramBots.getNotifierBot().sendMessage(telegramId, changeProcessStatusMsg, 'Markdown');

END

Пример с onProcessEvent.commands. При смене статуса оповещает создателя процесса и даёт ему возможность сменить статус.

msgNewDesc="Процесс №".concat(process.getId().toString()).concat( NEW_LINE )
msgNewDesc+=.concat("\uD83D\uDD16 Тип: _").concat(process.getTypeTitle()).concat("_").concat(NEW_LINE)
msgNewDesc+=.concat("\uD83D\uDD16 Статус: _").concat(process.getStatusTitle()).concat("_").concat(NEW_LINE)
### TELEGRAM КНОПКИ
msgNewDesc+=.concat("@{").concat(NEW_LINE)
msgNewDesc+=.concat("<[В обработку](setStatus:").concat(process.getId().toString()).concat(":15)").concat(NEW_LINE)
msgNewDesc+=.concat("[Отменить](setStatus:").concat(process.getId().toString()).concat(":20)>").concat("[Ссылка на процесс](http://erp.core.ufanet.ru/user/process#").concat(process.getId().toString()).concat(")").concat(NEW_LINE)
msgNewDesc+=.concat("}@")
{@inc:cnt}
onProcessEvent.{@cnt}.events=statusChanged:10,15,244,17,20,8,22,13
onProcessEvent.{@cnt}.commands=telegramNotifyCreateProcessUser:1799:Markdown:msgNewDesc

Конфигурация

api.telegrab.enable=true            # Включение Telegrab (по умолчанию: false)
api.telegrab.useAmq=true            # Использование очереди amq (по умолчанию: false)
api.telegrab.amqQueue               # Название очереди с общением с сервисом телеграма (по умолчанию: "tg.telegrab")
api.telegrab.amqReceiver            # Имя телеграм сервиса в очереди (по умолчанию: "telegram")
api.telegrab.telegramParamId=111    # Параметр пользователя с id телеграм (по умолчанию: 1799)

# Если используется очередь, в системе должна быть конфигурации очереди AMQ

amq.host=tcp://localhost:61616      # Имя хоста
amq.username=admin                  # Логин
amq.password=admin                  # Пароль

# Помимо этого должен быть определен url telegram сервиса
api.telegram-service.url=           # Url для общения с телеграм сервисом

Для работы полного функционала (в том числе интерактивных сообщений), должна быть определена очередь AMQ, а также флаг api.telegrab.useAmq должен быть установлен в значение true