Skip to content

Latest commit

 

History

History
952 lines (667 loc) · 23.5 KB

api.md

File metadata and controls

952 lines (667 loc) · 23.5 KB

Справочник HTTP API

Базовый URL: http://<host>:8081

173 эндпоинта — полная поддержка Bot API 9.4.

Все ответы — JSON. При ошибке: {"detail": "описание ошибки"}.

Здоровье и метрики

GET /health

Проверка работоспособности сервиса.

Ответ:

{"status": "ok", "time": "2025-01-01T12:00:00Z"}

GET /v1/metrics

Статистика сообщений по статусам.

Ответ:

{"sent": 42, "error": 1, "deleted": 5, "dry_run": 3}

Сообщения

POST /v1/messages/send

Отправка текстового сообщения.

Тело запроса:

{
  "chat_id": -100123456,
  "text": "<b>Привет!</b>",
  "template": "fleet_status",
  "variables": {"title": "Статус"},
  "parse_mode": "HTML",
  "reply_to_message_id": 101,
  "message_thread_id": 5,
  "disable_web_page_preview": true,
  "reply_markup": {
    "inline_keyboard": [[{"text": "OK", "callback_data": "ok"}]]
  },
  "request_id": "external-uuid",
  "live": false,
  "dry_run": false
}

Обязательно: chat_id + (text или template).

Поле Тип Описание
chat_id int/str ID чата
text str Текст сообщения (до 4096 символов)
template str Имя Jinja2-шаблона (вместо text)
variables object Переменные для шаблона
parse_mode str HTML / MarkdownV2
reply_to_message_id int ID сообщения для ответа
message_thread_id int ID топика (для форумов)
disable_web_page_preview bool Отключить превью ссылок
reply_markup object Inline/Reply клавиатура
request_id str Внешний ID для идемпотентности
live bool Пометка для прогресс-сообщений
dry_run bool Не отправлять в Telegram

Ответ:

{
  "message": {
    "id": 1,
    "chat_id": "-100123456",
    "telegram_message_id": 42,
    "status": "sent",
    "text": "Привет!",
    "parse_mode": "HTML",
    "created_at": "...",
    "sent_at": "..."
  },
  "result": {"message_id": 42}
}

POST /v1/messages/{id}/edit

Редактирование сообщения по внутреннему ID.

Тело:

{
  "text": "Новый текст",
  "parse_mode": "HTML",
  "reply_markup": null
}

POST /v1/messages/{id}/delete

Удаление сообщения по внутреннему ID.

GET /v1/messages/{id}

Получение сообщения по ID.

GET /v1/messages

Список сообщений.

Параметр Тип Описание
chat_id str Фильтр по чату
status str Фильтр по статусу (sent, error, deleted, dry_run)
limit int Количество (по умолчанию 50, макс. 500)
offset int Смещение

POST /v1/messages/forward

Пересылка сообщения.

{
  "chat_id": -100123456,
  "from_chat_id": -100654321,
  "message_id": 42
}

POST /v1/messages/copy

Копирование сообщения (без пометки «Переслано»).

{
  "chat_id": -100123456,
  "from_chat_id": -100654321,
  "message_id": 42,
  "caption": "Новая подпись",
  "parse_mode": "HTML"
}

Медиа

POST /v1/media/send-photo

Отправка фото по URL или file_id (JSON).

{
  "chat_id": -100123456,
  "photo": "https://example.com/image.jpg",
  "caption": "<b>Описание</b>",
  "parse_mode": "HTML",
  "reply_markup": null
}

POST /v1/media/upload-photo

Загрузка фото файлом (multipart/form-data).

Поле Тип Описание
chat_id form ID чата (обязательно)
file file Файл изображения (обязательно)
caption form Подпись
parse_mode form HTML / MarkdownV2
reply_to_message_id form ID сообщения для ответа
dry_run form true — не отправлять 
curl -X POST http://127.0.0.1:8081/v1/media/upload-photo \
  -F "chat_id=-100123456" \
  -F "caption=Описание фото" \
  -F "parse_mode=HTML" \
  -F "file=@photo.jpg"

