Telegram

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

Подключение

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

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

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

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

  3. .

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

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

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

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

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

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

    6. Настроить аватар, описание, и прочие параметры бота вы можете через бота 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.

    1. Канал Проекта будет сохранен и активирован, если:

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

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

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

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

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

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

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

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

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

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

    1. Изменения будут применены, если:

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

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

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

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

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

  3. Чтобы деактивировать Канал Проекта, нажмите кнопку DEACTIVATE.

  4. Чтобы применить изменения к деактивированному Канал Проекта, нажмите кнопку SAVE.

  5. Чтобы применить изменения и активировать Канал Проекта, нажмите кнопку SAVE & ACTIVATE.

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

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

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

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

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

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

  6. Чтобы отменить внесение изменений, нажмите кнопку CANCEL.

  7. Чтобы удалить Канал Проекта, нажмите кнопку DELETE.

Общение

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

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

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

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

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

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

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

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

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

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

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

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

Сообщение
Конечный канал
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

Нет

Last updated