---
slug: "telegram-bot-api"
name: "Telegram Bot API"
vendor: "Telegram"
industry: "communications"
docsUrl: "https://core.telegram.org/bots/api"
version: 2
updatedAt: "2026-10-24"
---

# Telegram Bot API

Отрасль: Связь и уведомления. Актуально на 2026-10-24.

HTTP-интерфейс для ботов Telegram: получение обновлений (long polling или вебхук), отправка и редактирование сообщений, фото и документов, ответы на нажатия inline-кнопок, работа с файлами. Каждый метод вызывается отдельным URL с токеном бота. Актуальная версия — Bot API 10.3 (24 августа 2026).

## Сценарии

### Отправлять уведомления в чат или канал

Самый частый случай: сайт или сервис пишет в Telegram о новых заказах, ошибках, заявках.

1. Создай бота у @BotFather и получи токен. Проверь его: POST /bot{token}/getMe вернёт данные бота.
2. Узнай chat_id: напиши боту любое сообщение (или добавь бота в группу) и вызови POST /bot{token}/getUpdates — chat_id будет в message.chat.id. Для публичного канала можно передавать @username канала, бот должен быть в нём администратором.
3. Отправь сообщение: POST /bot{token}/sendMessage с chat_id и text (до 4096 символов). Для жирного текста и ссылок передай parse_mode = HTML.
4. Храни chat_id в 64-битном целом: идентификаторы групп и каналов не помещаются в 32 бита. Если пришла ошибка с retry_after — подожди столько секунд и повтори.

```bash
TOKEN='123456:ABC-DEF...'

curl -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -H 'Content-Type: application/json' \
  -d '{
        "chat_id": -1001234567890,
        "text": "<b>Новый заказ №1042</b>\nСумма: 15 000 ₽\n<a href=\"https://example.ru/admin/orders/1042\">Открыть</a>",
        "parse_mode": "HTML",
        "link_preview_options": {"is_disabled": true}
      }'
```

### Принимать сообщения через вебхук

Бот на сервере с HTTPS: Telegram сам присылает каждое сообщение пользователю на твой адрес.

1. Установи вебхук: POST /bot{token}/setWebhook с url (HTTPS, порты 443, 80, 88 или 8443) и secret_token — случайной строкой.
2. Telegram присылает на url POST-запрос с объектом Update и заголовком X-Telegram-Bot-Api-Secret-Token. Сверяй заголовок с secret_token, чтобы отбрасывать чужие запросы.
3. Отвечай 200 сразу: при другом коде Telegram повторяет запрос. Ответ пользователю отправляй отдельным вызовом POST /bot{token}/sendMessage с chat_id из update.message.chat.id.
4. Пока вебхук установлен, getUpdates не работает. Чтобы вернуться к long polling, вызови setWebhook с пустым url.

```bash
curl -X POST "https://api.telegram.org/bot$TOKEN/setWebhook" \
  -H 'Content-Type: application/json' \
  -d '{
        "url": "https://example.ru/tg/webhook",
        "secret_token": "s3cr3t_Random_42",
        "allowed_updates": ["message", "callback_query"],
        "drop_pending_updates": true
      }'
```

### Бот без своего сервера с HTTPS: long polling

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

1. Убедись, что вебхук не установлен (иначе getUpdates вернёт ошибку).
2. В цикле вызывай POST /bot{token}/getUpdates с timeout = 30 (длинный опрос: запрос ждёт новых событий до 30 секунд) и offset.
3. После каждого ответа ставь offset = update_id последнего полученного обновления + 1 — так Telegram поймёт, что предыдущие обработаны, и не пришлёт их снова.
4. На каждое сообщение отвечай через POST /bot{token}/sendMessage.

