Как устроен Telegram Bot API: апдейты, методы и токен

Коротко: как это устроено

Telegram Bot API — это HTTP-интерфейс между вашей программой и Telegram. Модель простая:

• Вы → Telegram: отправляете HTTP-запрос к методу (sendMessage, sendPhoto и т. д.) и получаете JSON-ответ.
• Telegram → вы: всё, что происходит с ботом (сообщения, нажатия кнопок, оплаты), приходит в виде объектов Update.

Каждый запрос подписан токеном бота — он прямо входит в адрес. Библиотеки вроде aiogram, python-telegram-bot или grammY делают то же самое, просто удобнее.

Адрес запроса и токен

Все методы вызываются по одному шаблону:

https://api.telegram.org/bot<TOKEN>/<METHOD_NAME>

Токен выдаёт @BotFather при создании бота. Он выглядит как число, двоеточие и длинная строка символов. Важно понимать:

• токен — это полный доступ к боту: кто его знает, тот может читать входящие сообщения и писать от имени бота;
• его нельзя хранить в публичном репозитории или во фронтенде — только в переменных окружения или секретах сервера;
• при утечке токен перевыпускают через @BotFather, старый сразу перестаёт работать.

Самая простая проверка — метод getMe:

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

Формат ответа

Любой ответ — JSON с полем ok:

{"ok": true, "result": {"id": 123456789, "is_bot": true, "first_name": "Demo", "username": "demo_bot"}}

При ошибке ok равно false, а рядом приходят error_code и description. Самые частые:

Объект Update

Каждое входящее событие — это Update с уникальным update_id и одним из полей: message, edited_message, callback_query, channel_post, inline_query, pre_checkout_query, my_chat_member и другие.

{
  "update_id": 100000001,
  "message": {
    "message_id": 5,
    "from": {"id": 123456789, "is_bot": false, "first_name": "Ali"},
    "chat": {"id": 123456789, "type": "private"},
    "date": 1700000000,
    "text": "/start"
  }
}

Главное, что нужно из апдейта, — chat.id: именно туда бот отправит ответ.

Получить апдейты можно двумя способами:

• getUpdates — ваш код сам периодически спрашивает Telegram о новых событиях и передаёт offset (последний update_id + 1), чтобы не получать одно и то же повторно;
• webhook — Telegram сам отправляет каждый апдейт POST-запросом на ваш HTTPS-адрес.

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

Основные методы

• sendMessage — текст с разметкой и кнопками.
• sendPhoto, sendDocument, sendVideo — медиа и файлы.
• editMessageText, deleteMessage — изменить или удалить своё сообщение.
• answerCallbackQuery — подтвердить нажатие inline-кнопки, иначе у пользователя будет висеть индикатор загрузки.
• setMyCommands — меню команд бота.
• setWebhook, getWebhookInfo, deleteWebhook — управление доставкой апдейтов.

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

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Привет! Выберите действие:", "reply_markup": {"inline_keyboard": [[{"text": "Каталог", "callback_data": "catalog"}]]}}'

Параметры можно передавать в query string, как form-data или как JSON. Файлы загружаются через multipart/form-data.

Частые ошибки новичков

• Не передавать offset в getUpdates и получать одни и те же сообщения по кругу.
• Не отвечать на callback_query — кнопка «зависает».
• Игнорировать ошибку 429 и продолжать слать запросы без паузы.
• Не обрабатывать 403: пользователь заблокировал бота, и его нужно убрать из рассылки.

Полный список методов и типов — в официальной документации Bot API.