POST /v1/media/send-document

Отправка документа по URL или file_id.

{
  "chat_id": -100123456,
  "document": "https://example.com/file.pdf",
  "caption": "Документ"
}

POST /v1/media/send-video

Отправка видео по URL или file_id.

{
  "chat_id": -100123456,
  "video": "https://example.com/video.mp4",
  "caption": "Видео"
}

Шаблоны

POST /v1/templates

Создание или обновление шаблона.

{
  "name": "report",
  "body": "<b>{{ title }}</b>\n{{ content }}",
  "parse_mode": "HTML",
  "description": "Шаблон отчёта"
}

GET /v1/templates

Список всех шаблонов.

GET /v1/templates/{name}

Получение шаблона по имени.

POST /v1/templates/{name}/render

Рендеринг шаблона с переменными (без отправки).

{"variables": {"title": "Отчёт", "content": "Содержимое"}}

Ответ:

{"text": "<b>Отчёт</b>\nСодержимое", "parse_mode": "HTML"}

POST /v1/templates/seed

Загрузка шаблонов из директории templates/.

Команды бота

POST /v1/commands

Создание или обновление набора команд.

{
  "scope_type": "chat_member",
  "chat_id": -100123456,
  "user_id": 777,
  "commands": [
    {"command": "start", "description": "Начать работу"},
    {"command": "help", "description": "Справка"}
  ]
}
scope_type Описание
default Глобальные команды
all_private_chats Все личные чаты
all_group_chats Все групповые чаты
chat Конкретный чат
chat_administrators Администраторы чата
chat_member Конкретный пользователь в конкретном чате

GET /v1/commands

Список всех наборов команд.

POST /v1/commands/sync

Синхронизация набора с Telegram (вызов setMyCommands).

{"command_set_id": 1}

Callback Queries

POST /v1/callbacks/answer

Ответ на нажатие inline-кнопки.

{
  "callback_query_id": "123456789",
  "text": "Принято!",
  "show_alert": false
}

GET /v1/callbacks

Список полученных callback queries.

Параметр Тип Описание
chat_id str Фильтр по чату
user_id str Фильтр по пользователю
answered bool Фильтр: отвечен/не отвечен
limit int Количество
offset int Смещение

GET /v1/callbacks/{id}

Получение callback query по ID.

Чаты

GET /v1/chats/{chat_id}

Информация о чате от Telegram API (getChat).

GET /v1/chats/{chat_id}/members/{user_id}

Статус участника чата (getChatMember).

GET /v1/chats/{chat_id}/members/count

Количество участников (getChatMemberCount).

POST /v1/chats/{chat_id}/pin/{message_id}

Закрепить сообщение в чате.

DELETE /v1/chats/{chat_id}/pin/{message_id}

Открепить сообщение.

GET /v1/chats/{chat_id}/stored

Данные о чате из локальной БД (из вебхуков).

GET /v1/chats/{chat_id}/stored-users

Пользователи из БД, которые писали в данном чате.

Вебхуки

POST /telegram/webhook

Приём обновлений от Telegram (webhook target).

POST /telegram/webhook/{bot_id}

Приём обновлений от Telegram с привязкой к конкретному боту.

GET /v1/updates

Список полученных обновлений.

Параметр Тип Описание
limit int Количество
offset int Смещение
update_type str Фильтр: message, callback_query, edited_message
bot_id int Фильтр по боту (мультибот)

GET /v1/updates/poll

Long polling через getUpdates.

Параметр Тип Описание
bot_id int Бот для polling (если не указан, используется default context)
offset int Явный offset. Если не указан, берётся из update_offset для bot context
limit int До 100 обновлений
timeout int Таймаут long polling (сек)
allowed_updates list[str] Фильтр типов обновлений

POST /v1/updates/ack

Подтверждение обработанного offset.

{
  "offset": 123457,
  "bot_id": 123456789
}

