Интеграция с Telegram (бот)

В HelpDeskEddy есть возможность обработки заявок из Telegram бота. Боты — специальные аккаунты в Telegram, созданные для того, чтобы автоматически обрабатывать и отправлять сообщения. Пользователи могут взаимодействовать с ботами при помощи сообщений, отправляемых через обычные или групповые чаты.

 

Видеоинструкция:

 

1) Создание бота

2) Подключение бота к системе

3) Дополнительная информация и возможные ошибки при работе с Telegram

 

Первый шаг: создаем бота.

 

Обратитесь к пользователю @BotFather в Telegram и следуйте его инструкциям:

 

  • Напишите команду /newbot , чтобы создать нового бота. BotFather спросит у вас название бота и предложит придумать name и username.  Имя (name) будет отображаться в контактах и чатах:

 


Username — короткое имя на латинице, которое используется для упоминаний бота и в ссылках на профиль в t.me/

Username должен состоять из букв латинского алфавита, подчёркиваний и цифр и быть длиной от 5 до 32 символов. Также имя пользователя обязательно должно заканчиваться на «bot», например: «test_hde_bot»


 

Далее Вы можете настроить своего бота по желанию: установить картинку, описание и т.д. Полный список возможных команд доступен по команде /help.  

 

Второй шаг: подключение бота к системе.

После создания бота, Вы получите ключ авторизации, который необходим для подключения к вашей системе. Ключ (токен) предоставляет BotFather, вот здесь:

 

Как только вы создали бота и получили свой ключ (токен) авторизации, Вы можете подключить созданного бота к HelpDeskEddy. Для этого перейдите из Управления в раздел "Настройка каналов связи" и нажмите на кнопку "Добавить канал". После чего выберите "Telegram" и департамент к которому будет подключен канал.

 

В поле "Ключ бота" введите API token (который предоставил @Bot_father) и нажмите на кнопку "Синхронизировать и сохранить". В случае корректных настроек в статусе будет отображено что "Соединение успешно установлено":

 

Для того, чтобы бот мог работать как с обычными личными сообщениями, так и с групповыми чатами, в настройках бота необходимо указать:

  • /setjoingroups — определяет, можно ли добавлять вашего бота в группы:

 

По умолчанию этот параметр включен (ENABLED). При необходимости его можно отключить (Disable):

 

  • /setprivacy — переключает режим конфиденциальности в группах (все ли сообщения видит ваш бот в группах).

'Enable' - ваш бот будет получать только те сообщения, которые начинаются с символа '/'
'Disable' - ваш бот будет получать все сообщения, которые люди отправляют в группы:

 

 


Если в группе бот назначен администратором, то он будет считывать все сообщения из группы, независимо от того, какой режим /setprivacy установлен!


 

Таким образом пользователь (клиент), не заходя напрямую в систему, может обращаться в вашу службу поддержки используя привычный для него способ общения через Telegram, а вы, в свою очередь, сможете обрабатывать заявки поступившие из каналов соцсетей и мессенджеров напрямую в HelpDeskEddy.

 

Дополнительная информация

 

1) При редактировании и удалении сообщений в заявке из Telegram в HelpDeskEddy, эти сообщения будут отрекатированы/удалены и на стороне клиента:

 

2) Для Telegram доступны функции упоминания пользователя и цитирования ответов в заявке. Работает это так же, как и в самом мессенджере: выбираете в заявке юзера, нажимаете под его постом кнопку упоминания/ответить на комментарий пишете сообщение:

 

3) Группу в Телеграме можно подключать к каналам (channels), что позволит участникам группы оставлять комментарий под постами в канале. HelpDeskEddy умеет собирать все эти комментарии – для каждого поста создается отдельная заявка с названием сообщения, куда "подтягиваются" все сообщения оставленные пользователями. 

Комментарии под постами на стороне HelpDeskEddy всегда будут отображаться с цитатой, чтобы понимать, является ли это сообщение просто общим комментарием на пост, либо же пользователь отвечает (реплаит) другого пользователя:

 

 

4) HelpDeskEddy умеет определять язык пользователя из Telegram, который обратился в систему впервые.

В момент создания карточки контакта система считает язык клиента из его настроек Telegram и если там стоит, например, английский, то этот же язык будет указан в его карточке контакта в HelpDeskEddy. Чтобы функционал работал корректно, соответствующий язык в системе обязательно должен быть включен в меню "Язык". 

 

5) Если пользователь поставит реакцию на сообщение в Telegram через некоторое время после его отправки, то мессенджер повторно отправит это сообщение в заявку в виде ответа, т.к. это считается отредактированным сообщением, а они приходят в хелпдеск в виде отдельных ответов.

Также стоит учитывать эту особенность интеграции с Telegram и в закрытых заявках: реакция пользователя на пост в уже закрытой заявке спровоцирует создание новой заявки с ответом, на который поставлена реакция. 

 

6) В настройках бота можно запретить его добавление в сторонние групповые чаты чтобы избежать спам и другие проблемы.

После того, как вы подключите своего бота к HelpDeskEddy, перейдите в настройки в чате с @BotFather и запретите дальнейшее добавление бота в группы. Сделать это можно с помощью команды Allow Groups - Turn groups off:

 

После включения данного запрета бот будет автоматически выходить из каналов, в которые его добавляют. 

Но что делать, если бота уже добавили в ненужную группу? Для этого можем предложить воспользоваться подручными инструментами системы. Перейдите в "Диспетчер" и создайте следующее правило, которое будет срабатывать при создании новой заявки из группового чата Telegram:

 

И затем будет выполнять запрос, который автоматически выкинет бота из группы:

 

Содержимое запроса:

URL: https://api.telegram.org/bot[bot-key]/leaveChat,

где [bot-key] - API ключ вашего ТГ бота

Тело запроса:

{
 "chat_id": "{ meta_chat_id }"
}

Далее алгоритм будет следующим:

  1. удалите заявки, которые поступили из "ненужных" чатов;
  2. включите правило диспетчера;
  3. подождите, пока появится новая заявка из "ненужного" чата - сработает правило и заставит бота покинуть группу;
  4. не забудьте выключить правило после того, как бот покинет все лишние группы.

 

Возможные ошибки

 

Иногда при работе с каналом вы можете столкнуться с некоторыми ошибками (сообщение не было доставлено, обрыв соединения и т.д.). Так как интеграция двухсторонняя, то на стороне Telegram могут быть как определенные ограничения на отправку, так и перебои работы в целом. В логах канала можно ознакомиться, с чем было связана та или иная проблема, а также просмотреть код её ошибок. Помимо этого, информация о том, что сообщение было не доставлено, а также причина этого, отображается возле самого сообщения:

 

Ниже представлен список некоторых наиболее популярных проблем и причины их возникновения:

  1. 413 Request Entity Too Large - означает что вложение, отправленное из системы, превышает максимально допустимый размер (50MB);
  2. Error 500 говорит о том, что возникла какая-то неисправность со стороны сервера Telegram. Попробуйте повторить попытку через некоторое время;
  3. 403 FORBIDDEN - нарушение конфиденциальности. Например, попытка написать сообщение тому, кто заблокировал вашего бота.

  • В Telegram доступен метод getWebhookInfo для получения текущего состояния бота (его статус), не требующий параметров. В случае успеха возвращает объект WebhookInfo. Если бот использует getUpdates, возвращается объект с пустым полем url.

Например: https://api.telegram.org/bot123456:ABC-DEF1234/getWebhookInfo

где 123456:ABC-DEF1234 – токен вашего бота. Подробнее.

 

Если пользователь перейдёт по указанной ссылке и нажмёт кнопку "Старт" в Telegram, то в заявке в HelpDeskEddy передастся весь текст после "start=" в виде комментария, который можно обработать как вручную, так и автоматически, при помощи правил диспетчера (дополнительное условие "Содержимое последнего комментария"):