Боты: Введение разработчикам

Боты – специальные аккаунты Телеграмм, автоматически обрабатывающие сообщения. Пользователи могут взаимодействовать с ботами, отправляя им сообщение-команду в личных или групповых чатах. Вы можете управлять своим ботом, используя HTTPS запросы к API специально разработанного бота.

1. Что я могу делать с ботами?

Здесь представлены лишь несколько целей, для которых вы можете использовать ботов:

  • Интегрировать с другими сервисами. Потенциально бот способен автономно добавлять комментарии или управлять «умным домом» (Smart Home). Он также может отправлять вам уведомления через Телеграмм, когда что-то происходит (Например: GitHub Bot, Image Bot).
  • Создать пользовательские инструменты. Бот может предоставить вам прогноз погоды, оповестить, перевести текст или предоставить другую услугу по запросу. (Например: Poll Bot).
  • Создать одно- и многопользовательские игры. Бот может играть в шахматы и шашки против вас, проводить викторину или даже бросить кости магистра в подземельях РПГ. (Например: Trivia Bot).
  • Создать социальные сервисы. Бот может объединить людей, которые ищут собеседника на основе общности или близости интересов. (Например: Tinder-like, HotOrBot).
  • Делать практически все, что угодно. Кроме посуды – боты ужасно моют посуду.

2. Как работают боты?

Боты для Телеграмм являются особыми аккаунтами, которые не требуют дополнительного телефонного номера для установки. Эти аккаунты служат интерфейсом для кода, работающего где-то на вашем сервере.

Несомненным плюсом является то, что вам не нужно ничего знать о том, как работает протокол шифрования MTProto – сервер-посредник Telegram будет обрабатывать всю шифровку и связь с API за вас! Вы общаетесь с этим сервисом через простой интерфейс HTTPS, который является упрощенной версией API Телеграмма. Этот интерфейс называется Bot API.

! Подробное описание Bot API доступно на этой странице »

3. Как создать бота?

Для этого существует особый бот. Вы можете просто поговорить с BotFather (описание ниже) и выполнить несколько простых шагов. После того, как вы создали бота и получили свой токен авторизации, изучите инструкцию к Bot API, чтобы получить информацию о том, чему вы можете научить своего бота.

4. Как отличить бота от человека?

  • У ботов нет статуса «онлайн» и отметок о последнем посещении. Вместо этого интерфейс показывает метку «Бот».
  • У ботов ограниченный объем облачного хранилища: старые сообщения могут быть удалены сразу же после их обработки.
  • Боты не могут инициировать разговор с пользователем. Пользователь должен либо добавить их в список контактов, либо отправить боту сообщение. Пользователи могут использовать ссылки telegram.me/~~HEAD=dobj~~number=plural <> bot_username или же ввести имя бота в поисковой строке, чтобы найти вашего бота.
  • Имена ботов всегда заканчиваются на «bot» (Например: TriviaBot, GitHub_bot).
  • При добавлении в группу контактов, по умолчанию бот получает не все сообщения (см. режим конфиденциальности).
  • Бот никогда не ест, не спит и не жалуется (если иное не запрограммировано).

Уникальные особенности ботов

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

Клавиатуры

Одной из самых крутых вещей в Bot API являются новые пользовательские клавиатуры. Каждый раз, когда ваш бот посылает сообщение, оно может быть отправлено со специальной клавиатуры с предоставленными вариантами ответа (см. ReplyKeyboardMarkup). Приложение Telegram самостоятельно выведет клавиатуру пользователю. Нажатие одной из клавиш незамедлительно отправит соответствующую команду.

В настоящее время для кнопок поддерживаются как текст, так и смайлики эмоджи. Вот несколько примеров таких клавиатур:

(скрины 1,2,3)

! Для получения более подробной технической информации о пользовательских клавиатурах, пожалуйста, обратитесь к статье API Телеграмм ботов »

Команды

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

/command [optional] [argument]

Команда всегда должна начинаться с символа / и должна содержать не более 32 знаков. В команде могут использоваться латинские буквы, цифры и подчеркивания. Например:

/get_messages_stats
/set_timer 10мин тревоги!
/get_timezone Лондон, Великобритания

Сообщения, начинающиеся со слэша (/), всегда будут переданы боту (вместе с ответами на его сообщения и сообщениями, в которых указано имя бота, начинающееся на символ @) .

Приложение Telegram будет:

  • Предлагать список поддерживаемых команд с описаниями, когда пользователь вводит ‘/’ (для того чтобы работать, необходимо предоставить список команд в BotFather). Нажатие команды из списка немедленно отправляет команду боту.
  • Показывать дополнительную (/) кнопку в поле ввода во всех чатах с ботами. После нажатия отображается ‘/’ и список возможных команд.
  • Выделять /команды в сообщениях. Когда пользователь нажимает выделенную команду, она сразу же отправляется.

Несколько примеров: Скрин 4,5

Если в группе несколько ботов, то есть возможность добавить имена ботов в команды для того, чтобы избежать путаницы:

/start@TriviaBot
/start@ApocalypseBot

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

Глобальные команды

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

  • /start – начинается взаимодействие с пользователем, например, с помощью отправки приветственного сообщения. Эта команда также может быть использована для отображения дополнительных параметров бота (см. Глубокая разветвленная логика).
  • /help – показывает сообщение-справку. Это может быть короткое сообщение о том, что ваш бот может делать и список прилагаемых команд.
  • /settings – (если применимо) показывает настройки бота для данного бота и предлагает список команд для редактирования этих параметров.

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

Скрин 5,6

Выделение текста: жирный, курсив и встроенные ссылки

Вы можете использовать жирное и курсивное начертание, а также встроенные ссылки в сообщениях ваших ботов. Клиенты Телеграмма воспроизводят их соответственно (на данный момент данная функция поддерживается только для Android, но в ближайшее время все остальные официальные клиенты подтянутся).

! Подробный мануал по Bot API »

Режим конфиденциальности

Достаточно часто ботов добавляют в групповой чат с целью увеличения связей между пользователями, например, с помощью предоставления новостей в общем чате, уведомлений о различных услугах или дополнительным функционалом поиска. Это особенно актуально при работе с группами. Теперь, когда вы делите групповой диалог с ботом, вы наверняка спрашиваете себя: «Как я могу быть уверен, что это не мошенник, который передает информацию из переписок моим конкурентам?». Ответ – режим конфиденциальности.

Бот, работающий в режиме конфиденциальности, не будет получать все сообщения, которые пересылаются между пользователями. Вместо этого он будет получать только:

  • Все сообщения, которые начинаются с символа ‘/’ (см. Команды выше).
  • Сообщения, в которых указано имя бота, начинающееся на символ @.
  • Ответы на сообщения бота.
  • Служебные сообщения (пользователь добавлен/удален из группы).

С одной стороны, это помогает некоторым из нас лучше спать ночью (в колпаках из фольги), с другой – это позволяет разработчику сэкономить множество ресурсов, так как ему не придется обрабатывать десятки тысяч нерелевантных сообщений ежедневно.

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

Разветвленная глубокая логика

У ботов Телеграмма есть механизм глубокой разветвленной логики, который позволяет включать дополнительные параметры при запуске. Это может быть команда, которая запускает бота или маркер аутентификации для подключения учетной записи Телеграмма пользователя к их аккаунту какого-либо внешнего сервиса.

У каждого бота есть ссылка, которая непосредственно открывает диалог с ним в Телеграмме. https://telegram.me/. Вы можете добавить параметры запуска(start) или группового запуска (startgroup) по этой ссылке, со значениями до 64 символов. Например:

https://telegram.me/triviabot?startgroup=test

A-Z, a-z, 0-9, _ и - разрешаются. Мы рекомендуем использовать base64url для кодирования параметров с двоичными данными и другими и типами контента.

Последующая ссылка с параметром запуска откроет диалог один-на-один с ботом, показывая кнопку /start в поле ввода. Если используется групповой параметр startgroup, то пользователю будет предложено выбрать группу, чтобы добавить бота. Как только пользователь подтверждает действие (например, нажимает кнопку Start в окне диалога или выбирает группу, чтобы добавить в нее бота) бот будет получать сообщение от пользователя в следующей форме:

/start PAYLOAD

PAYLOAD означает запуск (start или startgroup) параметра, который был передан в ссылке.

Пример глубокой разветвленной логики

Предположим, что веб-сайт example.com хотел бы отправлять уведомления пользователям через Телеграмм. Ниже представлен алгоритм того, что бы они могли сделать для возможности отправки уведомлений с ID 123.

  1. Создать бота с подходящим именем, например, ExampleComBot.
  2. Настроить webhook для входящих сообщений.
  3. Создать случайную строку достаточной длины, например $ memcache_key = "vCH1vGWJxfSeofSAs0K5PA"
  4. Поставить значение «123» с ключом $ memcache_key в Memcache в течение 3600 секунд (1 час).
  5. Показать пользовательскую кнопку https://telegram.me/ExampleComBot?start=vCH1vGWJxfSeofSAs0K5PA~~HEAD=dobj
  6. Настроить процессор webhook на запрос Memcache с параметром, который передается во входящих сообщениях и начинается с /start. Если ключ существует, записать chat_id, переданный в webhook как telegram_chat_id для пользователя 123. Извлечь ключ из Memcahe.
  7. Теперь, когда мы хотим, чтобы пользователю 123 отправлялось уведомление, необходимо проверить наличие соответствующего поля в telegram_chat_id. Если да, то используем SendMessage в Bot API для отправки сообщения в Телеграмме.

BotFather

BotFather является ботом, созданным для управления ими всеми. Он поможет создать новых ботов и изменить настройки уже существующих.

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

Используйте команду /newbot, чтобы создать нового бота. BotFather запросит у вас имя и юзернейм для того, чтобы сгенерировать токен-авторизацию для нового бота.

Имя вашего бота будет отображаться в контактной информации и в других местах.

Юзернейм – это короткое имя, которое будет использоваться в упоминаниях и telegram.me ссылках. Юзернейм может быть длиной от 5 до 32 символов, он не чувствителен к регистрам, но может включать в себя только латинские буквы, цифры и подчеркивания. Имя пользователя должно заканчиваться на “bot”, например, ’tetris_bot’ или ‘TetrisBot’.

Маркером является строка 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw, которая будет необходима для авторизации бота и отправки запроса в Bot API.

Создать маркер авторизации для бота

Если ваш существующий маркер подвергается риску или же вы потеряли его по какой-либо причине, используйте команду /marker, чтобы создать новый.

Изменить настройки

Остальные команды достаточно понятны:

    • /setName – изменить имя бота.
    • /setdescribtion – изменяет описание бота – краткий текст до 512 символов, описывающий бота. Пользователи будут видеть этот текст в начале беседы с ботом под заголовком: «Что этот бот может делать?».
    • /setabouttext - изменяет данные о боте, еще более короткий текст до 120 символов. Пользователи будут видеть этот текст на странице профиля бота. Когда пользователь добавляет бота в группу, этот текст будет отправлен вместе с ссылкой.
    • /setuserpic - измененет фотографию профиля бота. Всегда приятно видеть лицо.
    • /setcommands - изменяет список команд, поддерживаемых вашим ботом. Каждая команда имеет имя (необходимо начать команду с косой черты '/', использовать буквенно-цифровой ввод плюс подчеркивания, размер ограничен 32 символами, без учета регистра), параметры и текстовое описание. Пользователи увидят список команд, когда вводят '/' в беседе с ботом.
    • /setjoingroups - определяет, можно ли добавить вашего бота в группу или нет. Любой бот должен быть в состоянии обрабатывать личные сообщения, но если ваш бот не предназначен для работы в группах, вы можете отключить эту опцию.
    • /setprivacy - определяет, какие сообщения бот будет получать при добавлении к группе. Если режим конфиденциальности отключен, бот будет принимать все сообщения. Мы рекомендуем оставить режим конфиденциальности включенным.
    • /deletebot - удаляет бота и освобождает его имя.
! Пожалуйста, обратите внимание, что может потребоваться несколько минут, чтобы изменения вступили в силу.