bot_id опционален. При отсутствии обновляется default offset context.

GET /v1/updates/offset

Текущий offset для polling context.

Параметр Тип Описание
bot_id int Вернуть offset конкретного бота. Без параметра — default context

POST /v1/webhook/set

Настройка вебхука у Telegram.

{
  "url": "https://example.com/telegram/webhook",
  "secret_token": "my-secret",
  "allowed_updates": ["message", "callback_query"]
}

DELETE /v1/webhook

Удаление вебхука.

GET /v1/webhook/info

Текущая конфигурация вебхука (getWebhookInfo).

Опросы

POST /v1/polls/send

Создание опроса или викторины.

Тело запроса:

{
  "chat_id": -100123456,
  "question": "Какой язык программирования вы предпочитаете?",
  "options": ["Python", "JavaScript", "Go", "Rust"],
  "type": "quiz",
  "correct_option_id": 0,
  "explanation": "Python — самый популярный язык для ML и data science",
  "explanation_parse_mode": "HTML",
  "is_anonymous": true,
  "allows_multiple_answers": false,
  "open_period": 300,
  "reply_markup": null
}
Поле Тип Описание
chat_id int/str ID чата (обязательно)
question str Вопрос (1-300 символов, обязательно)
options list[str] Варианты ответа (2-10 шт., обязательно)
type str regular (по умолчанию) или quiz
correct_option_id int Индекс правильного ответа (только для quiz)
explanation str Пояснение к правильному ответу (макс. 200 символов)
explanation_parse_mode str HTML / MarkdownV2 для пояснения
is_anonymous bool Анонимное голосование (по умолчанию true)
allows_multiple_answers bool Множественный выбор (только regular)
open_period int Время открытого голосования в секундах (5-600)
close_date int Unix timestamp закрытия опроса
is_closed bool Создать закрытый опрос
reply_markup object Inline-клавиатура

Ответ:

{
  "id": 1,
  "chat_id": "-100123456",
  "telegram_message_id": 42,
  "poll_id": "5312345678901234567",
  "question": "Какой язык программирования вы предпочитаете?",
  "type": "quiz",
  "is_closed": false,
  "status": "sent"
}

POST /v1/polls/{chat_id}/{message_id}/stop

Остановка опроса с показом результатов.

Параметры пути:

  • chat_id — ID чата
  • message_id — telegram_message_id опроса

Ответ:

{
  "poll_id": "5312345678901234567",
  "question": "...",
  "total_voter_count": 42,
  "is_closed": true
}

GET /v1/polls

Список опросов с фильтрацией.

Параметр Тип Описание
chat_id str Фильтр по чату
type str Фильтр по типу (regular, quiz)
is_closed bool Фильтр: закрыт/открыт
limit int Количество (по умолчанию 50, макс. 500)
offset int Смещение

GET /v1/polls/{poll_id}

Получение опроса по poll_id.

GET /v1/polls/{poll_id}/answers

Все ответы пользователей на опрос.

Ответ:

[
  {
    "id": 1,
    "poll_id": "5312345678901234567",
    "user_id": "777",
    "option_ids": [0, 2],
    "created_at": "..."
  }
]

Реакции

POST /v1/reactions/set

Установка реакции на сообщение.

Тело запроса:

{
  "chat_id": -100123456,
  "message_id": 42,
  "reaction": [
    {"type": "emoji", "emoji": "👍"},
    {"type": "emoji", "emoji": "🔥"}
  ],
  "is_big": false
}
Поле Тип Описание
chat_id int/str ID чата (обязательно)
message_id int telegram_message_id (обязательно)
reaction list[object] Список реакций (пустой = удалить все)
is_big bool Большая анимация (по умолчанию false)

Типы реакций:

// Эмодзи
{"type": "emoji", "emoji": "👍"}

// Кастомное эмодзи (Premium)
{"type": "custom_emoji", "custom_emoji_id": "5312536423851630001"}

// Платная реакция (Telegram Stars)
{"type": "paid"}

