Telegram Bot API: гайд для разработчиков ботов

Управляем телеграм-ботами без сторонних библиотек.

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

Альтернативное решение — Bot API. Это нативный интерфейс от создателей мессенджера, который лежит в основе всех ботов и библиотек. В этой статье рассказываем, для чего нужен Telegram Bot API и как им пользоваться.

Что такое Telegram Bot API

Чтобы понять, что такое Telegram Bot API, для начала разберёмся с самим понятием API.

Процесс работы с API строится на модели «запрос — ответ». Программист или приложение отправляет запрос на сервер и в ответ получает нужные данные, подтверждение выполнения операции или код ошибки.

Если вы никогда не работали с API и хотите узнать об этом больше, рекомендуем прочитать наше руководство.

Какие API есть в Telegram

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

Как создать бота в Telegram

Перед тем как писать код, надо создать бота — зарегистрировать специальный аккаунт и получить уникальный токен для API. Разберём подробно этот процесс.

Создаём бота в BotFather

Для разработчиков в Telegram есть BotFather — «крёстный отец» всех ботов. С его помощью можно зарегистрировать и настроить нового бота. Вот как это сделать:

• Шаг 1. Запустите Telegram и перейдите в чат BotFather. Будьте внимательны, у официального бота должна быть галочка верификации.

Официальный бот BotFather в Telegram
Скриншот: BotFather / Telegram

• Шаг 2. Нажмите кнопку Start, и BotFather пришлёт в ответ список доступных команд.

Список доступных команд
Скриншот: BotFather / Telegram

• Шаг 3. Выберите команду /newbot для создания нового бота.
• Шаг 4. BotFather попросит придумать боту имя, которое пользователи будут видеть в списке чатов. Можно использовать символы любого алфавита, цифры, знаки препинания и эмодзи. Например: Суперполезный бот 3000 🤓.
• Шаг 5. После этого бот-отец попросит задать username — уникальное имя пользователя, с помощью которого вашего бота можно будет найти в Telegram. В этом случае можно использовать только латиницу, цифры и некоторые разделительные знаки, а на конце обязательно должно быть слово bot. Например: Super3kBot или Super3k_bot.

BotFather проверит доступность юзернейма, и, если он свободен, поздравит с созданием нового бота и пришлёт токен. Это специальный набор букв и цифр, который нужен для связи вашего бота с сервером Telegram. Выглядит он примерно так:

7582552655:AAHmzfaKaoMnajrk47dLS76S2epa127gJ-0

Сообщение с токеном нового бота
Скриншот: BotFather / Telegram

Сохраните токен в надёжном месте и никому не показывайте. Если злоумышленники завладеют им, то смогут контролировать вашего бота, собирать данные пользователей и перенаправлять платежи. В случае утечки сгенерируйте новый токен с помощью команды /revoke в BotFather.

Полезные команды BotFather

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

• /mybots — показать список всех ботов пользователя;
• /setname — изменить имя бота;
• /setdescription — установить описание бота, которое отображается в профиле бота;
• /setabouttext — заполнить поле «О боте» в профиле;
• /setuserpic — установить аватарку;
• /setcommands — настроить список команд;
• /setinline — включить inline-режим, чтобы ботом можно было пользоваться в любом чате Telegram;
• /setjoingroups — разрешить боту работать в группах;
• /deletebot — удалить бота.

Какие есть ограничения у ботов в Telegram

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

Работая над своим проектом, помните, что боты в Telegram не могут:

• писать первыми — для начала общения пользователь должен нажать кнопку Start;
• управлять группами, в которые их не добавили администраторы;
• отправлять более 30 сообщений в секунду всего и более 20 сообщений в минуту в один чат;
• отправлять файлы размером более 50 МБ.

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

Как взаимодействовать с ботом через Bot API: метод getMe

Для взаимодействия с ботом при помощи Telegram Bot API мы будем отправлять HTTP-запросы на сервер мессенджера. В ответ нам будут приходить данные в формате JSON. Отправлять запросы можно несколькими способами.

C помощью браузера

Самый простой способ отправить запрос — воспользоваться браузером. Вот как это можно сделать:

• Шаг 1. Откройте любой браузер и введите адрес в формате https://api.telegram.org/bot{ТОКЕН}/{НАЗВАНИЕ-HTTP-МЕТОДА}.
• Шаг 2. Перейдите по адресу, чтобы получить ответ от сервера.

В качестве примера проверим, работает ли наш бот, и запросим основную информацию о нём. Для этого отправим запрос getMe:

https://api.telegram.org/bot7432444009:AAG62HGsVhddP5kq5Cbdf1ugTcYpTriV1Mg/getMe

Если вы всё сделали правильно, то в окне браузера появится следующий код:

{ “ok”:true, “result”: { “id”:7432444009, “is_bot”:true, “first_name”:”Суперполезный бот 3000 🤓”, “username”:”Super3kBot”, “can_join_groups”:true, “can_read_all_group_messages”:false, “supports_inline_queries”:false, “can_connect_to_business”:false, “has_main_web_app”:false } }

