Telegram

Telegram — мессенджер, имеющий веб версию, десктоп версию, а также версию для мобильных устройств. Имеет встроенный функционал чат-ботов.

Подключение

1. Создание бота на стороне Telegram

В первую очередь нужно произвести конфигурацию на стороне Telegram.

1. Откройте Telegram и авторизуйтесь.

2. Найдите в поиске бота “BotFather”.

3. .

4. Создайте бота в Telegram:

5. 1. Отправьте боту BotFather команду /newbot.

   2. В ответ на сообщение бота введите желаемое имя вашего бота.

   3. 

   4. Отправьте желаемый идентификатор бота. Он должен быть уникальным среди всех существующих ботов в Telegram и заканчиваться на “bot”. Например, My_new_telegram_bot_username_bot.

   5. 

   6. Если отправленный идентификатор бота соответствует требованиям, вы получите сообщение об успешном создании бота. В сообщении будет указана ссылка на вашего бота в Telegram и токен доступа к боту.

   7. 

   8. Скопируйте в удобное место токен доступа.

   9. 

   10. Настроить аватар, описание, и прочие параметры бота вы можете через бота BotFather.

На этом конфигурация Бота в Telegram завершена.

2. Конфигурация канала агента в Платформе

Агенту необходимо создать и настроить Канал Проекта с коннектором “Telegram”.

1. Кликните по кнопке настроек Агента.
2. Нажмите кнопку Add channel.
3. Откроется панель выбора Конечный канал.
4. Выберите Telegram.

5. Откроется панель создания Канал Проекта.
6. По необходимости пропишите заголовок для данного Канал Проекта в поле названия с плейсхолдером New channel.
7. Вставьте скопированный ранее токен в полеTelegram bot token.
8. По необходимости переключите тумблер Receive service messages, чтобы получать Сервисные сообщения канала.
9. Для сохранения Канал Проекта без его активации, нажмите кнопку CREATE.
10. Для сохранения и активации Канал Проекта, нажмите кнопку CREATE & ACTIVATE.
11. 1. Канал Проекта будет сохранен и активирован, если:

    2. 1. Агент обучен;

       2. токен в поле Telegram bot token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

       3. будет доступен адрес Канал Проекта;

       4. удастся зарегистрировать вебхук канала.

    3. Канал Проекта будет сохранен, но не активирован, если одно или больше условий не будут выполнены.

12. Для отмены создания Канал Проекта нажмите кнопку CANCEL.

Редактирование и удаление Канала Агента

Для редактирования Канал Проекта, необходимо кликнуть по его иконке на карточке Агента.

1. Чтобы отредактировать значение в любом поле, кликните по полю и впишите новое значение.

2. Чтобы применить изменения к активированному Канал Проекта, нажмите кнопку APPLY.
3. 1. Изменения будут применены, если:

   2. 1. Агент обучен;

      2. токен в поле Telegram bot token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

      3. будет доступен адрес Канал Проекта;

      4. удастся зарегистрировать вебхук канала.

   3. Изменения не будут применены, если одно или больше условий не будут выполнены.

4. Чтобы деактивировать Канал Проекта, нажмите кнопку DEACTIVATE.
5. Чтобы применить изменения к деактивированному Канал Проекта, нажмите кнопку SAVE.
6. Чтобы применить изменения и активировать Канал Проекта, нажмите кнопку SAVE & ACTIVATE.
7. 1. Изменения будут применены и Канал Проекта будет активирован, если:

   2. 1. Агент обучен;

      2. токен в поле Telegram bot token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

      3. будет доступен адрес Канал Проекта;

      4. удастся зарегистрировать вебхук канала.

   3. Изменения будут применены, но Канал Проекта не будет активирован, если одно или больше условий не будут выполнены.

8. Чтобы отменить внесение изменений, нажмите кнопку CANCEL.
9. Чтобы удалить Канал Проекта, нажмите кнопку DELETE.

Общение

Общение в групповых чатах Telegram

1. Бот может быть добавлен в групповой чат Telegram и обрабатывать сообщения и события этого чата.

2. Чтобы Бот обрабатывал все сообщения, отправляемые в группу, необходимо обеспечить ему доступ ко всем сообщениям, выключив настройку Group Privacy:

3. 1. Перейти в BotFather;

   2. Написать команду /mybots;

   3. Выбрать нужного Бота;

   4. Перейти в Bot Settings → Group Privacy;

   5. Выбрать Turn off.

4. При включенной настройке Group Privacy, чтобы отправить сообщение, которое будет обработано Агентом и записано в client_message, нужно либо ответить на сообщение Бота (reply), либо написать свое сообщение после символа / .

5. После каждого обработанного сообщения, в Канальные переменные будут установлены данные участника группы, отправившего сообщение.

6. Также, Агент обрабатывает события о добавлении в групповой чат новых пользователей. При этом в переменную client_message будет записана строка вида “telegram_chat_new_member: telegram_user_id|telegram_username|telegram_first_name|telegram_last_name” .

7. При обновлении группы до супергруппы генерируется новый идентификатор группы и Агент не может отправить сообщение.

Сообщение	Конечный канал	Client message	Описание
Пользователь группы телеграм присоединился в группу	Telegram	Строка: telegram_chat_new_member: {user.id}|{user.first_name}|{user.last_name}	При присоединении пользователя к группе Telegram в Контекстная переменная client_message передается сообщение в соответствии с шаблоном
Пользователь группы телеграм покинул в группу	Telegram	Строка: telegram_member_left_chat: {user.id}|{user.first_name}|{user.last_name}	При выходе пользователя из группы Telegram в Контекстная переменная client_message передается сообщение в соответствии с шаблоном

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

Переменная	Конечный канал	Переменная в запросе из канала	Примечания
channel_visitor_id	Telegram	id	При ответе на сообщение бота в групповом чате, в переменную записывается id ответившего юзера
channel_conversation_id	Telegram	id
channel_visitor_firstname	Telegram	first_name
channel_visitor_lastname	Telegram	last_name
channel_visitor_phone	Telegram
channel_visitor_email	Telegram
channel_visitor_account	Telegram	username
channel_visitor_auth	Telegram
channel_visitor_source	Telegram
channel_message_id	Telegram
channel_reply_to	Telegram	reply_to_message.text	Если Сообщение собеседника не является ответом (Reply) на сообщение Бота в Telegram, то переменная остается пустой

Функционал общения	Конечный канал	Доступность в канале	Примечания
channel_chat_id	Telegram	Да	Формат: channel_visitor_id|telegram
Сообщения дойдут до собеседника, если агент напишет первый в существующем чате	Telegram	Да
Перевод на оператора	Telegram	Нет	В мессенджере нет такого функционала
Кнопки	Telegram	Да
Передача файлов в виде ссылок от Агента (Attachment)	Telegram	Да	Файл будет передан ссылкой, если он не удовлетворяет требованиям Telegram к файлам данного типа.
Передача файлов в виде файлов от Агента (Attachment)	Telegram	Да	Telegram может принимать и предавать собеседникам вложения типа “file” только форматов gif, pdf и zip. Возможна поддержка других форматов, но Telegram её не гарантирует.При попытке передать изображение в слоте Attachment, если указана ссылка на файл из Telegram, то файл придет в виде ссылки, а не изображения
Получение файла от Собеседника в сценарий	Telegram	Да	В client_message записывается строка вида file:Тип файла|ID файла|Ссылка на файл, например, file:photo|HgYjJJGYuxkBAAMNYK1eZR1fbZv-KQ09Omcsz9A8AjwAAsSzMRtug3FJ079jiwXcvo-egdKiLgADAQADAgADeAADE7gCAAEfBA|https://api.telegram.org/file/bot1815753186:AAH_LtRWy_FSDAGFgstlTaQdkHHIFHV3xGI/photos/file_0.jpg . При этом, файл будет доступен по ссылке в течение 24 часов. Для получения файла в дальнейшем потребуется обновить ссылку на файл, используя Telegram API.
Получение геолокации от собеседника в сценарии	Telegram	Да	В client_message записывается строка вида location:Широта|Долгота, например, location:83.000000|54.000000
Доставка сообщений более 1000 символов от Агента до Собеседника	Telegram	Да	Допускаются сообщения до 4096 символов
Использование маркдауна	Telegram	Да	Работает в соответствии с документацией
Рассылки с помощью Notification	Telegram	Нет