Популярные эмодзи: 👍, 👎, ❤️, 🔥, 🥰, 👏, 😁, 🤔, 🤯, 😱, 🤬, 😢, 🎉, 🤩, 🤮, 💩, 🙏, 👌, 🕊, 🤡, 🥱, 🥴, 😍, 🐳, ❤‍🔥, 🌚, 🌭, 💯, 🤣, ⚡, 🍌, 🏆, 💔, 🤨, 😐, 🍓, 🍾, 💋, 🖕, 😈, 😴, 😭, 🤓, 👻, 👨‍💻, 👀, 🎃, 🙈, 😇, 😨, 🤝, ✍, 🤗, 🫡, 🎅, 🎄, ☃, 💅, 🤪, 🗿, 🆒, 💘, 🙉, 🦄, 😘, 💊, 🙊, 😎, 👾, 🤷‍♂️, 🤷, 🤷‍♀️, 😡

Ответ:

{
  "success": true
}

GET /v1/reactions

Список реакций с фильтрацией.

Параметр Тип Описание
chat_id str Фильтр по чату
user_id str Фильтр по пользователю
reaction_type str Фильтр по типу (emoji, custom_emoji, paid)
limit int Количество
offset int Смещение

GET /v1/reactions/{chat_id}/{message_id}

Все реакции на конкретное сообщение.

Ответ:

[
  {
    "id": 1,
    "chat_id": "-100123456",
    "telegram_message_id": 42,
    "user_id": "777",
    "reaction_type": "emoji",
    "emoji": "👍",
    "created_at": "..."
  }
]

Бот

GET /v1/bot/me

Информация о боте (getMe): имя, username, поддерживаемые фичи.

Web-UI (proxy к tgweb)

POST /v1/web/pages

Создание веб-страницы.

{
  "title": "Мой опрос",
  "page_type": "survey",
  "slug": "my-survey",
  "config": {
    "fields": [
      {"name": "rating", "type": "select", "label": "Оценка", "options": ["1", "2", "3", "4", "5"]}
    ]
  },
  "bot_id": 123456789,
  "event_id": null
}
Поле Тип Описание
title str Заголовок страницы (обязательно)
page_type str page, survey, prediction (по умолчанию page)
slug str URL-slug (генерируется автоматически если не указан)
config object Конфигурация страницы (поля формы, контент и т.д.)
template str Имя шаблона для рендеринга
bot_id int ID бота
event_id int ID события предсказаний (для type=prediction)

GET /v1/web/pages

Список страниц.

Параметр Тип Описание
page_type str Фильтр по типу
is_active bool Фильтр: активные/неактивные
limit int Количество (по умолчанию 50)
offset int Смещение

GET /v1/web/pages/{slug}

Конфигурация страницы по slug.

DELETE /v1/web/pages/{slug}

Удаление страницы.

POST /v1/web/pages/{slug}/links

Создание индивидуальной ссылки.

{
  "user_id": 777,
  "chat_id": -100123456,
  "metadata": {"source": "private_message"},
  "expires_at": "2026-03-01T00:00:00Z"
}

Ответ:

{
  "token": "a1b2c3d4e5f6...",
  "url": "https://tg.example.com:8090/l/a1b2c3d4e5f6..."
}

GET /v1/web/pages/{slug}/submissions

Ответы на форму страницы.

Параметр Тип Описание
limit int Количество
offset int Смещение

Боты (Bot API 9.4)

GET /v1/bots

Список зарегистрированных ботов.

POST /v1/bots

Регистрация нового бота по токену.

{"token": "123456:ABC-DEF", "is_default": true}

GET /v1/bots/default

Бот по умолчанию.

PUT /v1/bots/{bot_id}/default

Установить бота по умолчанию.

DELETE /v1/bots/{bot_id}

Деактивировать бота.

POST /v1/bots/profile-photo

Установить фото профиля бота (Bot API 9.4).

{"photo": {"type": "static", "sticker": "..."}, "is_public": true, "bot_id": null}

