Общая информация о TelegramBot

Общая информация о TelegramBot

"Робот и Я"

Основные возможности и информация о телеграмботах и их применении в робототехнике и проектах умных домов

Телеграм использует собственный протокол шифрования MTProto. MTProto API (он же Telegram API) — это API, через который ваше приложение Телеграм связывается с сервером. Telegram API полностью открыт, так что любой разработчик может написать свой клиент мессенджера.

Содержание


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

Единственная информация о Телеграм-ботах, которой в интернете полным-полно: как создать бота. Это делается через специального бота BotFather. Когда вы создадите бота, BotFather даст вам его токен. Токен выглядит примерно так: 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw. Именно с помощью токена вы сможете управлять ботом.Один пользователь может создать до 20 ботов.

В BotFather удобно управлять ботами своими командой /mybots.

В начало


Юзернеймы

При создании бота нужно выбрать юзернейм. После этого поменять его будет очень сложно.

Юзернейм бота выглядит как обычный юзернейм, но он должен заканчиваться на "bot".

Вы могли видеть ботов с именами @pic, @vid, @sticker, @gamee — это официальные боты Телеграма. Им можно нарушать все правила/

Очень многие юзернеймы уже заняты. Свободных коротких юзернеймов осталось очень мало. И что самое грустное: почти все эти боты мертвы. Просто не отвечают на сообщения. Наверное, это просто разные любопытные люди хотят сделать бота, создают его, а потом забивают. У меня самого есть несколько лежащих ботов. Так что, думаю, лимит в 20 ботов на одного владельца вполне оправдан

В начало


Оформление бота

Открыв бота, пользователи могут увидеть его профиль.

Оформление бота настраивается в BotFather: меню /mybots → Edit Bot. Там можно изменить:

  1. Имя бота.
  2. Описание (Description) — это текст, который пользователи будут видеть в начале диалога с ботом под заголовком "Что может делать этот бот?"
  3. Информация (About) — это текст, который будет виден в профиле бота.
  4. Аватарка. Аватарки ботов, в отличие от аватарок пользователей и чатов, не могут быть анимированными. Только картинки.
  5. Команды — тут имеются ввиду подсказки команд в боте. Подробнее о командах ниже.
  6. Inline Placeholder — об инлайн-режиме см. ниже.

В начало


Запуск бота пользователем

Когда пользователь впервые открывает бота, он видит кнопку "Запустить" или "Начать" (зависит от платформы пользователя), на английском — "Start". Нажимая на эту кнопку, он отправляет команду /start.

Таким образом, первое сообщение от пользователя — это всегда /start (либо /start с параметрами)

На стороне сервера это не проверяется, поэтому теоретически пользователь может отправить боту любое сообщение через Telegram API.

В начало


Сообщения

Понятно, что главная функция бота — отправлять и получать сообщения.

И то, и другое можно делать со всеми видами сообщений (фото и видео, файлы, опросы, голосовые сообщения и т. д.).

В Телеграме можно делиться файлами до 2 ГБ, но в Bot API более жесткие лимиты: боты могут скачивать файлы до 20 МБ и отправлять файлы до 50 МБ.

Если бот уже загрузил файл на сервер Телеграма, то он может использовать file_id, чтобы отправлять этот файл.


Загружать файл на сервер можно в том числе и по URL файла.

Подробнее об отправке файлов в Bot API

В начало


Куда может писать бот

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

Боты не могут писать другим ботам.

Бота можно добавить в группу (если в BotFather включена соответствующая настройка). По умолчанию он видит не все сообщения (об этом ниже, в разделе "Видимость сообщений в группах").

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

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

Также бота можно добавить в канал, причем только как администратора. Самый частый способ использования ботов в каналах — добавление кнопок под постами ("лайки", ссылки и прочее).

У админа канала может быть специальное право: "Редактирование чужих публикаций". С помощью него боты редактируют посты, добавляя к ним кнопки.

В начало


Супергруппы

На самом деле многие группы в Телеграме являются супергруппами.

Почему так? Раньше было четкое разделение на группы и супергруппы. По задумке, супергруппы — это группы для сообществ. Супергруппы могут иметь больше участников, публичные ссылки и другие плюшки.

Со временем, видимо, решили, что это неудобная концепция. Теперь обычная группа становится супергруппой, когда у группы меняются какие-нибудь настройки (подробнее тут). Вот такой костыль.

В этой статье под группами я подразумеваю и супергруппы, и обычные группы.

Супергруппу нельзя обратно превратить в группу. С точки зрения API супергруппа устроена так же, как и канал. Важное отличие супергрупп от обычных групп состоит в нумерации сообщений.

В начало


id пользователей и чатов

У каждого пользователя, бота, группы, канала в Телеграме есть собственный id. Различать чаты в коде бота следует именно по id, потому что он никогда не меняется.

В токене бота первая часть — это его id. Например, токен 110201874:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw принадлежит боту с id 110201874.

В Bot API перед id супергрупп и каналов пишется -100. Так, id 1356415630 превращается в -1001356415630.

Не следует хранить id пользователей и чатов в 32-битном типе числа: теперь id могут превышать 231-1.

В начало


id сообщений

Каждое сообщение в Телеграме имеет свой id. Это относится и к системным сообщениям (пользователь зашел в группу, изменилось название группы и т. д.)

Через Telegram API боты могут получать по запросу сообщения в любом чате по их id.

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

id сообщений в личных сообщениях и обычных группах работают по другому. Там, можно сказать, нумерация сквозная: id сообщения уникально для каждого отправившего его пользователя. Так, первое сообщение от пользователя во всех личках и группах имеет номер 1, второе сообщение от того же пользователя имеет номер 2 и так далее.

В начало


Видимость сообщений в группах

Обычно бот должен реагировать именно на команды. Телеграм не уведомляет бота об остальных сообщениях, и это гарантирует приватность переписки.

Но если боту нужно видеть все сообщения в группе (например, если это чат-бот или антиспам-бот), для него можно отключить Privacy mode.

Privacy mode — настройка в BotFather, которая по умолчанию включена. В таком режиме бот в группах видит только такие сообщения:

  • Сообщения с упоминанием бота,
  • Ответы на сообщение бота, ответы на ответы и так далее,
  • Системные сообщения,
  • Команды — о них в следующем пункте.

А если Privacy mode выключен, то бот видит все сообщения в группе.

Если бот — админ в группе, то он в любом случае видит все сообщения.

Бот, работающий через Bot API, в любом случае не будет видеть сообщения от других ботов.

О Privacy mode в документации Bot API

В начало


Сообщения от лица групп и каналов

В группах могут быть не только сообщения от пользователей, но и:

  • Сообщения в группе из привязанного канала (с точки зрения API это пересланные сообщения)
  • Сообщения от лица группы от анонимных администраторов той же группы
  • Сообщения от лица публичных каналов от любых пользователей

Учитывайте это при разработке ботов для групп.

В начало


Команды

Часто используемый способ "общения" пользователей с ботом — команды. Команды начинаются на "/" и состоят из латинских букв (можно использовать цифры и нижние подчеркивания).

Команды подсвечиваются как ссылки: нажатие отправляет команду в чат.

В группах, чтобы различать команды от разных ботов, Телеграм предлагает ставить в конце команды юзернейм бота. Например: /start@examplebot.

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

Если в подсказках команд есть /help, в профиле бота появляется кнопка "Помощь с ботом". Нажатие на кнопку отправляет эту команду.

Если в подсказках команд есть /settings, в профиле бота появляется кнопка "Настройки бота". Нажатие на кнопку отправляет эту команду.

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

В начало


Разметка сообщений

Как вы, наверное, знаете, сообщения в Телеграме могут содержать не только обычный текст, но и жирный, курсив и др. В Bot API разметку сообщений можно делать в HTML и Markdown.

В Telegram API для разметки надо вместе с сообщением передавать entities (MessageEntityBold, MessageEntityItalic и так далее). Хорошие библиотеки сами превращают HTML/Markdown в текст и entities.

Способы выделения текста:

  • Жирный текст
  • Курсив
  • Подчёркнутый текст
  • Зачёркнутый текст
  • Моноширинный текст ("в строке" и "блоком")
  • Ссылка (встроенная в текст)
  • Спойлер — текст, который показывается только после нажатия на плашку
  • Упоминание пользователя — текст, похожий на ссылку, клик по которому открывает профиль пользователя. Если упомянуть в группе её участника, он получит уведомление.
  • Чтобы вставить в сообщение упоминание пользователя, в Bot API нужно встроить ссылку на tg://user?id=123456789.

О разметке в документации Bot API

В начало


Кнопки

Инлайн-кнопки

Бот может оставлять кнопки под своими сообщениями.

Кнопки под сообщениями (они же inline keyboards / inline buttons) в основном бывают трёх видов:

  • URL button — кнопка с ссылкой.
  • Callback button. При нажатии на такую кнопку боту придёт апдейт. С созданием кнопки можно указать параметр, который будет указан в этом апдейте (до 64 байтов). Обычно после нажатий на такие кнопки боты изменяют исходное сообщение или показывают notification или alert.
  • Switch to inline button. Кнопка для переключения в инлайн-режим (об инлайн-режиме см. ниже). Кнопка может открывать инлайн в том же чате или открывать меню для выбора чата. Можно указать в кнопке запрос, который появится рядом с никнеймом бота при нажатии на кнопку.
  • Login URL button — специальная кнопка для авторизации пользователей на сайте. Использовалась, например, в официальном боте @discussbot (до добавления нативных комментариев в Телеграм).
  • Callback game button — кнопка для открытия HTML-игры. См. пункт "HTML-игры".
  • Pay button — кнопка для платежей. См. пункт "Платежи через ботов".

В начало


Клавиатурные кнопки

Есть другой тип кнопок: keyboard buttons. Они отображаются вместо клавиатуры как подсказки. При нажатии на такую кнопку пользователь просто отправит этот текст.

При этом в личных чатах с помощью кнопки можно:

  • Запросить номер телефона пользователя,
  • Запросить геолокацию пользователя,
  • Открыть у пользователя меню создания опроса.

Есть опция resize_keyboard, которая отвечает за то, изменять ли высоту этой "клавиатуры из кнопок". По умолчанию она, почему-то, выключена, и тогда высота клавиатуры стандартная большая.

Чтобы показать клавиатурные кнопки, бот должен отправить сообщение. Можно отправить клавиатуру, которая свернётся (но не пропадёт) после нажатия на кнопку.

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

  • Для пользователей, юзернеймы которых были в тексте сообщения,
  • Если это ответ на другое сообщение: для пользователя, который его отправил.

Оба типа кнопок могут составлять несколько рядов, в каждом из которых по несколько кнопок. Ограничения: в ряду может быть до 8 кнопок, а всего с сообщением до 100 кнопок.

При отправке сообщения можно выбрать одно (но не больше) из следующих действий:

  • Добавить к сообщению инлайн-кнопки,
  • Показать клавиатурные кнопки,
  • Убрать все клавиатурные кнопки,
  • Force reply: автоматически заставить пользователя ответить на сообщение. Так произойдёт то же самое, что и при нажатии пользователем кнопки "Ответить". Это нужно для того, чтобы бот мог общаться с пользователями в группах, не нарушая Privacy mode.

Таким образом, нельзя показать оба типа кнопок одновременно.

В начало


Ссылки на бота

Юзернеймы ботов работают так же, как и любые другие юзернеймы в Телеграме: бота @examplebot можно открыть по ссылке t.me/examplebot.

Также существует прямая ссылка: tg://resolve?domain=examplebot

Подробнее о ссылках tg://

В начало


Ссылка на добавление в группу

По ссылке t.me/examplebot?startgroup=true у пользователя откроется меню: выбор группы для добавления бота.

Прямая ссылка: tg://resolve?domain=examplebot&startgroup=true

В начало


Диплинки

По ссылке t.me/examplebot?start=<ваш текст> пользователь может запустить бота с каким-то стартовым параметром (<ваш текст>).

Что происходит, когда пользователь переходит по такой ссылке:

  1. Бот открывается как обычно.
  2. Отображается кнопка "Запустить", даже если пользователь уже запускал бота.
  3. Пользователь нажимает на кнопку и видит сообщение /start (всё как обычно).
  4. Боту вместо этого приходит сообщение /start <ваш текст>

