Уведомления в Телеграм

Последние изменения: 18.04.2024

Общая логика настройки уведомлений о новых обращениях и ответов клиентов описана тут. Другие инструкции:

звуковые и браузерные уведомления (по 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]"}]
     ] 
  }

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]"}]
     ] 
  }
}

Пример отображения:

Помогла ли вам статья?