Из него мы можем узнать уникальный идентификатор бота, юзернейм, название и список разрешений — например, можно ли добавить бота в групповой чат и может ли он читать в нём все сообщения.

С помощью Python

Запрос getMe можно отправить с помощью кода на Python и библиотеки Requests. Эта библиотека содержит функции, упрощающие процесс взаимодействия с различными API.

import requests # Создаём переменные, в которых будут храниться токен бота и HTTP-запрос bot_token = “7432444009:AAG62HGsVhddP5kq5Cbdf1ugTcYpTriV1Mg” url = f”https://api.telegram.org/bot{bot_token}/getMe” response = requests.get(url) # Пишем условие для обработки ответа сервера if response.status_code == 200: json_data = response.json() print(“Ответ API:”, json_data) else: print(f”Ошибка: {response.status_code}”)

После запуска кода в терминале IDE появится ответ сервера в виде JSON-файла. Ответ будет содержать всё то же самое, что и при отправке запроса через браузер: имя и идентификатор бота и список разрешений.

Как прочитать сообщения пользователей бота: метод getUpdates

Пользователи могут активировать нашего бота и общаться с ним. Мы же можем получать эти сообщения и обрабатывать на своём сервере. Давайте напишем боту и попробуем прочитать чат с помощью Telegram Bot API.

Поздороваемся с ботом
Скриншот: Telegram / Skillbox Media

Список сообщений можно получить с помощью HTTP-метода getUpdates. Для этого просто перейдите в браузере по следующему адресу:

https://api.telegram.org/bot7432444009:AAG62HGsVhddP5kq5Cbdf1ugTcYpTriV1Mg/getUpdates

В браузере появится следующий JSON-код:

{ “ok”:true, “result”: { “update_id”:123456789, “message”: { “message_id”:1, “from”: { “id”:123456789, “is_bot”:false, “first_name”:”user”, “username”:”user”, “language_code”:”ru”, “is_premium”:true }, “chat”: { “id”:123456789, “first_name”:”user”, “username”:”user”, “type”:”private” }, “date”:123456789, “text”:”Hello!” } } }

В нём:

• update_id — уникальный номер обращения к боту;
• message — большой блок со всеми метаданными сообщения;
• message_id — ID сообщения в чате;
• from — блок со всеми данными отправителя, включая ID пользователя, имя, никнейм и сведения о наличии подписки Telegram Premium;
• chat — блок с информацией о чате, включая ID, никнейм и тип (публичный или приватный);
• date — дата отправления;
• text — текст сообщения.

Также запрос getUpdates можно отправить с помощью Python:

import requests # Токен бота и HTTP-запрос bot_token = “7432444009:AAG62HGsVhddP5kq5Cbdf1ugTcYpTriV1Mg” url = f”https://api.telegram.org/bot{bot_token}/getUpdates” response = requests.get(url) # Обработка ответа сервера if response.status_code == 200: json_data = response.json() print(“Ответ API:”, json_data) else: print(f”Ошибка: {response.status_code}”)

Как отправить сообщение: метод sendMessage

Теперь попробуем ответить на наше же сообщение от имени бота. Для этого воспользуемся методом sendMessage. Он немного сложнее предыдущих и требует передать на вход дополнительные параметры: ID чата и текст сообщения. В общем виде метод выглядит так:

https://api.telegram.org/bot{ТОКЕН}/sendMessage? chat_id={ID-ЧАТА}& text={СООБЩЕНИЕ}

В нём:

• {ТОКЕН} — токен, который нам выдал BotFather;
• {ID-ЧАТА} — уникальный номер чата, в который бот отправит сообщение. Этот номер можно посмотреть в поле «chat»: {“id»: 123456789}, выполнив запрос getUpdates;
• {СООБЩЕНИЕ} — текст сообщения.

Отправим сообщение «Привет!»:

https://api.telegram.org/bot7432444009:AAG62HGsVhddP5kq5Cbdf1ugTcYpTriV1Mg/sendMessage?chat_id=123456789&text=Привет!

Если вы всё сделали правильно, то в чате появится сообщение от имени бота.

Бот отправил в чат текст, который мы указали в запросе
Скриншот: Telegram / Skillbox Media

С помощью Python запрос sendMessage можно отправить так:

import requests # Токен бота и HTTP-запрос bot_token = “7432444009:AAG62HGsVhddP5kq5Cbdf1ugTcYpTriV1Mg” chat_id = “123456789” message_text = “Привет!” url = f”https://api.telegram.org/bot{bot_token}/sendMessage” # Параметры запроса params = { “chat_id”: chat_id, “text”: message_text } response = requests.get(url, params=params) # Обработка ответа сервера if response.status_code == 200: json_data = response.json() print(“Ответ API:”, json_data) else: print(f”Ошибка: {response.status_code}”)

Как отправить стикер

Для отправки стикеров в Bot API есть метод sendSticker. Чаще всего этот запрос получается довольно длинным из-за объёмного ID стикера, поэтому вместо браузера удобнее использовать Python. В теле запроса надо обязательно передать токен бота, ID чата и стикера.

