Общая логика настройки уведомлений о новых обращениях и ответов клиентов описана тут. Другие инструкции:
звуковые и браузерные уведомления (по 2 минуты на выполнение)
уведомления на почту (2 минуты на выполнение)
уведомления в Slack (10 минут на выполнение)
уведомления в Mattermost (5 минут на выполнение)
уведомления в Discord (5 минут на выполнение)
Для получения уведомлений в Телеграме необходимо создать Телеграм-бота и настроить правила в Омнидеске. Видеоверсия инструкции по настройке тут.
Создание бота в Телеграме
Создайте отдельного бота в Телеграме для отправки через него уведомлений. Вы сможете использовать одного и того же бота для отправки уведомлений разным сотрудникам и в разные группы. Обратите внимание, что использовать для уведомлений телеграм-бота, который у вас подключен как канал для связи с клиентами, не получится.
1. Создайте бота в Телеграме. Для этого:
a) в строке «Поиск» введите @BotFather или перейдите по ссылке t.me/botfather;
б) нажмите кнопку «Start» / «Запустить» или наберите команду /start;
в) выберите команду /newbot в ответном сообщении от бота или в списке команд в меню;
г) укажите имя вашего нового бота латиницей, а затем — его юзернейм, который должен заканчиваться на «bot» слитно или через нижнее подчеркивание.
После успешного создания бота вы получите API-токен бота, который понадобится для настройки правил в Омнидеске.
Учтите, что Telegram не позволяет боту писать в адрес пользователя первым. Чтобы получать от бота уведомления в личную переписку, обязательно отправьте ему хотя бы одно сообщение и не забудьте попросить об этом коллег, для которых настраиваете уведомления. Найти бота можно через поиск или перейдя по ссылке в сообщении от @botfather.
2. Для настройки уведомлений также потребуется Chat ID.
На этом этапе решите, кому бот будет отправлять уведомления: отдельному пользователю или в группу.
Получить Chat ID можно несколькими способами:
В случае с пользователем и обычной группой Chat ID совпадает с User ID или, соответственно, с Group ID. Поэтому можно просто взять его из строки браузера в веб-клиенте Телеграма A-версии. После авторизации откройте нужную группу, чат с коллегой или «Saved Messages», если настраиваете уведомления для самого себя, и скопируйте цифры после символа #. Способ не подойдет для супергрупп;
спросить у бота, например, у @username_to_id_bot или @myidbot. Обратите внимание, что эти боты, никак не связанные с Омнидеском, так что мы не можем гарантировать их работоспособность;
через 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 этой инструкции.
Пример отображения:
9. Отправляйте уведомления в конкретную тему группы
Для отправки уведомлений в конкретную тему группы понадобится “message_thread_id”.
Важно: При включении тем в настройках группы она преобразуется в супергруппу, а ее Group ID и Chat ID навсегда меняются на другой. Если вы получали уведомления в группу и затем активировали темы, вам будет недостаточно получить только ID конкретного треда. Потребуется обновить и Chat ID группы, указанный в коде запроса в вашем правиле в Омнидеске. ↓
Chat ID для супергруппы рекомендуем получать через json-ответ API Телеграма, как это описано выше. Спросить ID у одного из специализированных ботов также можно, а вот просто скопировать цифры из адресной строки веб версии «А» Telegram уже не получится, так как в ней отображается именно Group ID.
Если способ с обращением к API Телеграм вам кажется слишком сложным, а сторонним ботам вы не доверяете, можете попробовать «сконструировать» Chat ID по следующей формуле: к ID группы, который отображается в браузерной строке добавьте «100» между “-” и самим ID. Если Используете ссылку на тему в группе, доступную в том числе и в приложении для смартфонов, то добавьте к полученным цифрам «-100».
К примеру, в строке браузера у вас отображается https://web.telegram.org/a/#-6554553552_13. ID группы тут «-6554553552», а chat_id в этом случае -1006554553552.
Если используете ссылку на тему из мобильного приложения, то она, обычно, выглядит так: https://t.me/c/6554553552/13. Chat ID в этом случае будет выглядеть как «-1006554553552».
На данный момент префикс, используемый при генерации Chat ID для супергруппы, именно «100», но в будущем этот параметр может измениться, и тогда описанный нами метод перестанет работать.
Если вы настроили уведомления по инструкции, но не получаете их, проверьте, что используете корректный Chat ID, другим из описанных в начале этой инструкции способов.
Получить ID нужной темы можно через ссылку на нее в самом Telegram. Нажмите на название темы и скопируйте цифры после «/». К примеру, для https://t.me/supergroupname/10 message_thread_id равен 10;
Полученный message_thread_id укажите в тексте кода запроса. Пример:
{
"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",
"message_thread_id":[полученный_id_темы],
"reply_markup" : {
"inline_keyboard": [
[{"text":"Ответить", "url":"[case_url]"}]
]
}
}
Пример отображения:
