Работа с Telegram Bots

📕 Начало работы

Боты Telegram создают возможности для интерактивного взаимодействия с клиентом или сотрудником, ответственным за определенные решения внутри организации.

Создать бота может любой пользователь Telegram, а их возможности позволяют сформировать практически любой сценарий персонализированного общения.

Для работы с ботом в Telegram необходимо его зарегистрировать в Accelera. Право на регистрацию и удаление бота есть у администратора системы Accelera. Для регистрации бота Вам потребуется токен бота в Telegram.

На вкладке администрирования для регистрации бота нажмите кнопку +Bot

В появившемся окне введите токен бота, нажмите Save. Система автоматически загрузит данные о боте и отобразит в таблице ниже.

✅ Бот готов для работы и уже принимает входящие сообщения.

Блоки для взаимодействия с ботом станут доступны в редакторе в разделе TelegramBot API. Данная секция отображается только в том случае, если модуль для Telegram ботов в настоящий момент доступен.

⚠️ Ограничения

Telegram устанавливает ограничения на взаимодействие с пользователями мессенджера по своим правилам. Ниже рекомендации по соблюдению ограничений:

1. Старайтесь не отправлять в один чат более 1 сообщения в секунду (особенно на больших количествах пользователей). Это не строгое ограничение, но при длительном нарушении этого ограничения API Telegram на некоторое время перестанет обслуживать ваших ботов
2. При массовых рассылках старайтесь не превышать ограничение в 30 сообщений в секунду. При превышении этого показателя API Telegram на некоторое время перестанет обслуживать ваших ботов.
3. Также обратите внимание, что ваш бот не сможет отправлять более 20 сообщений в минуту одной и той же группе.

Блоки для работы с Telegram ботами

Для взаимодействия с ботом предусмотрены блоки:

1. Wait message - ожидание события или сообщения.
2. Message - отправка сообщения.
3. Photo - отправка фотографии.
4. Poll - отправка опроса.
5. Sticker - отправка стикера.
6. Document - отправка документа.

💬 Прием сообщений

Прием текстовых сообщений

Прием текстовых сообщений осуществляется с помощью блока Wait message.

Данный блок необходимо настроить, нажав кнопку Configure. В открывшемся модале выберите бота, от которого будет ожидаться сообщение в этом блоке.

Сообщение, которое приходит от бота имеет следующую структуру:

{
  message_id: 386,
  from: {
    id: 123456789,
    is_bot: false,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    language_code: 'ru'
  },
  chat: {
    id: 123456789,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    type: 'private'
  },
  date: 1658848867,
  text: '/start',
  entities: [ { offset: 0, length: 6, type: 'bot_command' } ]
}

Для обработки параметров в сценарии к ним нужно обращаться через {{ }} по имени, указаное в колонке параметр.
Например, имя пользователя можно получить через формулировку {{ from.first_name }}.

Прием нажатий на кнопку c callback data

Если вы отправили пользователю сообщение с inline-клавиатурой, в кнопках которой есть callback data, то нажатие на такую кнопку пришлет в систему Accelera событие telegram_callback_query с параметром контекста data, в которой будет указана callback информация из нажатой кнопки. Подробнее см. Отправка сообщений.

Прием нажатий на кнопки опросов

При нажатии пользователем на опрос от бота в систему поступит событие telegram_poll_answer с параметром контекста options, в котором будет указан номер варианта, на который он нажал (начинается с 0).

💬 Отправка сообщений

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

Отправка текстовых сообщений

Блок Message отправляет пользователю простое текстовое сообщение. Дополнительно к текстовому сообщению можно отправить клавиатуру или Inline-клавиатуру. Подробнее см. Клавиатуры.

Пример настройки блока Message

Описание параметров

Bot

Укажите бота, который должен отправить сообщение.

Chat
Укажите идентификатор чата, в который нужно отправить сообщение. Стандартное значение (подсказывает по двойному клику) - {{
chat.id }}

Message

Введите сообщение для пользователя. Поддерживается markup разметка и emoji.

Keyboard

Укажите клавиатуру и заполните поля. Клавиатура - необязательный элемент, вы можете отправлять сообщения без него.

См. Клавиатуры.

Отправка фото

Для отправки фото пользователю у вас должна быть URL-адрес изображения, опубликованного в сети Интернет, либо идентификатор файла ранее загруженной фотографии. Проще всего разместить изображение на доступном сервере и отправить пользователю URL. Пример настройки:

С полями Bot и Chat вы уже знакомы. В поле Upload image укажите URL-адрес картинки. Также доступно опциональное поле Caption для подписи к изображению.

Также вместе с фото можно отправить клавиатуру.

Результат

Отправка стикера

Для того, чтобы отправить стикер необходимо знать его идентификатор. Для этого существует множество разных ботов Telegram. Либо вы можете создать свой стикерпак и получить идентификаторы для каждого стикера. Найдите подходящий для вас способ и получите ID стикера.

Вы также можете указать URL-ссылку на изображение в формате .webp, оно будет также отправлено как стикер.

Далее настройте его отправку пользователю:

Результат

Отправка опроса

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

Результат

В результате нажатия на 3 вариант в Accelera поступило событие telegram_poll_answer с параметром options, которое имеет значение 2.

Отправка документа

С помощью этого блока вы можете отправить пользователю любой файл до 50 Mb в виде документа. Все, что вам нужно - это знать URL-адрес этого файла.

Пример настройки

Результат

⌨️ Клавиатуры

Клавиатуры расширяют возможности взаимодействия с пользователем и упрощают опыт взаимодействия с ботом.

Есть два типа клавиатур:

• Обычная клавиатура отображается в нижней части экрана.
• Inline клавиатура отображается непосредственно под сообщением.

💡

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

Обычная клавиатура

Стандартная клавиатура Telegram появляется вместо клавиатуры смартфона и дает доступ к быстрым командам бота. Данная клавиатура остается у пользователя всегда, пока вы не пришлете другую.

Пример настройки обычной клавиатуры:

Отображение на смартфоне:

У каждой кнопки есть свой тип:

• Web page: открывает указанный сайт в формате страницы, пример:
  

• Contact: запрашивает у пользователя информацию о его номере телефона. При нажатии вы получите подтвержденный номер телефона. См. пример сообщения с контактом.

• Location: запрашивает у пользователя информацию о его местонахождении. В систему поступает широта и долгота устройства клиента. На десктоп версиях работает не всегда. См. пример сообщения с локацией.

• Custom: нажатие на кнопку отправляет боту текст, который написан на кнопке. В результате система Accelera получает обычное текстовое сообщение.

Поле Max amount of buttons in the row регулирует отображение кнопок у пользователя. Вы указываете максимальное количество кнопок в строке. По умолчанию - 1.

Inline-клавиатура

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

Пример настройки inline-клавиатуры

Отображение у пользователя:

Нажатие на Visit accelera.ai откроет превью страницы (как в предыдущем примере).

Нажатие на Get info about Accelera откроет страницу как внешнюю ссылку.

Если пользователь нажмет на Callback info, то система Accelera получит событие telegram_callback_query, с параметром data. В данном примере параметр data будет содержать строку “callback_data”.

🧑🏼‍💻 Примеры входящих сообщений

Фото

{
  message_id: 388,
  from: {
    id: 123456789,
    is_bot: false,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    language_code: 'ru'
  },
  chat: {
    id: 123456789,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    type: 'private'
  },
  date: 1658849467,
  photo: [
    {
      file_id: 'AgACAgIAAxkBAAIBhGLgCLv8qSp3dQ5QdLZdwkPf65l7AAIOwDEbWuoBS56x9-Jd6Q3-AQADAgADcwADKQQ',
      file_unique_id: 'AQADDsAxG1rqAUt4',
      file_size: 790,
      width: 67,
      height: 90
    },
    {
      file_id: 'AgACAgIAAxkBAAIBhGLgCLv8qSp3dQ5QdLZdwkPf65l7AAIOwDEbWuoBS56x9-Jd6Q3-AQADAgADbQADKQQ',
      file_unique_id: 'AQADDsAxG1rqAUty',
      file_size: 7911,
      width: 240,
      height: 320
    },
    {
      file_id: 'AgACAgIAAxkBAAIBhGLgCLv8qSp3dQ5QdLZdwkPf65l7AAIOwDEbWuoBS56x9-Jd6Q3-AQADAgADeAADKQQ',
      file_unique_id: 'AQADDsAxG1rqAUt9',
      file_size: 20101,
      width: 539,
      height: 718
    }
  ]
}

Контакт

{
  message_id: 391,
  from: {
    id: 123456789,
    is_bot: false,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    language_code: 'ru'
  },
  chat: {
    id: 123456789,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    type: 'private'
  },  
	date: 1658849750,
  contact: {
    phone_number: '79998887766',
    first_name: 'Ivan',
    last_name: 'Ivanov',
    user_id: 123456789
  }
}

Геолокация

{
  message_id: 393,
  from: {
    id: 123456789,
    is_bot: false,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    language_code: 'ru'
  },
  chat: {
    id: 123456789,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    type: 'private'
  },
  date: 1658849877,
  location: { latitude: 55.804492, longitude: 31.584954 }
}

Стикер

{
  message_id: 387,
  from: {
    id: 123456789,
    is_bot: false,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    language_code: 'ru'
  },
  chat: {
    id: 123456789,
    first_name: 'Ivan',
    last_name: 'Ivanov',
    username: 'username',
    type: 'private'
  },
  date: 1658849234,
  sticker: {
    width: 512,
    height: 512,
    emoji: '🎉',
    set_name: 'prtyparrot',
    is_animated: true,
    is_video: false,
    thumb: {
      file_id: 'AAMCAgADGQEAAgGDYuAH0r3yPXs47q2NI3PHQoipYyQAArEAA8D7CAABA-2rzdMeZJkBAAdtAAMpBA',
      file_unique_id: 'AQADsQADwPsIAAFy',
      file_size: 2524,
      width: 128,
      height: 128
    },
    file_id: 'CAACAgIAAxkBAAIBg2LgB9K98j17OO6tjSNzx0KIqWMkAAKxAAPA-wgAAQPtq83THmSZKQQ',
    file_unique_id: 'AgADsQADwPsIAAE',
    file_size: 3222
  }
}