# Telegram
[Telegram](http://telegram.org) — мессенджер, имеющий веб версию, десктоп версию, а также версию для мобильных устройств. Имеет встроенный функционал чат-ботов.
## Подключение
### 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 её не гарантирует.](https://core.telegram.org/bots/api#sending-files)При попытке передать изображение в слоте Attachment, если указана ссылка на файл из Telegram, то файл придет в виде ссылки, а не изображения |
| Получение файла от Собеседника в сценарий | Telegram | Да | В client\_message записывается строка вида file:Тип файла\|ID файла\|Ссылка на файл, например, file:photo\|HgYjJJGYuxkBAAMNYK1eZR1fbZv-KQ09Omcsz9A8AjwAAsSzMRtug3FJ079jiwXcvo-egdKiLgADAQADAgADeAADE7gCAAEfBA\| . При этом, файл будет доступен по ссылке в течение 24 часов. Для получения файла в дальнейшем потребуется обновить ссылку на файл, используя [Telegram API](https://core.telegram.org/api). |
| Получение геолокации от собеседника в сценарии | Telegram | Да | В client\_message записывается строка вида location:Широта\|Долгота, например, location:83.000000\|54.000000 |
| Доставка сообщений более 1000 символов от Агента до Собеседника | Telegram | Да | Допускаются сообщения до 4096 символов |
| Использование маркдауна | Telegram | Да | Работает в соответствии с [документацией](https://core.telegram.org/bots/api#markdownv2-style) |
| Рассылки с помощью Notification | Telegram | Нет | |
\