Telegram Bot API: обзор документации и примеры кода

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

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

Telegram Bot API - это набор HTTP-запросов, через которые вы общаетесь с ботом, созданным в Telegram. Он не требует установки специального ПО на вашем устройстве. Всё происходит через интернет: вы отправляете команду, Telegram отвечает, и бот делает то, что вы попросили. Это как писать письма, но вместо почты - JSON-запросы.

Боты в Telegram не являются обычными пользователями. Они работают через токен - уникальную строку, которую вы получаете от @BotFather при создании бота. Этот токен - ваш ключ доступа. Без него никто не сможет управлять вашим ботом. Не передавайте его никому. Не храните в открытом виде в коде на GitHub. Это не просто пароль - это идентификатор вашего бота в системе Telegram.

Как начать: создание бота и получение токена

Первый шаг - создать бота. Откройте Telegram, найдите @BotFather и начните чат. Напишите команду /newbot. BotFather спросит имя бота - это то, что увидят пользователи. Затем - имя пользователя (username), которое должно заканчиваться на bot, например, mycoolbot. После этого вы получите токен - длинную строку вроде 123456789:ABCdefGhIJKlmnoPqrStUvwxYz1234567.

Сохраните его. Это ваш главный секрет. Теперь вы можете начать отправлять запросы к API. Простейший запрос - получить информацию о боте. Откройте браузер и перейдите по ссылке:

https://api.telegram.org/botВАШ_ТОКЕН/getMe

Вы увидите JSON-ответ с именем, username и ID бота. Это значит: всё работает. Бот существует, токен верный, и API доступен.

Основные методы API: что можно делать

Telegram Bot API предоставляет более 50 методов. Но вам хватит 5 для старта:

• getUpdates - получает все входящие сообщения, которые бот ещё не обработал.
• sendMessage - отправляет текстовое сообщение пользователю.
• sendPhoto - отправляет фото по URL или файлу.
• setWebhook - настраивает постоянный канал связи с вашим сервером (вместо постоянного опроса).
• deleteWebhook - отключает вебхук, если вы хотите вернуться к опросу.

Пример отправки сообщения:

https://api.telegram.org/botТОКЕН/sendMessage?chat_id=123456789&text=Привет!

Здесь chat_id - уникальный идентификатор пользователя или чата. Его можно узнать, отправив боту сообщение и вызвав getUpdates. Ответ покажет структуру с полем from.id - это и есть ваш ID.

Пример на Python: простой бот-ответчик

Вот минимальный рабочий бот на Python с использованием библиотеки requests:

import requests
import time

TOKEN = "123456789:ABCdefGhIJKlmnoPqrStUvwxYz1234567"
BASE_URL = f"https://api.telegram.org/bot{TOKEN}"

last_update_id = 0

while True:
    response = requests.get(f"{BASE_URL}/getUpdates?offset={last_update_id + 1}")
    data = response.json()

    if data["result"]:
        for update in data["result"]:
            chat_id = update["message"]["chat"]["id"]
            text = update["message"]["text"]

            if text == "/start":
                requests.get(f"{BASE_URL}/sendMessage?chat_id={chat_id}&text=Привет! Напиши \"привет\".")
            elif "привет" in text.lower():
                requests.get(f"{BASE_URL}/sendMessage?chat_id={chat_id}&text=Привет! Как дела?")

            last_update_id = update["update_id"]

    time.sleep(1)

Этот бот ждёт сообщений, проверяет, есть ли в них слово «привет», и отвечает. Он работает в цикле, опрашивая API каждую секунду. Это называется polling - постоянный запрос новых данных. Подходит для маленьких ботов, но не для масштабных проектов.

Что лучше: polling или webhook?

В приведённом примере бот «спрашивает» Telegram каждую секунду: «Есть новые сообщения?». Это неэффективно. Если у вас 1000 пользователей, и каждый отправляет по 5 сообщений в день - вы делаете 5000 запросов в сутки. Telegram разрешает до 30 запросов в секунду, но это лишняя нагрузка.

Лучше использовать webhook. Это когда Telegram сам отправляет вам сообщение, как только кто-то пишет боту. Вам нужен сервер с публичным HTTPS-адресом. Вы отправляете один запрос:

https://api.telegram.org/botТОКЕН/setWebhook?url=https://ваш-сайт.ру/webhook

Теперь Telegram будет отправлять все сообщения на этот URL в формате JSON. Вы обрабатываете их на сервере - и всё. Нет нужды в циклах, нет задержек. Бот отвечает мгновенно.

Для этого вам понадобится хотя бы минимальный веб-сервер. Например, на Python - Flask или FastAPI. Вот простой пример на Flask:

from flask import Flask, request
import requests

app = Flask(__name__)
TOKEN = "123456789:ABCdefGhIJKlmnoPqrStUvwxYz1234567"

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    if 'message' in data:
        chat_id = data['message']['chat']['id']
        text = data['message']['text']
        
        if text == '/start':
            requests.post(f"https://api.telegram.org/bot{TOKEN}/sendMessage", json={
                'chat_id': chat_id,
                'text': 'Привет! Я бот на webhook.'
            })
    return 'OK'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Запустите его, настройте NGINX или используйте ngrok для тестирования, установите вебхук - и ваш бот работает в реальном времени.

Что можно сделать с ботом?

Боты - это не просто ответчики. Вот реальные примеры, которые работают прямо сейчас:

• Бот-напоминалка - отправляет сообщения в 9 утра с погодой и списком дел.
• Бот-квест - предлагает загадки, пользователь отвечает, бот проверяет и даёт следующую.
• Бот-доставки - принимает заказы, формирует чек, отправляет в Telegram-канал повара.
• Бот-аналитик - парсит сайт, отправляет уведомления, если цена на товар упала.
• Бот-поддержка - отвечает на часто задаваемые вопросы, перенаправляет сложные запросы человеку.

Все они используют одни и те же методы API. Разница - только в логике. Бот не думает. Он выполняет инструкции. Ваша задача - написать эти инструкции правильно.

Что нельзя делать

Telegram не запрещает ботов, но есть правила, которые нарушать нельзя:

• Нельзя использовать бота для рассылки спама - даже если пользователь подписался. Если он не просил сообщения - вы нарушаете правила.
• Нельзя создавать ботов, которые имитируют людей. Telegram может заблокировать бота, если он ведёт себя как реальный пользователь.
• Нельзя хранить токены в открытом виде. Даже в GitHub-репозиториях. Используйте переменные окружения.
• Нельзя обходить ограничения: например, отправлять 100 сообщений в секунду. API имеет лимиты - 30 запросов в секунду на токен.

Нарушение правил - и ваш бот будет заблокирован. Без предупреждения. Без возможности восстановления.

Где учиться дальше

Документация Telegram Bot API - самая чёткая среди всех API. Она есть на английском, но понятна даже без знания языка: core.telegram.org/bots/api. Там перечислены все методы, параметры, примеры ответов. Каждый метод - с описанием, типами данных и примерами.

Для Python - библиотека python-telegram-bot упрощает жизнь. Она берёт на себя работу с запросами, обработку ошибок, таймауты. Для Node.js - node-telegram-bot-api. Для PHP - irazasyed/telegram-bot-sdk.

Но начинать лучше без библиотек. Поймите, как работает API вручную - через HTTP-запросы. Тогда любая библиотека станет понятной.

Частые ошибки и как их избежать

1. Неправильный chat_id - вы отправляете сообщение боту, но не знаете, как получить ID пользователя. Решение: используйте getUpdates, найдите message.from.id.
2. Токен в коде - вы залили код на GitHub и забыли убрать токен. Решение: используйте файл .env и библиотеку python-dotenv.
3. Бот не отвечает - вы думаете, что он сломался. На самом деле, вы не установили вебхук или не запустили polling. Проверьте: вызовите getMe - если возвращает данные, бот жив. Проверьте логи сервера - если запросы не приходят, проблема в вебхуке.
4. Слишком медленный ответ - если ваш сервер отвечает дольше 10 секунд, Telegram считает это ошибкой и перестаёт отправлять сообщения. Ускоряйте обработку - используйте асинхронные запросы или очередь.

Безопасность: как не стать жертвой

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

• Всегда проверяйте, кто отправил сообщение. Не доверяйте chat_id без проверки. Храните список разрешённых ID.
• Никогда не выполняйте команды, которые приходят в виде текста, без фильтрации. Не позволяйте боту запускать rm -rf / через команду /delete.
• Используйте аутентификацию. Если бот управляет домом - требуйте пароль или код подтверждения.
• Логируйте действия. Если бот внезапно начал отправлять 500 сообщений - вы сразу увидите это в логах.

Бот - это не игрушка. Это сервис. И если он работает на реальных людях - его нужно защищать как любой веб-сервис.