Telegram Bot API: создаем своего первого бота

Самый быстрый способ освоить Telegram Bot API — это три команды: получить токен от BotFather, вызвать getUpdates для чтения сообщений и sendMessage для ответа. Все остальное в разработке ботов строится на этом цикле. Это руководство проведет вас по всему пути: от первого запроса cURL до работающего бота с вебхуком и библиотекой.

Bot API — это HTTP-интерфейс, что означает, что вы можете протестировать его с помощью curl еще до того, как напишете хоть одну строчку кода. Это делает его одним из самых дружелюбных API для изучения. Если вы разработчик, который хочет получить работающего бота сегодня, или создатель, взвешивающий код против платформы без кода, такой как TeleClaw, вы попали по адресу.

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

Ключевые выводы

• Бот — это просто HTTP-клиент. Каждый метод — это запрос к https://api.telegram.org/bot<TOKEN>/METHOD_NAME, поэтому curl достаточно для начала.
• Три основных метода для запуска: getMe для проверки токена, getUpdates для чтения сообщений и sendMessage для ответа.
• Long polling и вебхуки взаимоисключающи. Используйте long polling для локального тестирования, переключайтесь на вебхук для продакшена.
• API бесплатен, но Telegram ограничивает массовую рассылку примерно 30 сообщениями в секунду разным пользователям и одним сообщением в секунду на чат.
• Библиотека экономит время, когда ваш бот вырастает из простого скрипта. Используйте python-telegram-bot, aiogram или Telegraf.

Что такое Telegram Bot API?

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

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

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

Шаг 1: Получаем токен бота от BotFather

Откройте Telegram и найдите @BotFather — официального бота для создания и управления другими ботами. Начните чат и отправьте команду /newbot.

BotFather затем задаст два вопроса по порядку:

1. Отображаемое имя для вашего бота, например “Мой первый API-бот”.
2. Имя пользователя, которое заканчивается на bot, например first_api_demo_bot.

Когда вы закончите, BotFather вернет API-токен, который выглядит как 123456789:AAExampleTokenStringHere. Этот токен — единственное, что вам понадобится для остальной части этого руководства.

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

Шаг 2: Вызываем первый метод Bot API

Прежде чем писать какую-либо программу, убедитесь, что токен работает. Метод getMe возвращает основную информацию о вашем боте и является стандартной проверкой работоспособности. Замените <YOUR_TOKEN> значением, полученным от BotFather.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Успешный ответ — это JSON с "ok": true и ID, именем и именем пользователя вашего бота. Если вы видите "ok": false, токен неверен или содержит опечатку.

Этот единственный запрос — это весь шаблон. Каждый метод Telegram Bot API имеет одинаковую структуру: HTTPS-вызов к https://api.telegram.org/bot<TOKEN>/METHOD_NAME, с параметрами в строке запроса или теле POST-запроса, и JSON-объект в ответ. Полный список находится в справочнике Bot API, который документирует каждый метод и объект, которые вам когда-либо понадобятся.

Шаг 3: Получаем и отправляем сообщения

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

Затем прочитайте это сообщение с помощью getUpdates, который получает входящие обновления с использованием long polling и возвращает массив объектов обновлений.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

В ответе найдите message.chat.id. Этот chat_id — адрес, на который вы отвечаете. Скопируйте его, затем вызовите sendMessage:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Привет от моего первого бота"

Ваш бот ответит в чате. Этот цикл, чтение с помощью getUpdates и ответ с помощью sendMessage, является основной логикой большинства Telegram-ботов. Параметр text принимает до 4096 символов на сообщение, поэтому длинные ответы нужно разбивать.

Две детали, которые следует помнить, когда вы масштабируете этот пример Telegram Bot API в реальный код:

• Пересчитывайте смещение. Передавайте update_id последнего обновления плюс один в качестве параметра offset при следующем вызове getUpdates, иначе Telegram будет возвращать одни и те же обновления.
• Один метод за раз. getUpdates перестает работать в тот момент, когда вы регистрируете вебхук, что является темой следующего шага.

Шаг 4: Выбираем long polling или вебхук

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

• Long polling означает, что ваш код постоянно вызывает getUpdates. Это самый простой путь для обучения и локальной разработки, потому что он не требует публичного URL, только постоянно работающего процесса.
• Вебхуки означают, что Telegram отправляет каждое обновление на вашу HTTPS-конечную точку в виде POST-запроса в тот момент, когда оно происходит. Это стандарт для продакшена: меньшая задержка, отсутствие простоя при опросе, и он лучше масштабируется при постоянном трафике.

Чтобы переключиться на вебхук, зарегистрируйте свой публичный HTTPS-URL один раз:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"

Ваша конечная точка должна иметь действительный TLS-сертификат и быстро возвращать HTTP 200. Если обновления перестают приходить, первым делом всегда проверяйте ошибку. Для полного процесса регистрации, верификации и устранения неполадок см. наше руководство по настройке вебхука Telegram-бота. Краткая версия: начните с long polling во время разработки, переходите на вебхук перед запуском.

Шаг 5: Оборачиваем API в библиотеку

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

Выбирайте по языку, который вы уже знаете:

• Python: python-telegram-bot — это чистый Python, полностью асинхронный, поддерживает Python 3.10 и выше. aiogram и pyTelegramBotAPI — популярные альтернативы.
• Node.js: Telegraf — зрелый и дружелюбный к TypeScript. node-telegram-bot-api — давно существующий вариант.

Вот тот же эхо-бот на Python, наиболее распространенная отправная точка для руководства по Telegram Bot API на Python:

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

И эквивалент на Node.js с Telegraf:

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

Оба делают ту же работу, что и цикл cURL из Шага 3, но в нескольких строках и с обработкой всех сложных моментов за вас. Мария, бэкенд-разработчик, прототипирующая бота поддержки, перешла от cURL-тестов к python-telegram-bot за один день и в тот же день запустила обработчики команд и инлайн-кнопки. Концепции API напрямую перенеслись, потому что библиотека — это тонкая обертка над теми же HTTP-методами.

Лимиты и квоты, о которых нужно знать

API бесплатен, но не безграничен. В FAQ по ботам Telegram приведены рекомендации, которые помогут избежать троттлинга вашего бота.

• Одно сообщение в секунду на чат. В одном разговоре избегайте отправки быстрее.
• Около 30 сообщений в секунду всего при отправке многим разным пользователям. Превышение этого лимита приведет к получению HTTP 429 “Too Many Requests” ответов.
• Примерно 20 сообщений в минуту в одну и ту же группу.

Когда рассылка действительно требует большего, вы можете включить «Платные рассылки» в @BotFather, что увеличит лимит до 1000 сообщений в секунду. Сообщения сверх бесплатных 30 в секунду стоят 0.1 Telegram Stars каждое. Большинству ботов это никогда не понадобится, но хорошо знать о существовании этого лимита, прежде чем разрабатывать функцию уведомлений.

Уважайте 429, считывая значение retry_after, которое возвращает Telegram, и делая паузу на указанное количество секунд. Библиотека сделает это за вас, что является еще одной причиной перейти от сырых запросов, как только ваш трафик станет реальным.

Пропускаем код: AI-боты без сервера

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

TeleClaw — это платформа без кода, которая запускает бота за вас и подключает Claude AI “из коробки”. Вы добавляете @claw в свою группу, вставляете токен BotFather в дашборд и настраиваете поведение, не касаясь setWebhook или обработки лимитов. Томас, который управляет криптосообществом из 4000 участников, заменил наполовину готового кастомного бота на TeleClaw и запустил AI-модерацию и ответы на часто задаваемые вопросы в тот же вечер.

В основе лежит тот же Bot API. Вы выбираете, управлять ли серверным уровнем самостоятельно или доверить это платформе. Изучите, что это включает, на странице функций TeleClaw и сравните варианты в нашем обзоре лучших Telegram-ботов 2026 года. Для создания бота исключительно через дашборд, см. наше руководство по созданию Telegram-чатбота без кода.

Заключение

Теперь у вас есть рабочая модель Telegram Bot API: токен от BotFather, HTTP-методы, такие как getMe, getUpdates и sendMessage, выбор между long polling и вебхуками, а также библиотека для обертывания всего этого, когда ваш бот вырастет. API бесплатен, хорошо документирован и достаточно прост, чтобы протестировать его с помощью cURL за считанные минуты.

Самый быстрый следующий шаг — самый маленький. Откройте @BotFather, запустите /newbot и отправьте свой первый запрос getMe, чтобы подтвердить токен. Оттуда вы можете разрабатывать на Python или Node, или вообще обойтись без сервера. Чтобы запустить AI-бота за считанные минуты вместо дней, добавьте @claw в свою группу и настройте его в дашборде TeleClaw.