```python
import requests

API = "https://api.telegram.org/bot<токен>"
offset = 0
while True:
    r = requests.post(f"{API}/getUpdates", json={"offset": offset, "timeout": 30, "allowed_updates": ["message"]}, timeout=40).json()
    for upd in r.get("result", []):
        offset = upd["update_id"] + 1
        msg = upd.get("message")
        if msg and "text" in msg:
            requests.post(f"{API}/sendMessage", json={"chat_id": msg["chat"]["id"], "text": f"Вы написали: {msg['text']}"})
```

### Кнопки под сообщением и обработка нажатий

Inline-кнопки: «Подтвердить заказ», «Отменить», выбор варианта — без ввода текста.

1. Отправь сообщение с кнопками: POST /bot{token}/sendMessage с reply_markup = inline_keyboard. У каждой кнопки — text и callback_data (до 64 байт): по ней ты поймёшь, что нажали.
2. Нажатие приходит как update с callback_query: в нём id, data (твоя callback_data) и message, к которому была кнопка.
3. Обязательно ответь на нажатие: POST /bot{token}/answerCallbackQuery с callback_query_id — иначе у пользователя будет крутиться индикатор загрузки. В text можно показать короткое уведомление.
4. Обнови исходное сообщение: POST /bot{token}/editMessageText с chat_id, message_id и новым текстом (и новыми кнопками или без них).

```bash
# Сообщение с кнопками
curl -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -H 'Content-Type: application/json' \
  -d '{
        "chat_id": 123456789,
        "text": "Заказ №1042 на 15 000 ₽. Подтвердить?",
        "reply_markup": {"inline_keyboard": [[
          {"text": "✅ Подтвердить", "callback_data": "order:1042:ok"},
          {"text": "❌ Отменить", "callback_data": "order:1042:cancel"}
        ]]}
      }'

# После нажатия: убрать «часики» и поменять текст
curl -X POST "https://api.telegram.org/bot$TOKEN/answerCallbackQuery" \
  -H 'Content-Type: application/json' -d '{"callback_query_id": "<id>", "text": "Заказ подтверждён"}'
curl -X POST "https://api.telegram.org/bot$TOKEN/editMessageText" \
  -H 'Content-Type: application/json' -d '{"chat_id": 123456789, "message_id": 512, "text": "Заказ №1042 подтверждён ✅"}'
```

### Отправить файл и скачать файл от пользователя

Прислать счёт или отчёт документом, принять от пользователя фото или файл.

1. Отправь файл с диска: POST /bot{token}/sendDocument в формате multipart/form-data с chat_id и document. Бот может отправлять файлы до 50 МБ. Фото — POST /bot{token}/sendPhoto: можно передать HTTP-ссылку вместо загрузки.
2. Telegram вернёт file_id: повторно отправляй тот же файл по нему, без загрузки.
3. Чтобы скачать файл от пользователя, возьми file_id из сообщения (document.file_id или последний элемент photo) и вызови POST /bot{token}/getFile.
4. Скачай файл по адресу https://api.telegram.org/file/bot<токен>/<file_path> из ответа. Ссылка живёт не меньше часа, через облачный Bot API скачиваются файлы до 20 МБ.

```bash
# Отправить PDF
curl -X POST "https://api.telegram.org/bot$TOKEN/sendDocument" \
  -F chat_id=123456789 \
  -F document=@invoice-1042.pdf \
  -F caption='Счёт по заказу №1042'

# Получить путь к файлу пользователя и скачать
FILE_PATH=$(curl -s -X POST "https://api.telegram.org/bot$TOKEN/getFile" -d file_id='<file_id>' | jq -r .result.file_path)
curl -o file.bin "https://api.telegram.org/file/bot$TOKEN/$FILE_PATH"
```

## Базовые URL

- Боевой: `https://api.telegram.org`
- URL метода: `https://api.telegram.org/bot<token>/METHOD_NAME`

## Авторизация

Тип: API-ключ

Токен бота (выдаёт @BotFather) передаётся в пути запроса после `bot`.

```
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe
```

## Методы

