Telegram Bot API: как получить токен, получать обновления и отправлять сообщения

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

Для первого рабочего бота не нужно сразу разбираться во всей документации Bot API. Достаточно пройти короткую цепочку:

BotFather
↓
токен
↓
getMe
↓
getUpdates
↓
chat_id
↓
sendMessage

После этого уже можно подключать webhook, базу данных, бизнес-логику и полноценный backend.

В этой инструкции разберём именно такой путь: от получения токена до первого сообщения через API.

Что такое Telegram Bot API

Telegram-бот сам по себе не содержит бизнес-логики.

BotFather создаёт учётную запись бота внутри Telegram, а ваша программа решает, что бот должен делать.

Упрощённо архитектура:

Пользователь Telegram
↓
Telegram
↓
Bot API
↓
ваша программа
↓
база данных / CRM / API / бизнес-логика

Например, пользователь пишет:

/start

Telegram создаёт соответствующее обновление.

Ваша программа получает его через Bot API, определяет команду и может отправить ответ:

Здравствуйте! Чем могу помочь?

Bot API представляет собой HTTP-интерфейс для разработки Telegram-ботов.

Как выглядит запрос к Bot API

Общая форма:

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

Где:

<TOKEN>

— токен вашего бота, а:

<METHOD>

— метод Bot API.

Примеры:

getMe
getUpdates
sendMessage
setWebhook
getWebhookInfo

Как получить токен Telegram-бота

Для создания обычного бота используется официальный @BotFather.

Последовательность:

1. открыть @BotFather в Telegram;
2. отправить /newbot;
3. указать имя бота;
4. выбрать username;
5. получить токен.

Токен выглядит примерно так:

1234567890:AAExampleTokenDoNotUseInRealProject

Это вымышленный пример.

Токен — секрет.

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

Где нельзя хранить токен

Не стоит помещать настоящий токен:

• в публичный GitHub;
• в JavaScript frontend;
• в HTML страницы;
• в Telegram-канал;
• в скриншоты;
• в публичную документацию.

В рабочем проекте его обычно хранят в environment variable:

TELEGRAM_BOT_TOKEN=...

а приложение получает значение только на сервере.

Что делать, если токен попал в открытый доступ

Не ограничиваться удалением сообщения или commit.

Считать токен скомпрометированным и заменить его через BotFather.

Как проверить токен через getMe

После получения токена первый полезный метод:

getMe

Он позволяет проверить:

• принимается ли токен;
• существует ли бот;
• к какому боту относится токен.

Пример через curl:

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

Использовать placeholder <TOKEN>, никогда не вставлять настоящий секрет.

Пример ответа:

{
  "ok": true,
  "result": {
    "id": 1234567890,
    "is_bot": true,
    "first_name": "Example Bot",
    "username": "example_test_bot"
  }
}

Главный признак успешного запроса:

"ok": true

Если getMe не работает

Проверить:

• токен скопирован полностью;
• нет лишнего пробела;
• используется токен нужного бота;
• токен не был отозван;
• запрос идёт к api.telegram.org.

Пока getMe не заработал, не нужно диагностировать sendMessage, webhook или обработчики команд.

Как получать сообщения через getUpdates

После проверки токена нужно увидеть сообщения пользователей.

Для этого используется:

getUpdates

Он получает входящие updates через long polling.

Telegram поддерживает два основных способа:

getUpdates
или:
webhook

При установленном webhook getUpdates использовать нельзя.

Самая простая проверка

Сначала открыть бота в Telegram и отправить:

/start

или:

Привет

После этого:

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

Пример ответа:

{
  "ok": true,
  "result": [{
    "update_id": 123456789,
    "message": {
      "message_id": 10,
      "from": { "id": 111111111, "first_name": "Иван" },
      "chat": { "id": 111111111, "type": "private" },
      "text": "Привет"
    }
  }]
}

Здесь важны:

update_id
message
from
chat
text

Что такое Update

Telegram передаёт события боту в виде объектов Update.

Update может содержать:

• новое сообщение;
• изменённое сообщение;
• нажатие inline-кнопки;
• событие канала;
• изменение состояния участника;
• другие события Bot API.

Production-код не должен предполагать, что в каждом Update обязательно существует:

message.text

Тип обновления нужно проверять.

Почему getUpdates возвращает одни и те же сообщения

У каждого обновления есть:

update_id