Как получить первые два параметра, мы уже знаем из примеров выше. Чтобы получить ID стикера, сделайте следующее:

• Шаг 1. Отправьте в чат с ботом нужный стикер.
• Шаг 2. Выполните в браузере запрос getUpdates.
• Шаг 3. В JSON-ответе найдите данные последнего сообщения.
• Шаг 4. В поле file_id будет ID стикера. Например: «file_id»:”CAACAgIAAxkBAAENhyhn18v1vykSL7iweWj0syat7KNAPwACmEcAAkYhyUrp2ZMtEnJVtTYE».

Код запроса на Python выглядит так:

import requests # Токен бота и HTTP-запрос bot_token = “7432444009:AAG62HGsVhddP5kq5Cbdf1ugTcYpTriV1Mg” chat_id = “123456789” sticker_id = “CAACAgIAAxkBAAENhyhn18v1vykSL7iweWj0syat7KNAPwACmEcAAkYhyUrp2ZMtEnJVtTYE” url = f”https://api.telegram.org/bot{bot_token}/sendSticker” # Параметры запроса params = { “chat_id”: chat_id, “sticker”: sticker_id } response = requests.get(url, params=params) # Обработка ответа сервера if response.status_code == 200: json_data = response.json() print(“Ответ API:”, json_data) else: print(f”Ошибка: {response.status_code}”)

Если запустить код в IDE, то бот пришлёт указанный стикер в чат.

Бот прислал стикер, ID которого мы указали в коде запроса
Скриншот: Telegram / Skillbox Media

Какие ещё методы есть в Telegram Bot API

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

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

Вот некоторые из доступных методов в Bot API:

• forwardMessage — пересылает сообщение пользователя в другой чат;
• copyMessage — копирует сообщение;
• sendPhoto — отправляет изображение;
• sendVoice — отправляет голосовое сообщение;
• sendPoll — запускает в чате опрос;
• getUserProfilePhotos — получает аватарку пользователя;
• banChatMember — блокирует пользователя в групповом чате;
• createChatInviteLink — создаёт ссылку-приглашение в групповой чат;
• setChatPhoto — устанавливает аватарку группового чата;
• setChatTitle — устанавливает название группового чата;
• getChatAdministrators — получает список администраторов;
• setMyCommands — метод для замены списка команд бота;
• setMyName — метод для смены имени бота.

Сочетая методы Bot API можно создавать ботов со сложной логикой. Главное преимущество «чистого» API перед библиотеками в том, что запросы можно отправлять с помощью любого языка программирования или вообще без кода. Это даёт больше преимуществ разработчикам, которые создают ботов на непопулярных языках программирования.

Главный минус работы с Bot API напрямую в том, что каждый раз приходится использовать много кода даже для простых запросов. Кроме того, надо разработать алгоритм, который может быстро получать сообщения из чата с пользователем и анализировать их. Это усложняет процесс создания ботов, поэтому вместо Bot API лучше использовать специальные библиотеки.

Библиотеки для разработки телеграм-ботов

Для разработчиков ботов есть специальные библиотеки на базе Bot API, которые упрощают процесс отправки запросов. Они помогают сократить количество кода в проекте и предоставляют готовые алгоритмы мониторинга новых сообщений и обработки команд. С такими библиотеками разработка бота становится похожа на сборку конструктора — просто берём нужные функции, связываем их друг с другом и событиями в чате.

Рассмотрим популярные библиотеки для создания телеграм-ботов на разных языках программирования.

Библиотеки для создания ботов на Python

Python — самый популярный язык в сообществе разработчиков ботов. В большинстве гайдов, курсов и уроков именно на нём показывают все примеры кода. Для Python есть следующие библиотеки:

Библиотеки для JavaScript и Node.js

Второй по популярности язык программирования для разработки телеграм-ботов — JavaScript. Для него и платформы Node.js тоже есть много обучающих материалов и библиотек. Ниже список популярных решений:

Библиотеки для других языков программирования

Одно из преимуществ открытого Bot API в том, что сторонние разработчики могут создавать на его базе собственные библиотеки для любых языков программирования. Поддерживают их не так активно, как решения для Python и JavaScript, но базовые функции всегда работают. Ниже список библиотек для разных языков программирования.

Что запомнить

• Telegram Bot API — это набор HTTP-методов, с помощью которых можно отправлять запросы к серверу Telegram, получать ответы в формате JSON и управлять ботами.
• При использовании Bot API важно учитывать ограничения на количество запросов и соблюдать рекомендации по безопасности, чтобы избежать блокировок бота.
• Открытый API позволяет сторонним разработчикам использовать любые языки программирования для управления ботами.
• Работать напрямую с серверами Telegram сложно и не всегда рационально: код получается сложным, запутанным и надо самостоятельно реализовывать многие алгоритмы.
• В качестве альтернативы можно использовать готовые библиотеки на базе Bot API. Существуют библиотеки для разных языков программирования, но авторы и сообщество активно поддерживают только решения для Python и JavaScript.