### POST /bot{token}/getMe — Проверка токена

Параметров нет. Возвращает объект User с информацией о боте.

### POST /bot{token}/getUpdates — Получение обновлений (long polling)

Возвращает массив объектов Update. Не работает, пока установлен вебхук.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `offset` | body | integer | нет | ID первого обновления; на 1 больше последнего полученного — подтверждает предыдущие |
| `limit` | body | integer | нет | Число обновлений, 1–100, по умолчанию 100 |
| `timeout` | body | integer | нет | Таймаут long polling в секундах, по умолчанию 0 |
| `allowed_updates` | body | array | нет | Типы обновлений, например ["message", "edited_channel_post", "callback_query"] |

### POST /bot{token}/setWebhook — Установка вебхука

Telegram отправляет на URL HTTPS POST с JSON-объектом Update; при ответе не 2XX повторяет запрос.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `url` | body | string | да | HTTPS URL для обновлений; пустая строка удаляет вебхук |
| `certificate` | body | file | нет | Публичный ключ для самоподписанного сертификата |
| `ip_address` | body | string | нет | Фиксированный IP для отправки вебхуков |
| `max_connections` | body | integer | нет | Одновременных соединений, 1–100, по умолчанию 40 |
| `allowed_updates` | body | array | нет | Типы обновлений |
| `drop_pending_updates` | body | boolean | нет | Сбросить накопленные обновления |
| `secret_token` | body | string | нет | 1–256 символов A-Z, a-z, 0-9, _, -; приходит в заголовке X-Telegram-Bot-Api-Secret-Token |

### POST /bot{token}/sendMessage — Отправка текстового сообщения

Возвращает отправленный Message.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `chat_id` | body | integer/string | да | ID чата или @username канала/супергруппы |
| `text` | body | string | да | Текст, 1–4096 символов после разбора сущностей |
| `parse_mode` | body | string | нет | Режим форматирования (Markdown-стиль или HTML) |
| `entities` | body | array | нет | Сущности текста вместо parse_mode |
| `message_thread_id` | body | integer | нет | ID темы форума |
| `link_preview_options` | body | object | нет | Настройки превью ссылок |
| `disable_notification` | body | boolean | нет | Отправить без звука |
| `protect_content` | body | boolean | нет | Запретить пересылку и сохранение |
| `reply_parameters` | body | object | нет | Сообщение, на которое отвечаем |
| `reply_markup` | body | object | нет | Inline-клавиатура, обычная клавиатура, её удаление или ForceReply |
| `business_connection_id` | body | string | нет | Бизнес-подключение, от имени которого отправляем |

### POST /bot{token}/sendPhoto — Отправка фото

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `chat_id` | body | integer/string | да | ID чата или @username |
| `photo` | body | file/string | да | file_id, HTTP URL или загрузка через multipart/form-data |
| `caption` | body | string | нет | Подпись, 0–1024 символа |
| `parse_mode` | body | string | нет | Режим форматирования подписи |
| `has_spoiler` | body | boolean | нет | Скрыть фото под спойлером |
| `show_caption_above_media` | body | boolean | нет | Подпись над медиа |
| `reply_markup` | body | object | нет | Клавиатура |

### POST /bot{token}/sendDocument — Отправка файла

Боты могут отправлять файлы любого типа до 50 МБ.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `chat_id` | body | integer/string | да | ID чата или @username |
| `document` | body | file/string | да | file_id, HTTP URL или загрузка через multipart/form-data |
| `thumbnail` | body | file/string | нет | Превью в JPEG до 200 кБ |
| `caption` | body | string | нет | Подпись, 0–1024 символа |
| `parse_mode` | body | string | нет | Режим форматирования подписи |
| `disable_content_type_detection` | body | boolean | нет | Отключить определение типа файла на сервере |
| `reply_markup` | body | object | нет | Клавиатура |

### POST /bot{token}/answerCallbackQuery — Ответ на нажатие inline-кнопки

Показывает уведомление или алерт; возвращает `True`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `callback_query_id` | body | string | да | ID callback-запроса |
| `text` | body | string | нет | Текст уведомления, 0–200 символов |
| `show_alert` | body | boolean | нет | Показать алерт вместо уведомления, по умолчанию false |
| `url` | body | string | нет | URL для открытия (игра или t.me/your_bot?start=XXXX) |
| `cache_time` | body | integer | нет | Время кэширования ответа на клиенте, секунд; по умолчанию 0 |

### POST /bot{token}/editMessageText — Редактирование текста сообщения

Возвращает отредактированный Message или `True` для inline-сообщений.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `chat_id` | body | integer/string | нет | Обязателен, если нет inline_message_id |
| `message_id` | body | integer | нет | Обязателен, если нет inline_message_id |
| `inline_message_id` | body | string | нет | Обязателен, если нет chat_id и message_id |
| `text` | body | string | нет | Новый текст, 1–4096 символов; обязателен, если нет rich_message |
| `parse_mode` | body | string | нет | Режим форматирования |
| `link_preview_options` | body | object | нет | Настройки превью ссылок |
| `reply_markup` | body | object | нет | Inline-клавиатура |

### POST /bot{token}/getFile — Информация о файле для скачивания

Возвращает объект File; ссылка `https://api.telegram.org/file/bot<token>/<file_path>` действует не меньше часа. Боты могут скачивать файлы до 20 МБ.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `file_id` | body | string | да | Идентификатор файла |

### POST /bot{token}/deleteMessage — Удаление сообщения

Сообщение можно удалить, если оно отправлено меньше 48 часов назад; служебные сообщения о создании супергруппы, канала или темы удалить нельзя.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `token` | path | string | да | Токен бота |
| `chat_id` | body | integer/string | да | ID чата или @username |
| `message_id` | body | integer | да | ID сообщения |

## Нюансы

- Поддерживаются GET и POST; параметры — строкой запроса, `application/x-www-form-urlencoded`, `application/json` (кроме загрузки файлов) или `multipart/form-data` (для файлов).
- Имена методов нечувствительны к регистру; все запросы — в UTF-8 и только по HTTPS.
- Ответ — JSON с полем `ok`; при успехе результат в `result`, при ошибке — `description` и `error_code`.
- `getUpdates` и вебхук взаимоисключающие: пока вебхук установлен, `getUpdates` не работает. Порты вебхука: 443, 80, 88, 8443.
- Чтобы не получать дубли при long polling, пересчитывайте `offset` после каждого ответа.
- ID чатов могут превышать 32 бита (до 52 значимых бит) — храните их в 64-битных целых.
- `allow_paid_broadcast` снимает лимиты рассылки до 1000 сообщений в секунду за 0,1 Telegram Stars за сообщение.

## Ошибки

| Код | Описание |
|---|---|
| `retry_after` | Превышен flood control — сколько секунд ждать до повтора |
| `migrate_to_chat_id` | Группа преобразована в супергруппу с указанным ID |

## Ограничения

- Отправка файлов ботом — до 50 МБ; скачивание через `getFile` — до 20 МБ.
- Локальный Bot API Server: скачивание без ограничения размера, загрузка до 2000 МБ.
- Текст сообщения — до 4096 символов, подпись к медиа — до 1024.

## Источники

- [Telegram Bot API](https://core.telegram.org/bots/api)
- [Making requests](https://core.telegram.org/bots/api#making-requests)
- [Getting updates](https://core.telegram.org/bots/api#getting-updates)
- [ResponseParameters](https://core.telegram.org/bots/api#responseparameters)

---

Если этого недостаточно — официальная документация: https://core.telegram.org/bots/api
JSON: https://mcp-everything.ru/api/integrations/telegram-bot-api. MCP: https://mcp-everything.ru/mcp