Чтобы Telegram понял, что обновление обработано, следующий запрос делают с offset, превышающим последний обработанный update_id.

Например:

"update_id": 100500

Следующий offset:

offset=100501

Упрощённая схема:

получили update_id = 100
↓
обработали
↓
следующий offset = 101

Production-приложение должно делать это автоматически.

Как узнать chat_id Telegram-бота

Для sendMessage нужен получатель:

chat_id

Самый простой способ получить его — через getUpdates.

Пользователь пишет боту, затем в Update смотрим:

"chat": {
  "id": 111111111,
  "type": "private"
}

111111111 — chat_id.

Для личного диалога

Обычно:

message.chat.id

Для группы

После добавления бота в группу сообщения содержат chat.id соответствующего чата.

У групп и каналов ID может отличаться по формату.

Не вычислять его вручную — использовать значение из реального Update.

Почему бот не может просто написать любому человеку

Обычный Telegram-бот не может произвольно начать личный диалог с любым пользователем.

Пользователь сначала должен взаимодействовать с ботом либо бот должен находиться в соответствующем чате.

Сценарий:

нашёл username
↓
взял token
↓
sendMessage
↓
написал незнакомому человеку

не является обычным рабочим сценарием Telegram Bot API.

Как отправить сообщение через sendMessage

Когда известны TOKEN и chat_id, используется метод:

sendMessage

Пример:

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d "chat_id=111111111" \
  -d "text=Привет! Бот работает."

Успешный ответ содержит:

{
  "ok": true,
  "result": { "..." : "..." }
}

Минимальная цепочка:

пользователь написал боту
↓
getUpdates
↓
получили chat_id
↓
sendMessage
↓
пользователь получил ответ

Можно ли отправлять только текст

Нет.

Bot API поддерживает методы, например:

sendMessage
sendPhoto
sendDocument
sendVideo
sendLocation

Но первую диагностику всегда лучше начинать с sendMessage.

getUpdates или webhook — что выбрать

Оба способа доставляют программе Telegram Updates.

getUpdates

Схема:

ваш backend
↓
Telegram: есть новые updates?
↓
Telegram отвечает

Это pull-модель.

Для нормальной работы используется long polling.

Плюсы:

• просто начать;
• не нужен публичный webhook endpoint;
• удобно для локальной разработки;
• подходит небольшим ботам.

Webhook

Схема:

Telegram
↓
HTTPS POST
↓
ваш backend

Telegram сам отправляет Update на зарегистрированный URL.

Это push-модель.

Например:

https://example.ru/api/telegram/webhook

Можно ли использовать оба одновременно

Нет.

Если установлен webhook, getUpdates использовать нельзя.

При переходе обратно к polling webhook нужно удалить.

Как настроить webhook Telegram-бота

Для webhook нужен публично доступный HTTPS endpoint.

Например:

https://example.ru/api/telegram/webhook

Backend принимает:

POST

с JSON Update.

Для установки webhook используется:

setWebhook

Пример:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://example.ru/api/telegram/webhook"

Telegram также позволяет использовать secret_token.

Пример:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://example.ru/api/telegram/webhook" \
  -d "secret_token=YOUR_SECRET_VALUE"

На сервере можно проверять header:

X-Telegram-Bot-Api-Secret-Token

Как проверить состояние webhook

Используется:

getWebhookInfo

Пример:

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

Полезные поля:

url
pending_update_count
last_error_date
last_error_message

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

Как удалить webhook

Для возврата к getUpdates:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook"

После удаления webhook можно снова использовать polling.

Первый запрос к Telegram Bot API на Python

Для простого примера использовать requests.

Установка:

pip install requests

Токен не прописывать прямо в исходном коде.

Использовать environment variable:

TELEGRAM_BOT_TOKEN

Проверяем getMe

import os
import requests

token = os.environ["TELEGRAM_BOT_TOKEN"]
url = f"https://api.telegram.org/bot{token}/getMe"
response = requests.get(url, timeout=10)
response.raise_for_status()
print(response.json())

Получаем updates

import os
import requests

token = os.environ["TELEGRAM_BOT_TOKEN"]
url = f"https://api.telegram.org/bot{token}/getUpdates"
response = requests.get(url, params={"timeout": 30}, timeout=35)
response.raise_for_status()
data = response.json()
for update in data["result"]:
    print(update)

Отправляем сообщение

import os
import requests

token = os.environ["TELEGRAM_BOT_TOKEN"]
chat_id = 111111111
url = f"https://api.telegram.org/bot{token}/sendMessage"
response = requests.post(url, json={"chat_id": chat_id, "text": "Привет из Python!"}, timeout=10)
response.raise_for_status()
print(response.json())

Для production дальше понадобятся:

• error handling;
• сохранение состояния;
• защита секретов;
• безопасное логирование;
• дедупликация updates;
• работа с offset;
• retries;
• база данных при необходимости;
• бизнес-логика.

Почему Telegram Bot API не работает

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

Проверять последовательно.

1. Работает ли getMe

getMe → ok: true ?

Если нет — проблема уже на уровне token/API request.

2. Пользователь писал боту?

Если ждём входящий Update — сначала реально отправить боту сообщение.

3. Установлен ли webhook

Если getMe работает, но getUpdates не получает события — проверить:

getWebhookInfo

Если указан webhook URL, getUpdates не будет использоваться одновременно с ним.

4. Правильно ли обрабатывается offset

Если сообщения приходят повторно — проверить:

update_id
offset

5. Правильный ли chat_id

Использовать:

chat.id

из реального Update.

Не путать с:

message_id
update_id
другими user IDs

6. Может ли бот писать этому пользователю

Для личного диалога пользователь должен сначала начать взаимодействие с ботом.

7. Что вернул Bot API

Смотреть HTTP response и JSON.

{
  "ok": false,
  "error_code": "...",
  "description": "..."
}

Поле description часто показывает направление диагностики.

8. Не скрывается ли ошибка библиотекой

Если используется framework:

aiogram
python-telegram-bot
Telegraf
grammY

полезно проверить тот же метод напрямую через curl или простой HTTP request.

Если прямой Bot API работает, а framework нет — область поиска значительно уже.

Что проверить, если бот перестал получать сообщения

Цепочка:

токен
↓
getMe
↓
getWebhookInfo
↓
getUpdates или webhook
↓
backend logs
↓
обработчик Update

Для webhook дополнительно проверить:

• доступен ли endpoint из интернета;
• работает ли HTTPS;
• принимает ли сервер POST;
• нет ли 404/500;
• не блокирует ли firewall/WAF;
• не изменился ли URL;
• есть ли ошибки в getWebhookInfo;
• проходит ли secret_token, если используется.

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

Нужно ли использовать библиотеку для Telegram Bot API

Не обязательно.

Bot API — HTTP API.

Примеры:

Python → requests/httpx
Node.js → fetch
PHP → cURL
Go → net/http

Для сложного бота framework может упростить:

• routing команд;
• callback queries;
• middleware;
• FSM;
• клавиатуры;
• updates;
• retries;
• типизацию объектов.

Схема:

проверить API / простая интеграция
→ прямые HTTP-запросы

полноценный сложный бот
→ framework или специализированная библиотека

При этом понимание базового Bot API полезно даже при использовании framework.

Нужно ли использовать webhook в production

Не обязательно.

Небольшой production-бот может работать через корректный long polling.

Webhook удобен, если уже есть:

• публичный backend;
• HTTPS;
• API infrastructure;
• интеграции;
• обычный server-side deployment.

Схема:

Telegram
↓
/api/telegram/webhook
↓
backend
↓
business logic
↓
database

Для local development getUpdates часто проще.

Не выбирать webhook только потому, что он кажется «более профессиональным».

Какую последовательность использовать для первого Telegram-бота

Последовательность:

1. Создать бота через BotFather
↓
2. Получить token
↓
3. getMe
↓
4. Написать боту в Telegram
↓
5. getUpdates
↓
6. Найти chat_id
↓
7. sendMessage
↓
8. Реализовать обработку updates
↓
9. Добавить бизнес-логику
↓
10. При необходимости перейти на webhook

Так каждая следующая стадия строится на проверенной предыдущей.

Если getMe не работает — не диагностировать webhook.

Если getUpdates не получает сообщения — рано разбираться с sendMessage.

Если прямой sendMessage работает — проблема ответа может находиться уже в обработчике или бизнес-логике.

Telegram
↓
Bot API
↓
получение Update
↓
обработчик
↓
бизнес-логика
↓
база / внешнее API
↓
sendMessage
↓
Telegram

getMe работает?
↓
Update приходит?
↓
обработчик запускается?
↓
логика выполняется?
↓
 sendMessage работает?