Telegram Bot API: гайд для разработчиков ботов
2026-02-21 03:03 Diff
https://skillbox.ru/media/code/telegram-bot-api/

#статьи

  • 20 мар 2025
  • 0

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

Иллюстрация: Оля Ежак для Skillbox Media

Программист, консультант, специалист по документированию. Легко и доступно рассказывает о сложных вещах в программировании и дизайне.

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

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

Эксперт

Principal Software Engineer, эксперт Skillbox по бэкенду и Java в коммерческой разработке.

Содержание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Шаг 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 } }

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

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

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

Все методы подробно описаны в официальной документации 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 есть следующие библиотеки:

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

Второй по популярности язык программирования для разработки телеграм-ботов — 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, но базовые функции всегда работают. Ниже список библиотек для разных языков программирования.

НазваниеЯзык программированияСсылкаPHP Telegram BotPHPGitHubTelegram Bot Java LibraryJavaGitHubTelegram.Bot.NETGitHubTgbot-cppC++GitHubKotlin Telegram BotKotlinGitHubSwift Telegram SDKSwiftGitHubTelegram-bot-rubyRubyGitHub
  • Telegram Bot API — это набор HTTP-методов, с помощью которых можно отправлять запросы к серверу Telegram, получать ответы в формате JSON и управлять ботами.
  • При использовании Bot API важно учитывать ограничения на количество запросов и соблюдать рекомендации по безопасности, чтобы избежать блокировок бота.
  • Открытый API позволяет сторонним разработчикам использовать любые языки программирования для управления ботами.
  • Работать напрямую с серверами Telegram сложно и не всегда рационально: код получается сложным, запутанным и надо самостоятельно реализовывать многие алгоритмы.
  • В качестве альтернативы можно использовать готовые библиотеки на базе Bot API. Существуют библиотеки для разных языков программирования, но авторы и сообщество активно поддерживают только решения для Python и JavaScript.
Курс: «Создание Telegram-бота и продвижение в мессенджерах» Узнать больше