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

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

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

Содержание

• Что такое Telegram Bot API
• Какие API есть в Telegram
• Как создать бота в Telegram
• Ограничения ботов
• Как взаимодействовать с ботом через Bot API
• Как прочитать сообщение
• Как отправить сообщение
• Как отправить стикер
• Какие ещё методы есть в Telegram Bot API
• Библиотеки для разработки телеграм-ботов

Что такое Telegram Bot API

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

API (application programming interface, программный интерфейс приложения) — это набор методов, с помощью которых различные сервисы и программы обмениваются данными между собой. Разработчики используют API для того, чтобы получить от сервиса нужную информацию или заставить его выполнить определённое действие.

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

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

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

Читайте также:

Что такое API и как он работает

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

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

• Telegram API — низкоуровневый интерфейс, на базе которого реализованы основные функции Telegram, включая криптографический протокол MTProto. Официальные клиенты Telegram используют методы из этого набора.
• Bot API — HTTP-интерфейс, созданный для разработки ботов, внутренних мини-приложений и веб-игр. Благодаря ему программистам не надо разбираться в устройстве Telegram API для отправки сообщений и получения данных из чатов с пользователями в реальном времени. Достаточно отправить HTTP-запрос, получить ответ в формате JSON и обработать его.
• TDLib — библиотека, предназначенная для разработки альтернативных клиентов Telegram. Если вам кажется, что в приложении мессенджера нет какой-то важной функции, то с помощью TDLib можно создать собственное приложение и опубликовать его в интернете.
• Gateway API — набор методов для отправки кодов авторизации через Telegram. Обычно компании отправляют коды с помощью SMS, но благодаря Gateway API можно сэкономить на оплате мобильной связи.
• Bot Payments API — платформа для обработки платежей в телеграм-ботах. С её помощью разработчики могут получать деньги от пользователей за товары и услуги.

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

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

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

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

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

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

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

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

7582552655:AAHmzfaKaoMnajrk47dLS76S2epa127gJ-0

Сохраните токен в надёжном месте и никому не показывайте. Если злоумышленники завладеют им, то смогут контролировать вашего бота, собирать данные пользователей и перенаправлять платежи. В случае утечки сгенерируйте новый токен с помощью команды /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
    }
 }

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

Читайте также:

JSON: что это за формат и как с ним работать

С помощью 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-файла. Ответ будет содержать всё то же самое, что и при отправке запроса через браузер: имя и идентификатор бота и список разрешений.

Читайте также:

Библиотека Requests для Python: код и практика

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

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

Список сообщений можно получить с помощью 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=Привет!

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

С помощью 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, то бот пришлёт указанный стикер в чат.

Какие ещё методы есть в 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 есть следующие библиотеки:

• Aiogram — асинхронная библиотека для создания высоконагруженных ботов. Чаще всего именно её используют в масштабных проектах с десятками тысяч ежедневных пользователей. Разработчики Aiogram часто обновляют библиотеку и быстро внедряют новые функции Bot API.
• TeleBot — одна из первых библиотек для Python. Обновления для неё выходят редко, а боты на базе TeleBot не справляются с большим количеством запросов. Из-за простого синтаксиса решение подойдёт новичкам, которые только изучают возможности Bot API.
• Python-telegram-bot — библиотека с асинхронным и синхронным режимами работы. По возможностям и сложности находится между Aiogram и TeleBot. Обновления также выходят с интервалом в несколько месяцев.

Читайте также:

Чат-боты в Telegram на Python и Aiogram: пишем первого бота

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

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

• Telegraf.js — фреймворк с поддержкой JavaScript и TypeScript. Поддерживает основные функции мессенджера и выполняет код асинхронно.
• GrammY — библиотека для разработки ботов на JavaScript и TypeScript, которых можно запускать в Node.js и Deno. Если вы уже создавали веб-проекты с нуля, то сможете быстро научиться писать код для телеграм-ботов. Во всяком случае, это гарантируют авторы GrammY.
• Node.js Telegram Bot API — простая библиотека для Node.js. Обновления для неё выходят редко.

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

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

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

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