DELETE /v1/bots/profile-photo

Удалить фото профиля бота.

GET /v1/bots/users/{user_id}/profile-audios

Получить аудио профиля пользователя (Bot API 9.4).

Параметр Тип Описание
bot_id int Бот (опционально)
offset int Смещение
limit int Количество

POST /v1/bots/star-subscription/edit

Редактировать Star-подписку пользователя (Bot API 8.0).

{"user_id": 777, "telegram_payment_charge_id": "...", "is_canceled": true}

Форум-топики (Bot API 9.3)

POST /v1/forums/topics

Создать топик в форум-группе.

{"chat_id": -100123456, "name": "Обсуждение", "icon_color": 7322096, "icon_custom_emoji_id": "..."}

PUT /v1/forums/topics/{topic_id}

Редактировать имя/иконку топика.

POST /v1/forums/topics/{topic_id}/close

Закрыть топик.

POST /v1/forums/topics/{topic_id}/reopen

Повторно открыть топик.

DELETE /v1/forums/topics/{topic_id}

Удалить топик.

POST /v1/forums/general/hide

Скрыть General-топик.

POST /v1/forums/general/unhide

Показать General-топик.

Истории (Bot API 9.0–9.3)

POST /v1/stories/post

Опубликовать историю в канал.

{"chat_id": -100123456, "content": {"type": "photo", "photo": "..."}, "caption": "..."}

PUT /v1/stories/{story_id}

Редактировать опубликованную историю.

DELETE /v1/stories/{story_id}

Удалить историю.

POST /v1/stories/repost

Репост истории из одного канала в другой (Bot API 9.3).

{"chat_id": -100123456, "from_chat_id": -100654321, "story_id": 42}

Предложенные посты (Bot API 9.2)

POST /v1/suggested-posts/approve

Одобрить предложенный пост в бизнес-канале.

{"business_connection_id": "abc123", "message_id": 42, "is_scheduled": false}

POST /v1/suggested-posts/decline

Отклонить предложенный пост.

{"business_connection_id": "abc123", "message_id": 42}

Чек-листы (Bot API 9.1)

POST /v1/checklists/send

Отправить интерактивный чек-лист (до 30 задач).

{
  "chat_id": -100123456,
  "title": "Задачи на сегодня",
  "tasks": [
    {"id": 1, "text": "Первая задача"},
    {"id": 2, "text": "Вторая задача", "checked": true}
  ]
}

PUT /v1/messages/{id}/checklist

Редактировать существующий чек-лист.

Звёзды и подарки (Bot API 9.1–9.3)

GET /v1/stars/balance

Баланс звёзд бота (Bot API 9.1).

POST /v1/stars/invoice

Создать счёт на оплату Stars.

POST /v1/stars/refund

Возврат Stars платежа.

GET /v1/stars/transactions

История транзакций Stars.

POST /v1/gifts/premium

Подарить премиум-подписку за звёзды (Bot API 9.3).

{"user_id": 777, "month_count": 3, "star_count": 1000}

GET /v1/gifts/user/{user_id}

Подарки пользователя (Bot API 9.3).

GET /v1/gifts/chat/{chat_id}

Подарки чата (Bot API 9.3).

Черновики (Bot API 9.3)

POST /v1/messages/draft

Отправить черновик сообщения (для стриминга LLM).

{
  "business_connection_id": "abc123",
  "chat_id": 123456789,
  "text": "Текст черновика",
  "parse_mode": "HTML"
}

Cross-cutting параметры (Bot API 9.2)

Следующие параметры добавлены во все send-методы (messages, media, checklists):

Параметр Тип Описание
direct_messages_topic_id int Маршрутизация в топик через Direct Messages
suggested_post_parameters object Параметры для предложенных постов

Коды ошибок

Код Описание
400 Неверный запрос (валидация)
404 Ресурс не найден
409 Конфликт (напр., нет telegram_message_id для edit)
502 Ошибка Telegram Bot API
500 Внутренняя ошибка сервера