chatme.ai
Search
⌃K

Вывод Агента в Telegram

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

Подключение Агента

Создание бота в Telegram

В первую очередь нужно произвести конфигурацию на стороне Telegram.
  1. 1.
    Откройте Telegram и авторизуйтесь.
  2. 2.
    Найдите в поиске бота “BotFather”.
    image.png
    .
  3. 3.
    Создайте бота в Telegram:
    • Отправьте боту BotFather команду /newbot.
    • В ответ на сообщение бота введите желаемое имя вашего бота
    • Отправьте желаемый идентификатор бота. Он должен быть уникальным среди всех существующих ботов в Telegram и заканчиваться на “bot”. Например, My_new_telegram_bot_username_bot.
      image.png
    • Если отправленный идентификатор бота соответствует требованиям, вы получите сообщение об успешном создании бота. В сообщении будет указана ссылка на вашего бота в Telegram и токен доступа к боту.
      image.png
    • Скопируйте токен доступа.
      tempsnip.png
    • Настроить аватар, описание, и прочие параметры бота вы можете через бота BotFather.
На этом конфигурация бота в Telegram завершена.

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

Агенту необходимо создать и настроить Канал Агента с коннектором Telegram.
  1. 1.
    Войдите в меню редактирования (Edit) настроек вашего Агента.
  2. 2.
    В появившемся окне перейдите на вкладку Channels для настройки каналов, затем:
    • выберите тип канала Messaging
    • Нажмите кнопку Add another channel.
      messaging.png
  3. 3.
    Интеграция с Telegram происходит через Коннектор с названием “Telegram”, установите его в поле Channel.
  4. 4.
    По необходимости пропишите заголовок для данного канала в поле Title.
    1. 1.
      Заголовки разных каналов агента могут совпадать.
  5. 5.
    После выбора Telegram вам станет доступно для записи поле Token, в которое нужно вставить предварительно скопированный токен
  6. 6.
    Активируйте канал переключением тумблера для того, чтобы Агент начал отвечать в нем после сохранения.
    1. 1.
      Если Агент не был обучен, появится предупреждение. В таком случае необходимо обучить Агента, после чего повторить попытку активации Канала Агента.
      image.png
  7. 7.
    После активации Канала Агента, если есть проблемы с его доступностью, будет выведено предупреждение (Канал будет активирован несмотря на проблемы):
    1. 1.
      "Can’t reach channel" — выводится в случае, если сервер не отвечает по указанному URL
      image.png
    2. 2.
      ”Couldn’t register agent webhook” — выводится в случае, если не удалось зарегистрировать вебхук в удаленном канале.
      image.png
  8. 8.
    Сохраните Канал Агента — нажмите Save.
Все настройки будут применены только после сохранения.

Общение

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

  • Чатбот может быть добавлен в групповой чат Telegram и обрабатывать сообщения и события этого чата.
  • Если Telegram-бот НЕ является администратором группы: чтобы отправить сообщение, которое будет обработано Агентом и записано в переменную контекста client_message, нужно либо ответить на сообщение бота(reply), либо написать свое сообщение после символа / .
  • Если Telegram-бот является администратором группы: Агент обрабатывает все сообщения, отправляемые в чат.
  • После каждого обработанного сообщения, в Канальных переменных будут установлены данные участника группы, отправившего сообщение.
  • Также Агент обрабатывает события о добавлении в групповой чат новых пользователей. При этом в переменную client_message будет записана строка вида “telegram_chat_new_member: telegram_user_id|telegram_username|telegram_first_name|telegram_last_name” .

Сервисные сообщения канала

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

Маппинг канальных переменных из канала Telegram

Канальная переменная
Переменная в теле входящего запроса из канала
Особенности
channel_visitor_id
id
При ответе на сообщение бота в групповом чате, в переменную записывается id ответившего юзера
channel_conversation_id
id
channel_visitor_firstname
first_name
channel_visitor_lastname
last_name
channel_visitor_phone
channel_visitor_email
channel_visitor_account
username
channel_visitor_auth
channel_visitor_source

Возможности общения в Telegram

Функционал
Наличие в канале
Описание
Переменная channel_chat_id
Да
Формат: channel_visitor_id|telegram
Сообщения дойдут до собеседника, если Агент напишет первый в существующем чате
Да
Перевод на оператора
Нет
В мессенджере нет такого функционала
Кнопки
Да
Передача файлов в виде ссылок от Агента (слот Attachment)
Да
Файл будет передан ссылкой, если он не удовлетворяет требованиям Telegram к файлам данного типа.
Передача файлов в виде файлов от Агента (слот Attachment)
Да
Telegram может принимать и передавать собеседникам вложения типа “file” только форматов gif, pdf и zip. Возможна поддержка других форматов, но Telegram её не гарантирует. Подробнее: https://core.telegram.org/bots/api#sending-files
Получение файла от Собеседника в сценарий
Да
В переменную 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.
Получение геолокации от собеседника в сценарии
Да
В переменную client_message записывается строка вида location:Широта|Долгота, например, location:83.000000|54.000000
Доставка сообщений более 1000 символов от Агента до Собеседника
Да
Допускаются сообщения до 4096 символов
Использование маркдауна
Да
Работает в соответствии с документацией