Общая логика настройки уведомлений о новых обращениях и ответов клиентов описана тут. Другие инструкции:
звуковые и браузерные уведомления (по 2 минуты на выполнение)
уведомления на почту (2 минуты на выполнение)
уведомления в Slack (10 минут на выполнение)
уведомления в Mattermost (5 минут на выполнение)
уведомления в Discord (5 минут на выполнение)
Для получения уведомлений в Телеграме необходимо создать Телеграм-бота и настроить правила в Омнидеске. Видеоверсия инструкции по настройке тут.
Создание бота в Телеграме
Создайте отдельного бота в Телеграме для отправки через него уведомлений. Вы сможете использовать одного и того же бота для отправки уведомлений разным сотрудникам и в разные группы. Обратите внимание, что использовать для уведомлений телеграм-бота, который у вас подключен как канал для связи с клиентами, не получится.
1. Создайте бота в Телеграме. Для этого:
a) в строке «Поиск» введите @BotFather или перейдите по ссылке t.me/botfather; б) нажмите кнопку «Start» / «Запустить» или наберите команду /start; в) выберите команду /newbot в ответном сообщении от бота или в списке команд в меню; г) укажите имя вашего нового бота латиницей, а затем — его юзернейм, который должен заканчиваться на «bot» слитно или через нижнее подчеркивание.
После успешного создания бота вы получите API-токен бота, который понадобится для настройки правил в Омнидеске.
Учтите, что Telegram не позволяет боту писать в адрес пользователя первым. Чтобы получать от бота уведомления в личную переписку, обязательно отправьте ему хотя бы одно сообщение и не забудьте попросить об этом коллег, для которых настраиваете уведомления. Найти бота можно через поиск или перейдя по ссылке в сообщении от @botfather.
2. Для настройки уведомлений также потребуется Chat ID.
У чата с отдельным пользователем и группового будут разные ID, поэтому на этом этапе решите, кому бот будет отправлять уведомления: отдельному пользователю или группе пользователей.
Получить Chat ID можно несколькими способами:
спросить у бота, например, у @username_to_id_bot;
скопировать из строки браузера в веб-клиенте Телеграма A-версии. После авторизации откройте нужную группу, чат с коллегой или «Saved Messages», если настраиваете уведомления для самого себя, и скопируйте цифры после символа #;
через json-ответ API Телеграма.
Последний способ опишем подробнее. Перейдите по ссылке https://api.telegram.org/bot[токен_бота]/getUpdates (переменную [токен_бота] вместе с квадратными скобками замените на API-токен созданного вами бота). Вы должны получить ответ: «{"ok":true,"result":[]}».
а. Для получения ID чата с пользователем отправьте в адрес созданного вами бота несколько сообщений. Затем вернитесь к вкладке, открытой на предыдущем шаге по ссылке https://api.telegram.org/bot[токен_бота]/getUpdates, обновите страницу и скопируйте полученный id.
б. ID группового чата отобразится по ссылке https://api.telegram.org/bot[токен_бота]/getUpdates сразу после добавления бота в группу. Обновите страницу и скопируйте полученный id. На ID чата с группой указывает знак минус (“-”) перед цифровым кодом.
Создание правил в Омнидеске
3. Создайте в Омнидеске правила, которые будут отправлять уведомления в Телеграм. Перейдите в аккаунт администратора — раздел «Каналы» — подраздел «Правила».
а. Для получения уведомлений в Телеграм о поступлении новых обращений создайте правило для входящих обращений:
В блоке «производить действие» выберите вариант «Выполнить вебхук», затем укажите метод POST. В поле «URL для отправки запроса» вставьте следующую ссылку, заменив в ней переменную [токен_бота] вместе с квадратными скобками на API-токен созданного вами бота:
https://api.telegram.org/bot[токен_бота]/sendMessage
Ниже выберите вариант «Кастомный запрос» в формате JSON и добавьте код запроса с нужными вам переменными. Переменную [полученный_id] вместе с квадратными скобками замените на ID пользователя или группы, который вы получили в пункте 2.
{
"chat_id": [полученный_id],
"parse_mode": "HTML",
"text": "<i>Новое обращение</i>\n\n<b>#[case_number]: [case_subject]</b>\n[user_full_name]: [user_email]\n\n[case_description|text]",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
Уведомление с использованием приведенного выше кода будет выглядеть так:
б. Для получения уведомлений в Телеграм о поступлении новых ответов в обращениях и чатах создайте правило для измененных обращений:
В блоке «производить действие» выберите вариант «Выполнить вебхук», затем укажите метод POST. В поле «URL для отправки запроса» вставьте следующую ссылку, заменив в ней переменную [токен_бота] вместе со скобками на API-токен созданного вами бота:
https://api.telegram.org/bot[токен_бота]/sendMessage
Ниже выберите вариант «Кастомный запрос» в формате JSON и добавьте код запроса с нужными вам переменными. Переменную [полученный_id] вместе с квадратными скобками замените на ID пользователя или ID группы, который вы получили в пункте 2.
{
"chat_id": [полученный_id],
"parse_mode": "HTML",
"text": "<i>Новый ответ в обращении</i>\n\n<b>#[case_number]: [case_subject]</b> \n[user_full_name]: [user_email]\n\n[last_message|text]",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
Уведомление с использованием приведенного выше кода будет выглядеть так:
На этом настройка закончена, теперь вы будете получать уведомления в Телеграм и не пропустите новые сообщения от пользователей.
PRO подсказка: В новых чатах тема обращения формируется на основе первого сообщения от пользователя:
иногда такое сообщение может быть довольно длинным и ломать верстку вашего уведомления;
текст самого сообщения в таком случае будет дублировать тему.
Чтобы избежать этого, лучше создавать отдельные правила для входящих обращений по каналу email и по синхронным каналам, а в тексте кода запроса для уведомления о новых чатах не использовать переменную [case_subject].
Дополнительные возможности
4. Добавьте в код вебхука нужные вам переменные с данными из Омнидеска (группу обращения, телефон пользователя, компанию, текст заметки и т. п.), чтобы уведомления максимально отвечали вашим задачам. Кроме того, вы также можете самостоятельно выбрать отображение элементов, которое вам больше подходит.
Пример кода и отображения такого уведомления в Telegram:
{
"chat_id": [полученный_id],
"parse_mode": "HTML",
"text": "[last_message|text]\n\n<b>[user_full_name]</b> написал в обращении #[case_number]: <b>[case_subject]</b>\n\n<i>Почта: </i>[user_email]\n<i>Группа: </i>[case_group]\n<i>Приоритет: </i>[case_priority]\n\n<a href=\"[case_url]\">Ответить на обращение</a>",
"disable_web_page_preview": "True"
}
5. Используйте дополнительные параметры в коде вебхука:
а) “disable_notification” — отправляет «тихие» уведомления, которые не будут отвлекать вас от основных задач;
б) "protect_content" — отключает возможность копировать или пересылать уведомления;
в) “message_thread_id” — отправляет уведомления в указанную тему супергруппы. Чтобы получить ID нужной темы, нажмите на название темы и скопируйте цифры после «/». К примеру, для https://t.me/supergroupname/10 message_thread_id равен 10;
г) [переменная|text] — преобразует html-форматирование в простой текст;
д) [переменная|limit100] — обрезает уведомление до указанного количества символов. Учтите, что Telegram не позволяет отправлять сообщения длиной более 4096 символов в кодировке UTF-8.
Пример кода с использованием перечисленных параметров:
{
"chat_id": [полученный_id],
"parse_mode": "HTML",
"text": "<i>Новый ответ в обращении</i>\n\n<b>#[case_number]: [case_subject]</b> \n[user_full_name]: [user_email]\n\n[last_message|limit350]",
"disable_web_page_preview": "True",
"disable_notification": "True",
"protect_content": "True",
"message_thread_id":[полученный_id_темы],
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
В коде замените [полученный_id_темы] на ID вашей темы и укажите нужное вам количество символов.
6. Добавляйте собственные кнопки, чтобы открывать нужные вам ссылки. К примеру, можно быстро переходить к профилю пользователя в Омнидеске, в вашу базу знаний, к списку всех обращений и т. д.
Пример кода в HTML и отображения такого уведомления в Telegram:
{
"chat_id": [полученный_id],
"parse_mode": "HTML",
"text": "<b>#[case_number]: [case_subject]</b>\n<i>[user_full_name]</i>: [user_email]\n\n[last_message|text]",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Профиль пользователя", "url":"https://[domain].omnidesk.ru/staff/users/record/[user_id]"},
{"text":"База знаний", "url":"https://[domain].omnidesk.ru/knowledge_base/"}],
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
В ссылке на вашу базу знаний и профиль пользователя укажите название своего поддомена на Омнидеске вместо [domain].
Пример кода в Markdown V2 и отображения такого уведомления в Telegram:
{
"chat_id": [полученный_id],
"parse_mode": "MarkdownV2",
"text": "`[case_number]`: *[case_subject]*\n[user_full_name]: `[user_email]`\n\n`[last_message|text]`",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Профиль пользователя", "url":"https://[domain].omnidesk.ru/staff/users/record/[user_id]"}, {"text":"База знаний", "url":"https://[domain].omnidesk.ru/knowledge_base/"}],
[{"text":"Ответить", "url":"[case_url]"}]
]
}
В ссылке на вашу базу знаний и профиль пользователя укажите название своего поддомена на Омнидеске вместо [domain].
7. Телеграм поддерживает разные форматы разметки текста. Выберите нужный, указав одну из опций параметра “parse_mode”:
a. HTML — этот тип форматирования мы использовали для примеров в основной части статьи по настройке уведомлений.
б. Markdown V2 — актуальный синтаксис, рекомендованный для использования Телеграмом.
В этом языке разметки есть ограничение на передаваемые символы — такие как '_', '*', '[', ']', '(', ')', '~' и т. д. Текст или переменные, которые их содержат, нужно оформлять в виде `кода`, то есть использовать с двух сторон обратные одинарные кавычки, или backticks (юникод U+0060). Обратите внимание, что в примерах кода мы не обрамляем такими кавычками переменные [case_subject] и [user_full_name]. Если в них встретится один из таких символов, уведомление не будет доставлено в Телеграм. Подробнее — в документации Телеграма;
Номер обращения и почту в разметке Markdown V2 можно скопировать в один клик.
Пример кода и отображения такого уведомления в Telegram:
{
"chat_id": [полученный_id],
"parse_mode": "MarkdownV2",
"text": "`[case_number]`: *[case_subject]*\n[user_full_name]: `[user_email]`\n\n`[last_message|text]`",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
в. Markdown в Telegram считают устаревшим, но оставили поддержку этого формата для обратной совместимости.
Пример кода и отображения такого уведомления в Telegram:
{
"chat_id": [полученный_id],
"parse_mode": "Markdown",
"text": "*#[case_number]: [case_subject]*\n[user_full_name]: [user_email]\n\n[last_message|text]",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
г. Entities — используется как альтернатива parse_mode. Позволяет передать только одну специальную сущность. Необходимо знать точную длину сообщения. Подойдет, если вы хотите использовать специальные возможности или настроить минималистичные уведомления.
Пример кода и отображения такого уведомления в Telegram:
{
"chat_id": [полученный_id],
"text":"Новый ответ в обращении: [case_number]",
"entities": [
{
"offset": 0,
"length": 35,
"type": "text_link",
"url":"[case_url]"
},
{
"offset": 0,
"length": 35,
"type": "bold"
}
],
"disable_web_page_preview": "True"
}
8. Добавьте упоминание сотрудника через @username. Если хотите упоминать именно ответственного, то:
а. Для каждого из сотрудников создайте правило для входящих обращений, которое будет отправлять уведомление с упоминанием ответственного в Telegram при поступлении нового обращения:
Используйте следующий текст кастомного запроса:
{
"chat_id": [полученный_id],
"parse_mode": "HTML",
"text": "<i>Новое обращение</i>\n\n<b>#[case_number]: [case_subject]</b>\nОтветственный: @[юзернейм]\nПриоритет: [case_priority]\n\n«[case_description|text]»",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
Пример отображения:
PRO подсказка: Для более быстрого добавления правил используйте функцию дублирования и затем редактируйте в правилах только данные упоминаемого сотрудника. Объедините правила, созданные для всех сотрудников, в одну группу.
Разместите созданную группу правил после правила, которое назначает ответственного в обращении. К примеру, чтобы равномерно назначать ответственными в обращении всех доступных сотрудников, кроме руководителя и тех, у кого доступ «только просмотр», можете использовать такое правило:
б. Для отправки уведомления с упоминанием ответственного в Telegram при поступлении нового ответа в обращении также понадобятся отдельные правила для каждого сотрудника, теперь уже для измененных обращений. Их мы также рекомендуем объединить в группу. Вот пример такого правила:
Используйте следующий текст кастомного запроса:
{
"chat_id": [полученный_id],
"parse_mode": "HTML",
"text": "<i>Новый ответ в обращении</i>\n\n<b>#[case_number]: [case_subject]</b>\nОтветственный: @[юзернейм]\nПриоритет: [case_priority]\n\n«[last_message|text]»",
"disable_web_page_preview": "True",
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
Обратите внимание, что для получения текста ответа в обращении в параметре “text” нужно использовать переменную [last_message|text].
Пример отображения:
PRO подсказка: Чтобы отобразить полное имя ответственного вместо username, используйте следующую конструкцию:
Ответственный: <a href=\"tg://user?id=[id_пользователя]\">[assigned_full_name]</a>
Как получить ID пользователя, подробно описано в пункте 2 этой инструкции.
Пример отображения:
