Всем привет!
Покажу на примере, как настроить отправку уведомлений о событиях из iTop в Telegram без единой доработки. Женить системы будем с помощью механизма Webhook, который добавлен в iTop с версии 3.0, а для 2.7.x есть в виде дополнения.
Webhook это интеграционный механизм, который позволяет системе выполнять HTTP-запросы к внешним сервисам в качестве реакции на внутренние события. В нашем случае таким внешним сервисом будет Telegram Bot API, а внутренними событиями будут те же триггеры, которые используются для стандартных уведомлений по email в iTop.
У меня в примере используется свежий iTop 3.1.1-1, на других версиях не тестировал, но принципиальных отличий в настройке нет.
Часть 1. Telegram
В телеге нам нужно сделать три простые вещи: узнать свой Chat ID, создать бота для уведомлений, написать нашему боту.
С помощью бота @BotFather создаём бота, который будет принимать сообщение от айтопа и передавать его получателю. После создания бота у нас на руках есть токен 6783469258:AAEEGN8ncrF5sGSyEBak0i-xAyKGXLrj9_U, который в дальнейшем мы будем использовать для настройки веб-хука. Токен этот конфиденциальный, даёт права на управление ботом, так что его нужно держать в секрете.
Следующим шагом нужно узнать идентификатор чата получателя (Chat ID). Идентификатор чата это не то публичное имя пользователя, которое можно найти в интерфейсе телеги, а внутренний номер, скрытый от глаз пользователей. Узнать свой Chat ID можно через специальных ботов, например, @raw_info_bot.
И последнее, что нам нужно сделать здесь, это инициировать переписку с нашим новым ботом. Достаточно просто открыть чат с ботом и выполнить команду
/start. Без этого бот не сможет отправлять нам сообщения.
В дальнейшем получать Chat ID и написать первое сообщение боту должен будет каждый получатель уведомлений.
Часть 2. iTop
Перемещаемся в iTop, прихватив с собой токен бота и идентификатор чата получателя.
Первым делом сохраним в идентификатор чата в одном из полей в карточке Персоны. Я буду использовать существующее поле Мобильный телефон (mobile_phone), но правильнее было бы добавить отдельное поле специально для Chat ID, а затем вывести его на портале в профиле пользователя, чтобы пользователь сам мог указать значение.
Дальше переходим в меню Configuration > Integrations и создаём новый Remote application connection. Тут нужно добавить новый Application type (я назвал просто Telegram), а в поле URL указать адрес, по которому iTop будет обращаться для отправки сообщения. Адрес этот берётся из Telegram Bot API и выглядит так:
https://api.telegram.org/bot<token>/sendMessage, где <token> – это токен нашего бота.
Теперь добавляем сам веб-хук. Делается это аналогично настройке уведомлений по email: мы должны определить триггеры, по срабатыванию которых будет выполняться веб-хук, а также тело отправляемого сообщения.
Переходим в меню Configuration > Notifications и на вкладке Webhook actions (outgoing integrations) создаём новый Webhook call (generic). В Connection и Test connection выбираем созданный на предыдущем шаге Remote application connection, Method и Headers оставляем как есть.
В поле Payload нужно сформировать JSON, который будет передаваться в теле HTTP-запроса. Допустимые параметры и значения JSON можно посмотреть в описании Telegram Bot API для метода sendMessage. Я ограничился минимально необходимыми chat_id и text. Как и при настройке уведомлений по email здесь нам доступны подстановочные шаблоны ($this->attribute$ и др.), которые будут заменены на конкретные значения в момент срабатывания триггера и отправки сообщения. В качестве триггеров я выбрал упоминание персоны в журналах Тикета и Наряда на работу (Trigger on object mention), поэтому помимо стандартных шаблонов $this->attribute$ и $current_contact->attribute$ могу использовать дополнительные $mentioned->attribute$, которые будут заменяться на значения полей упомянутой персоны. В итоге Payload получился таким:
{
"chat_id": "$mentioned->mobile_phone$",
"text": "You have been mentioned by $current_contact->friendlyname$ in $this->ref$"
}
Всё готово! Открываем тикет, пишем сообщение в журнале, упоминая нашу персону, и отправляем. В чат с ботом приходит сообщение.
На вкладке Notifications в тикете видно событие EventWebhook (возможно, придётся обновить страницу браузера).
Но успешно выполненное событие EventWebhook ещё не означает успешную отправку сообщения. Внутри этого события есть полезная информация (ответ API Telegram, фактическое тело запроса и др.) для диагностики и выявления ошибок.
P.S. Как отправить сообщение в группу и как вставить ссылку на тикет в сообщение, догадайтесь сами 