Так бот может отреагировать на запуск не как на обычный "/start", а другим способом.

Часто диплинки используются для реферальных программ (в качестве параметра можно передавать id пользователя, который поделился ссылкой). Есть и другие применения.

Прямая ссылка: tg://resolve?domain=examplebot&start=<ваш текст>

О диплинках в документации Bot API

В начало


Платежи через ботов

Телеграм предоставляет ботам возможность принимать платежи от пользователей. Это делается через провайдеров ЮMoney, Сбербанк, Stripe и ещё 7.

Эта возможность используются редко, потому что для использования провайдеров нужно юридическое лицо.

Страница Bot Payments API

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

В начало


Telegram Login Widget

Вы можете добавить на свой сайт авторизацию через Телеграм. Процесс авторизации будет проходить так:

  1. Пользователь должен будет ввести свой номер телефона.
  2. Бот Telegram попросит подтвердить вход.
  3. Пользователь авторизуется и нажимает на "Принять" на сайте.

Telegram Login Widget не связан с Login URL button (см. раздел про кнопки выше), а является его альтернативой.

О Telegram Login Widget на сайте Телеграм

В начало


Какие апдейты можно получать

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

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

В Telegram API бот может чуточку больше: он может получать сообщения по id, получать список участников группы и прочее.

Получение апдейтов: Bot API vs Telegram API

В начало


Обновления API

Telegram API и Telegram Bot API обновляются с появлением новых фич в Телеграме. Все обновления Bot API описаны на отдельной странице в документации и в официальном канале BotNews.

В начало


Лимиты

Конечно, на запросы к серверу существуют лимиты. В Bots FAQ на сайте Telegram названы следующие:

  • Не больше одного сообщения в секунду в один чат,
  • Не больше 30 сообщений в секунду вообще,
  • Не больше 20 сообщений в минуту в одну группу.

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

Другие известные ограничения в Telegram собраны на limits.tginfo.me — см. раздел про ботов.

В начало


Рассылка по пользователям

Ниже в Bots FAQ сказано, что Bot API не позволяет рассылать сообщения всем юзерам одновременно и что в будущем, может быть, они что-то для этого сделают. И написано это уже несколько лет.

Они советуют растянуть рассылку на длительное время (8-12 часов) и замечают, что API не позволит отправлять сообщения более чем ~30 пользователям в секунду.

В начало


Смена владельца бота

Осенью 2020 года появилась возможность передавать ботов другому человеку. Это можно сделать в настройках бота в BotFather. Для этого на вашем аккаунте должна быть включена двухфакторная авторизация — не менее, чем за 7 дней до передачи. Передать бота можно только пользователю, который что-либо ему писал.

В начало


Локальный сервер Bot API

Также осенью 2020 года исходники Bot API выложили на GitHub. Теперь вы можете поднять собственный сервер Bot API. На GitHub перечислены следующие преимущества:

  • Скачивание файлов с сервера без ограничения (ограничение на отправку файлов пользователями в Телеграме — 2 ГБ),
  • Загрузка файлов на сервер до 2000 МБ,
  • Загрузка файлов на сервер с помощью локального пути и URI файла,
  • Использование HTTP URL для вебхука,
  • Использование любого локального IP-адреса для вебхука,
  • Использование любого порта для вебхука,
  • Возможность увеличить максимальное число соединений до 100000,
  • Получение локального пути файла вместо загрузки файла с сервера.

В начало


Юзерботы

В начале статьи я рассказывал о том, что такое Telegram API и Telegram Bot API.

Telegram API используется не только для ботов — тогда в чём проблема управлять аккаунтами пользователей, как ботами? Люди это делают. Кто-то автоматически ставит текущее время себе на аватарку, кто-то скриптом реагирует на свои сообщения как на команды, кто-то сохраняет сообщения из публичных групп и каналов. Всё это называют юзерботами.

Юзерботов следует использовать аккуратно: за большую подозрительную активность аккаунт могут ограничить или забанить

В начало


За основу взяты материалы статьи на хабре

К списку проектов

На главную





Report content on this page

Report Page

Please submit your DMCA takedown request to dmca@telegram.org