{ "name": "Xiro Bot API", "version": "1.0.0", "description": "HTTP Bot API шлюз Xirogram (telesrv). Совместим с Telegram Bot API: тот же формат токена, те же объекты ответов.", "base_url": "https://xiroapi.duckdns.org", "method_endpoint": "https://xiroapi.duckdns.org/bot/", "file_endpoint": "https://xiroapi.duckdns.org/file/bot/", "auth": { "type": "path-token", "format": ":", "header": null, "notes": "Токен передаётся в пути URL и является единственным credential." }, "transport": [ "json", "multipart/form-data", "application/x-www-form-urlencoded" ], "max_upload_bytes": 26214400, "method_count": 47, "groups": [ { "id": "bot", "title": "Бот и команды", "badge": "Бот" }, { "id": "updates", "title": "Обновления", "badge": "Updates" }, { "id": "send", "title": "Отправка текста", "badge": "Send" }, { "id": "media", "title": "Медиа", "badge": "Media" }, { "id": "geo", "title": "Гео и контакты", "badge": "Geo" }, { "id": "edit", "title": "Правка и действия", "badge": "Edit" }, { "id": "ephemeral", "title": "Ephemeral-сообщения", "badge": "Ephemeral" }, { "id": "callback", "title": "Callback", "badge": "Callback" }, { "id": "files", "title": "Файлы", "badge": "Files" }, { "id": "webhooks", "title": "Webhooks", "badge": "Webhook" }, { "id": "menu", "title": "Меню и статус", "badge": "Menu" }, { "id": "webapps", "title": "Web Apps и inline", "badge": "WebApp" }, { "id": "payments", "title": "Платежи и Stars", "badge": "Stars" } ], "methods": [ { "name": "getMe", "anchor": "getMe", "group": "bot", "http_method": "POST", "path": "/bot/getMe", "description": "Возвращает объект User самого бота. Проверка токена и базовый self-test.", "parameters": [], "returns": "User", "notes": [], "status": "implemented", "verified": "200 OK" }, { "name": "setMyCommands", "anchor": "setMyCommands", "group": "bot", "http_method": "POST", "path": "/bot/setMyCommands", "description": "Сохраняет список команд бота. Максимум 100 записей.", "parameters": [ { "name": "commands", "type": "array", "required": true, "extension": false, "description": "JSON-массив {command, description, is_ephemeral}, до 100 элементов." }, { "name": "scope", "type": "object", "required": false, "extension": false, "description": "Принимается только {\"type\":\"default\"}." }, { "name": "language_code", "type": "string", "required": false, "extension": false, "description": "Должно быть пустым — локализованные scope не поддерживаются." } ], "returns": "true", "notes": [ "is_ephemeral: true помечает команду как ephemeral: её вызов в группе создаёт сообщение, видимое только вызвавшему. Бот должен ответить в пределах 15-секундного окна." ], "status": "implemented", "verified": "200 OK" }, { "name": "deleteMyCommands", "anchor": "deleteMyCommands", "group": "bot", "http_method": "POST", "path": "/bot/deleteMyCommands", "description": "Очищает сохранённый список команд. Те же правила по scope, что и у setMyCommands.", "parameters": [ { "name": "scope", "type": "object", "required": false, "extension": false, "description": "Только {\"type\":\"default\"}." } ], "returns": "true", "notes": [], "status": "implemented", "verified": null }, { "name": "getMyCommands", "anchor": "getMyCommands", "group": "bot", "http_method": "POST", "path": "/bot/getMyCommands", "description": "Возвращает сохранённый массив команд. Поле is_ephemeral присутствует только у помеченных команд.", "parameters": [ { "name": "scope", "type": "object", "required": false, "extension": false, "description": "Только {\"type\":\"default\"}." } ], "returns": "Array<BotCommand>", "notes": [], "status": "implemented", "verified": "200 OK" }, { "name": "getUpdates", "anchor": "getUpdates", "group": "updates", "http_method": "POST", "path": "/bot/getUpdates", "description": "Long-polling выборка обновлений. Пока активен опрос, setWebhook вернёт 409 CONFLICT.", "parameters": [ { "name": "offset", "type": "int", "required": false, "extension": false, "description": "Идентификатор первого возвращаемого обновления. Значение меньше -10000 — OFFSET_INVALID. Подтверждает предыдущие." }, { "name": "limit", "type": "int", "required": false, "extension": false, "description": "1..100, по умолчанию 100." }, { "name": "timeout", "type": "int", "required": false, "extension": false, "description": "Секунды long-poll, ограничивается диапазоном 0..50." }, { "name": "allowed_updates", "type": "array", "required": false, "extension": false, "description": "До 100 строк: message, edited_message, callback_query." } ], "returns": "Array<Update>", "notes": [ "Шлюз порождает только три типа обновлений: message, edited_message, callback_query. Неизвестные имена в allowed_updates не ошибка, но и ни с чем не совпадают.", "Ephemeral-сообщения приходят обычным message-обновлением, но их message_id живёт в отдельном пространстве." ], "status": "implemented", "verified": "200 OK" }, { "name": "sendMessage", "anchor": "sendMessage", "group": "send", "http_method": "POST", "path": "/bot/sendMessage", "description": "Отправляет текстовое сообщение. С receiver_user_id уходит как ephemeral.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль; отрицательный для групп и каналов." }, { "name": "text", "type": "string", "required": true, "extension": false, "description": "До 4096 символов после разбора разметки." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "HTML, Markdown, MarkdownV2 или пусто." }, { "name": "entities", "type": "array", "required": false, "extension": false, "description": "Используется при отсутствии parse_mode, иначе игнорируется." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Один из четырёх конструкторов: inline_keyboard, keyboard, remove_keyboard, force_reply." }, { "name": "disable_web_page_preview", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "Обычный ответ на сообщение." }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Расширение telesrv: переключает вызов в ephemeral-отправку (получатель видит «видно только вам»). Взаимоисключим с reply_to_message_id." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-отправка, привязанная к callback query: получатель берётся из query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "{message_id} для обычного ответа, {ephemeral_message_id} — для ephemeral." } ], "returns": "Message", "notes": [ "Обычная и ephemeral-адресация взаимоисключающие: при receiver_user_id поле reply_to_message_id должно быть пустым.", "Для ephemeral-отправки допустимы только inline-клавиатуры, иначе BUTTON_TYPE_INVALID." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendRichMessage", "anchor": "sendRichMessage", "group": "send", "http_method": "POST", "path": "/bot/sendRichMessage", "description": "Расширение telesrv: rich-текст Layer 228. Таблицы, заголовки, разделители, блоки details и footer доходят до клиента настоящими rich-блоками.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "rich_message", "type": "object", "required": true, "extension": false, "description": "{\"html\":\"...\"} или {\"markdown\":\"...\"}, плюс необязательные is_rtl и skip_entity_detection." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline-клавиатуры." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "{message_id}; устаревшее reply_to_message_id тоже принимается, но не оба сразу." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "protect_content", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "message_effect_id", "type": "int", "required": false, "extension": false, "description": "Id эффекта сообщения." } ], "returns": "Message", "notes": [ "Ровно одно из html / markdown должно быть непустым — иначе RICH_MESSAGE_INVALID.", "blocks и media разбираются, но отклоняются: RICH_MESSAGE_BLOCKS_UNSUPPORTED, RICH_MESSAGE_MEDIA_UNSUPPORTED.", "Исходник ограничен 256 KiB. Rich HTML с удалённым медиа (img, video, audio, tg-map) падает с WEBPAGE_MEDIA_EMPTY.", "Поддерживаемые элементы: b, i, u, s, tg-spoiler, a, code, pre, blockquote, tg-emoji, tg-time, footer, table." ], "status": "implemented", "verified": null }, { "name": "sendPhoto", "anchor": "sendPhoto", "group": "media", "http_method": "POST", "path": "/bot/sendPhoto", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. Принимает загрузку, attach://, HTTP(S)-URL или file_id.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "photo", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendAnimation", "anchor": "sendAnimation", "group": "media", "http_method": "POST", "path": "/bot/sendAnimation", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. GIF или беззвучное MP4.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "animation", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendAudio", "anchor": "sendAudio", "group": "media", "http_method": "POST", "path": "/bot/sendAudio", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. Плюс title, performer, duration.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "audio", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendDocument", "anchor": "sendDocument", "group": "media", "http_method": "POST", "path": "/bot/sendDocument", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. Любой файл до 25 MiB.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "document", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendSticker", "anchor": "sendSticker", "group": "media", "http_method": "POST", "path": "/bot/sendSticker", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. Плюс emoji.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "sticker", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendVideo", "anchor": "sendVideo", "group": "media", "http_method": "POST", "path": "/bot/sendVideo", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. Плюс width, height, duration.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "video", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendVideoNote", "anchor": "sendVideoNote", "group": "media", "http_method": "POST", "path": "/bot/sendVideoNote", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. Круглое видео.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "video_note", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendVoice", "anchor": "sendVoice", "group": "media", "http_method": "POST", "path": "/bot/sendVoice", "description": "Отправляет медиа в чат. Общий обработчик всех медиа-методов. Голосовое сообщение.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "voice", "type": "file", "required": true, "extension": false, "description": "Файл: multipart-часть, attach://<field>, HTTP(S)-URL или ранее выданный file_id." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "Используется без parse_mode." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Все четыре конструктора." }, { "name": "disable_notification", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "reply_to_message_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [ "Приоритет файлового поля: attach://<field> → multipart-часть → URL http(s):// → file_id. Всё остальное — FILE_ID_INVALID.", "width, height, duration, title, performer принимаются как подсказки метаданных." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendLivePhoto", "anchor": "sendLivePhoto", "group": "media", "http_method": "POST", "path": "/bot/sendLivePhoto", "description": "Live Photo: кадр + видеочасть одним сообщением.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "photo", "type": "file", "required": true, "extension": false, "description": "Кадр: загрузка, attach:// или file_id." }, { "name": "live_photo", "type": "file", "required": true, "extension": false, "description": "Видеочасть. HTTP-URL запрещён — FILE_ID_INVALID, как в официальном ограничении." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "" }, { "name": "receiver_user_id", "type": "int", "required": false, "extension": true, "description": "Ephemeral-получатель." }, { "name": "callback_query_id", "type": "string", "required": false, "extension": true, "description": "Ephemeral-якорь на callback query." }, { "name": "reply_parameters", "type": "object", "required": false, "extension": false, "description": "Как в sendMessage." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Верхнее сообщение ephemeral-треда." } ], "returns": "Message", "notes": [], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendContact", "anchor": "sendContact", "group": "geo", "http_method": "POST", "path": "/bot/sendContact", "description": "Отправляет контакт. Только ephemeral: без receiver_user_id возвращает EPHEMERAL_TARGET_REQUIRED.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "phone_number", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "first_name", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "last_name", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "vcard", "type": "string", "required": false, "extension": false, "description": "До 2048 байт." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Обязателен: эти три метода существуют только в ephemeral-виде." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline-клавиатуры." } ], "returns": "Message", "notes": [], "status": "implemented", "verified": "400 EPHEMERAL_TARGET_REQUIRED" }, { "name": "sendLocation", "anchor": "sendLocation", "group": "geo", "http_method": "POST", "path": "/bot/sendLocation", "description": "Отправляет точку на карте. Только ephemeral.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "latitude", "type": "float", "required": true, "extension": false, "description": "−90..90." }, { "name": "longitude", "type": "float", "required": true, "extension": false, "description": "−180..180." }, { "name": "horizontal_accuracy", "type": "float", "required": false, "extension": false, "description": "0..1500, по умолчанию 0." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Обязателен: эти три метода существуют только в ephemeral-виде." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline-клавиатуры." } ], "returns": "Message", "notes": [ "Ненулевой live_period отклоняется с MEDIA_INVALID — live-локация не реализована." ], "status": "implemented", "verified": "400 EPHEMERAL_TARGET_REQUIRED" }, { "name": "sendVenue", "anchor": "sendVenue", "group": "geo", "http_method": "POST", "path": "/bot/sendVenue", "description": "Отправляет место с названием и адресом. Только ephemeral.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Не ноль." }, { "name": "latitude", "type": "float", "required": true, "extension": false, "description": "−90..90." }, { "name": "longitude", "type": "float", "required": true, "extension": false, "description": "−180..180." }, { "name": "title", "type": "string", "required": true, "extension": false, "description": "Название места." }, { "name": "address", "type": "string", "required": true, "extension": false, "description": "Адрес." }, { "name": "foursquare_id", "type": "string", "required": false, "extension": false, "description": "Вместе с foursquare_type." }, { "name": "google_place_id", "type": "string", "required": false, "extension": false, "description": "Вместе с google_place_type." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Обязателен: эти три метода существуют только в ephemeral-виде." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline-клавиатуры." } ], "returns": "Message", "notes": [], "status": "implemented", "verified": "400 EPHEMERAL_TARGET_REQUIRED" }, { "name": "editMessageText", "anchor": "editMessageText", "group": "edit", "http_method": "POST", "path": "/bot/editMessageText", "description": "Правит текст сообщения — обычный, rich и inline. Единый метод для всех трёх случаев.", "parameters": [ { "name": "chat_id + message_id", "type": "int", "required": false, "extension": false, "description": "Первый способ адресации." }, { "name": "inline_message_id", "type": "string", "required": false, "extension": false, "description": "Второй способ; не смешивать с первым — MESSAGE_IDENTIFIER_INVALID." }, { "name": "text", "type": "string", "required": false, "extension": false, "description": "Одна форма содержимого." }, { "name": "rich_message", "type": "object", "required": false, "extension": false, "description": "Другая форма содержимого; не смешивать с text. Отдельного editMessageRichMessage нет." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "entities", "type": "array", "required": false, "extension": false, "description": "" }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline. Наличие пустого значения снимает клавиатуру." }, { "name": "disable_web_page_preview", "type": "bool", "required": false, "extension": false, "description": "" } ], "returns": "Message | true", "notes": [ "Для inline_message_id результат — булево, для сообщения чата — обновлённый Message.", "Правка, ничего не меняющая, даёт MESSAGE_NOT_MODIFIED." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "editMessageCaption", "anchor": "editMessageCaption", "group": "edit", "http_method": "POST", "path": "/bot/editMessageCaption", "description": "Правит подпись медиа-сообщения.", "parameters": [ { "name": "chat_id + message_id", "type": "int", "required": true, "extension": false, "description": "Обязательно; inline_message_id пока не поддерживается (INLINE_MESSAGE_ID_UNSUPPORTED)." }, { "name": "caption", "type": "string", "required": false, "extension": false, "description": "До 1024 символов; отсутствие или пустая строка убирает подпись." }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "" }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Отсутствие сохраняет клавиатуру, пустое значение снимает." } ], "returns": "Message", "notes": [ "Подпись есть только у фото/видео/анимации/аудио/голосового/документа. Для текста — MESSAGE_HAS_NO_CAPTION." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "editMessageReplyMarkup", "anchor": "editMessageReplyMarkup", "group": "edit", "http_method": "POST", "path": "/bot/editMessageReplyMarkup", "description": "Меняет только клавиатуру сообщения.", "parameters": [ { "name": "chat_id + message_id", "type": "int", "required": true, "extension": false, "description": "Без inline_message_id." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Отсутствие убирает клавиатуру." } ], "returns": "Message", "notes": [ "Методов editMessageMedia, editMessageLiveLocation и stopMessageLiveLocation нет." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "sendChatAction", "anchor": "sendChatAction", "group": "edit", "http_method": "POST", "path": "/bot/sendChatAction", "description": "Показывает статус «печатает…» / «загружает…». Ничего не сохраняется.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Личный чат или канал/супергруппа, где бот состоит." }, { "name": "action", "type": "string", "required": true, "extension": false, "description": "typing, upload_photo, record_video, upload_video, record_voice, upload_voice, upload_document, choose_sticker, find_location, record_video_note, upload_video_note." }, { "name": "message_thread_id", "type": "int", "required": false, "extension": false, "description": "Тема форума." } ], "returns": "true", "notes": [ "business_connection_id не поддерживается." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "deleteMessage", "anchor": "deleteMessage", "group": "edit", "http_method": "POST", "path": "/bot/deleteMessage", "description": "Удаляет сообщение.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "" }, { "name": "message_id", "type": "int", "required": true, "extension": false, "description": "> 0." } ], "returns": "true | false", "notes": [ "Удаление уже удалённого или чужого сообщения возвращает false либо ошибку." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "editEphemeralMessageText", "anchor": "editEphemeralMessageText", "group": "ephemeral", "http_method": "POST", "path": "/bot/editEphemeralMessageText", "description": "Правит текст ephemeral-сообщения.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Чат, в котором живёт ephemeral-сообщение." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Получатель, который видит сообщение." }, { "name": "ephemeral_message_id", "type": "int", "required": true, "extension": false, "description": "Id из ephemeral-пространства (не обычный message_id)." }, { "name": "text", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "entities", "type": "array", "required": false, "extension": false, "description": "" }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline; переданный пустой снимает клавиатуру." } ], "returns": "Message", "notes": [], "status": "implemented", "verified": "400 EPHEMERAL_MESSAGE_ID_INVALID" }, { "name": "editEphemeralMessageMedia", "anchor": "editEphemeralMessageMedia", "group": "ephemeral", "http_method": "POST", "path": "/bot/editEphemeralMessageMedia", "description": "Заменяет медиа ephemeral-сообщения.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Чат, в котором живёт ephemeral-сообщение." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Получатель, который видит сообщение." }, { "name": "ephemeral_message_id", "type": "int", "required": true, "extension": false, "description": "Id из ephemeral-пространства (не обычный message_id)." }, { "name": "media", "type": "object", "required": true, "extension": false, "description": "type (photo, animation, audio, document, video, live_photo), файловое поле, caption, parse_mode, caption_entities, width, height, duration, title, performer." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline." } ], "returns": "Message", "notes": [ "Сырая загрузка не допускается — только file_id, ссылка на файл без attach:// или HTTPS-URL." ], "status": "implemented", "verified": "400 EPHEMERAL_MESSAGE_ID_INVALID" }, { "name": "editEphemeralMessageCaption", "anchor": "editEphemeralMessageCaption", "group": "ephemeral", "http_method": "POST", "path": "/bot/editEphemeralMessageCaption", "description": "Правит подпись ephemeral-медиа.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Чат, в котором живёт ephemeral-сообщение." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Получатель, который видит сообщение." }, { "name": "ephemeral_message_id", "type": "int", "required": true, "extension": false, "description": "Id из ephemeral-пространства (не обычный message_id)." }, { "name": "caption", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "parse_mode", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "caption_entities", "type": "array", "required": false, "extension": false, "description": "" }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "" } ], "returns": "Message", "notes": [], "status": "implemented", "verified": "400 EPHEMERAL_MESSAGE_ID_INVALID" }, { "name": "editEphemeralMessageReplyMarkup", "anchor": "editEphemeralMessageReplyMarkup", "group": "ephemeral", "http_method": "POST", "path": "/bot/editEphemeralMessageReplyMarkup", "description": "Меняет клавиатуру ephemeral-сообщения.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Чат, в котором живёт ephemeral-сообщение." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Получатель, который видит сообщение." }, { "name": "ephemeral_message_id", "type": "int", "required": true, "extension": false, "description": "Id из ephemeral-пространства (не обычный message_id)." }, { "name": "reply_markup", "type": "object", "required": false, "extension": false, "description": "Только inline." } ], "returns": "Message", "notes": [], "status": "implemented", "verified": "400 EPHEMERAL_MESSAGE_ID_INVALID" }, { "name": "deleteEphemeralMessage", "anchor": "deleteEphemeralMessage", "group": "ephemeral", "http_method": "POST", "path": "/bot/deleteEphemeralMessage", "description": "Удаляет ephemeral-сообщение у получателя.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "Чат, в котором живёт ephemeral-сообщение." }, { "name": "receiver_user_id", "type": "int", "required": true, "extension": false, "description": "Получатель, который видит сообщение." }, { "name": "ephemeral_message_id", "type": "int", "required": true, "extension": false, "description": "Id из ephemeral-пространства (не обычный message_id)." } ], "returns": "true", "notes": [], "status": "implemented", "verified": "400 EPHEMERAL_MESSAGE_ID_INVALID" }, { "name": "answerCallbackQuery", "anchor": "answerCallbackQuery", "group": "callback", "http_method": "POST", "path": "/bot/answerCallbackQuery", "description": "Отвечает на нажатие inline-кнопки: тост или модальное окно.", "parameters": [ { "name": "callback_query_id", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "text", "type": "string", "required": false, "extension": false, "description": "Текст уведомления." }, { "name": "url", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "show_alert", "type": "bool", "required": false, "extension": false, "description": "Модальное окно вместо тоста." }, { "name": "cache_time", "type": "int", "required": false, "extension": false, "description": "Секунды." } ], "returns": "true", "notes": [], "status": "implemented", "verified": "400 QUERY_ID_INVALID" }, { "name": "getFile", "anchor": "getFile", "group": "files", "http_method": "POST", "path": "/bot/getFile", "description": "Возвращает метаданные файла и путь для скачивания.", "parameters": [ { "name": "file_id", "type": "string", "required": true, "extension": false, "description": "Должен быть выдан этим же сервером." } ], "returns": "File", "notes": [ "В результате всегда file_unique_id == file_id и file_path == file_id, поэтому URL скачивания — /file/bot<TOKEN>/<file_id>.", "offset игнорируется, файл отдаётся целиком." ], "status": "implemented", "verified": "400 FILE_ID_INVALID" }, { "name": "GET /file/{path}", "anchor": "file-route", "group": "files", "http_method": "GET", "path": "/file/bot/", "description": "Скачивание файла потоком, чанк за чанком, с сохранённым MIME-типом и Content-Length.", "parameters": [ { "name": "token", "type": "path", "required": true, "extension": false, "description": "Тот же <bot_id>:<secret>." }, { "name": "file_path", "type": "path", "required": true, "extension": false, "description": "Равен file_id." } ], "returns": "binary stream", "notes": [ "Путь с лишними сегментами даёт 404 FILE_NOT_FOUND." ], "status": "implemented", "verified": "400 FILE_ID_INVALID" }, { "name": "setWebhook", "anchor": "setWebhook", "group": "webhooks", "http_method": "POST", "path": "/bot/setWebhook", "description": "Регистрирует HTTPS-эндпоинт доставки обновлений. Пустой url удаляет webhook.", "parameters": [ { "name": "url", "type": "string", "required": true, "extension": false, "description": "Абсолютный http(s)-URL, до 2048 символов, без userinfo и fragment." }, { "name": "secret_token", "type": "string", "required": false, "extension": false, "description": "[A-Za-z0-9_-], до 256 символов. Уходит в заголовке X-Telegram-Bot-Api-Secret-Token." }, { "name": "max_connections", "type": "int", "required": false, "extension": false, "description": "1..100, по умолчанию 40." }, { "name": "allowed_updates", "type": "array", "required": false, "extension": false, "description": "До 100 строк." }, { "name": "drop_pending_updates", "type": "bool", "required": false, "extension": false, "description": "" } ], "returns": "true", "notes": [ "certificate отклоняется с CERTIFICATE_PINNING_UNSUPPORTED: нужен публично доверенный сертификат. ip_address — IP_ADDRESS_UNSUPPORTED.", "Установка во время long-polling getUpdates возвращает 409 CONFLICT.", "Доставка: один POST на обновление, тело — объект Update, успех — любой 2xx, редиректы не следуются, ретраи экспоненциально от 1s до 5 мин." ], "status": "implemented", "verified": "400 WEBHOOK_URL_INVALID" }, { "name": "deleteWebhook", "anchor": "deleteWebhook", "group": "webhooks", "http_method": "POST", "path": "/bot/deleteWebhook", "description": "Снимает webhook, опционально отбрасывая накопленные обновления.", "parameters": [ { "name": "drop_pending_updates", "type": "bool", "required": false, "extension": false, "description": "" } ], "returns": "true", "notes": [ "Как и setWebhook, ждёт завершения текущей доставки до 20 секунд." ], "status": "implemented", "verified": null }, { "name": "getWebhookInfo", "anchor": "getWebhookInfo", "group": "webhooks", "http_method": "POST", "path": "/bot/getWebhookInfo", "description": "Текущее состояние webhook: URL, очередь, последняя ошибка доставки.", "parameters": [], "returns": "WebhookInfo", "notes": [], "status": "implemented", "verified": "200 OK" }, { "name": "setChatMenuButton", "anchor": "setChatMenuButton", "group": "menu", "http_method": "POST", "path": "/bot/setChatMenuButton", "description": "Настраивает кнопку меню бота в чате.", "parameters": [ { "name": "chat_id", "type": "int", "required": false, "extension": false, "description": "Необязателен: без него меняется глобальная кнопка." }, { "name": "menu_button", "type": "object", "required": true, "extension": false, "description": "{\"type\":\"default\"}, {\"type\":\"commands\"} или {\"type\":\"web_app\",\"text\":\"...\",\"web_app\":{\"url\":\"...\"}}." } ], "returns": "true", "notes": [ "Принимается и «плоское» тело с type на верхнем уровне — для старых сериализаторов библиотек." ], "status": "implemented", "verified": "400 BUTTON_INVALID" }, { "name": "getChatMenuButton", "anchor": "getChatMenuButton", "group": "menu", "http_method": "POST", "path": "/bot/getChatMenuButton", "description": "Возвращает текущую кнопку меню. Никогда не null: незаданная читается как {\"type\":\"default\"}.", "parameters": [ { "name": "chat_id", "type": "int", "required": false, "extension": false, "description": "Необязателен." } ], "returns": "MenuButton", "notes": [], "status": "implemented", "verified": "200 OK" }, { "name": "setUserEmojiStatus", "anchor": "setUserEmojiStatus", "group": "menu", "http_method": "POST", "path": "/bot/setUserEmojiStatus", "description": "Меняет emoji-статус пользователя.", "parameters": [ { "name": "user_id", "type": "int", "required": true, "extension": false, "description": "" }, { "name": "emoji_status_custom_emoji_id", "type": "int", "required": false, "extension": false, "description": "" }, { "name": "emoji_status_expiration_date", "type": "int", "required": false, "extension": false, "description": "Unix-время окончания." } ], "returns": "true", "notes": [ "Нужно разрешение пользователя, иначе 403 USER_PERMISSION_DENIED.", "Нужен Premium у пользователя, иначе PREMIUM_ACCOUNT_REQUIRED." ], "status": "implemented", "verified": "400 USER_ID_INVALID" }, { "name": "answerWebAppQuery", "anchor": "answerWebAppQuery", "group": "webapps", "http_method": "POST", "path": "/bot/answerWebAppQuery", "description": "Отвечает на запрос Mini App. Поддерживается только InlineQueryResult типа article.", "parameters": [ { "name": "web_app_query_id", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "result", "type": "object", "required": true, "extension": false, "description": "id (до 64 символов), title, description, url (только HTTPS), input_message_content / сокращение message_text, reply_markup (только inline)." } ], "returns": "SentWebAppMessage", "notes": [ "Другие типы результатов — RESULT_TYPE_INVALID. В ответе будет inline_message_id, если он порождён." ], "status": "implemented", "verified": "400 RESULT_ID_INVALID" }, { "name": "savePreparedInlineMessage", "anchor": "savePreparedInlineMessage", "group": "webapps", "http_method": "POST", "path": "/bot/savePreparedInlineMessage", "description": "Сохраняет подготовленное inline-сообщение для последующей отправки.", "parameters": [ { "name": "user_id", "type": "int", "required": true, "extension": false, "description": "Кто сможет отправить." }, { "name": "result", "type": "object", "required": true, "extension": false, "description": "То же ограничение на article." }, { "name": "allow_user_chats", "type": "bool", "required": false, "extension": false, "description": "Фильтр пиров." }, { "name": "allow_bot_chats", "type": "bool", "required": false, "extension": false, "description": "Фильтр пиров." }, { "name": "allow_group_chats", "type": "bool", "required": false, "extension": false, "description": "Фильтр пиров." }, { "name": "allow_channel_chats", "type": "bool", "required": false, "extension": false, "description": "Фильтр пиров." } ], "returns": "{id, expiration_date}", "notes": [], "status": "implemented", "verified": "400 USER_ID_INVALID" }, { "name": "sendInvoice", "anchor": "sendInvoice", "group": "payments", "http_method": "POST", "path": "/bot/sendInvoice", "description": "Отправляет счёт в Stars. Принимается только currency = XTR.", "parameters": [ { "name": "chat_id", "type": "int", "required": true, "extension": false, "description": "" }, { "name": "title", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "description", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "payload", "type": "string", "required": true, "extension": false, "description": "Внутренний payload бота." }, { "name": "price", "type": "int", "required": true, "extension": false, "description": "Цена в Stars. Альтернатива — prices из одной записи." }, { "name": "currency", "type": "string", "required": false, "extension": false, "description": "XTR или пусто (по умолчанию XTR). Иная валюта — CURRENCY_INVALID." } ], "returns": "Message", "notes": [ "Фиатные счета не моделируются: XTR — единственная валюта, которую сервер может рассчитать." ], "status": "implemented", "verified": "400 CHAT_ID_INVALID" }, { "name": "getAvailableGifts", "anchor": "getAvailableGifts", "group": "payments", "http_method": "POST", "path": "/bot/getAvailableGifts", "description": "Каталог Star Gift, из которого бот выбирает подарок. id из ответа передаётся в sendGift.", "parameters": [], "returns": "{gifts: Array<Gift>}", "notes": [ "Каталог серверный, не хардкод: не берите gift_id из констант.", "Проданный лимитированный подарок остаётся в списке — смотрите remaining_count." ], "status": "implemented", "verified": "200 OK" }, { "name": "sendGift", "anchor": "sendGift", "group": "payments", "http_method": "POST", "path": "/bot/sendGift", "description": "Отправляет Star Gift пользователю или в чат за Stars с баланса бота.", "parameters": [ { "name": "gift_id", "type": "int", "required": true, "extension": false, "description": "Из getAvailableGifts." }, { "name": "user_id", "type": "int", "required": false, "extension": false, "description": "Получатель. Взаимоисключим с chat_id; ровно одно из двух." }, { "name": "chat_id", "type": "int", "required": false, "extension": false, "description": "Получатель-чат. Взаимоисключим с user_id." }, { "name": "text", "type": "string", "required": false, "extension": false, "description": "Сопроводительный текст." }, { "name": "text_parse_mode", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "text_entities", "type": "array", "required": false, "extension": false, "description": "Ограниченный набор entity." }, { "name": "request_id", "type": "string", "required": false, "extension": true, "description": "Ключ идемпотентности, дублирует заголовок Idempotency-Key." } ], "returns": "true", "notes": [ "Без ключа идемпотентности каждый ретрай списывает Stars заново." ], "status": "implemented", "verified": "400 GIFT_ID_INVALID" }, { "name": "giftPremiumSubscription", "anchor": "giftPremiumSubscription", "group": "payments", "http_method": "POST", "path": "/bot/giftPremiumSubscription", "description": "Дарит Premium из Stars-баланса бота через тот же пайплайн, что и MTProto payments.sendStarsForm.", "parameters": [ { "name": "user_id", "type": "int", "required": true, "extension": false, "description": "Получатель; подарок себе отклоняется." }, { "name": "month_count", "type": "int", "required": true, "extension": false, "description": "1..120." }, { "name": "star_count", "type": "int", "required": true, "extension": false, "description": "Положительное, не более 10^15." }, { "name": "text", "type": "string", "required": false, "extension": false, "description": "До 128 символов." }, { "name": "text_parse_mode", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "text_entities", "type": "array", "required": false, "extension": false, "description": "" }, { "name": "request_id", "type": "string", "required": false, "extension": true, "description": "Идемпотентность: [A-Za-z0-9._:-], до 128 символов." } ], "returns": "true", "notes": [ "Повтор ключа с тем же запросом вернёт сохранённый результат; с другим получателем/тарифом/ценой — IDEMPOTENCY_KEY_INVALID." ], "status": "implemented", "verified": "400 USER_ID_INVALID" }, { "name": "refundStarPayment", "anchor": "refundStarPayment", "group": "payments", "http_method": "POST", "path": "/bot/refundStarPayment", "description": "Возвращает Stars по конкретному платежу.", "parameters": [ { "name": "user_id", "type": "int", "required": true, "extension": false, "description": "Плательщик; сверяется с записью инвойса, а не принимается на веру." }, { "name": "telegram_payment_charge_id", "type": "string", "required": true, "extension": false, "description": "Id платежа." } ], "returns": "true", "notes": [ "Возврат идёт в том же порядке транзакций, что и списание: покупателю возвращается, кошелёк бота дебетуется." ], "status": "implemented", "verified": "400 USER_ID_INVALID" }, { "name": "answerPreCheckoutQuery", "anchor": "answerPreCheckoutQuery", "group": "payments", "http_method": "POST", "path": "/bot/answerPreCheckoutQuery", "description": "Подтверждает или отклоняет оплату до списания Stars. Плательщик ждёт ответа не более 10 секунд.", "parameters": [ { "name": "pre_checkout_query_id", "type": "string", "required": true, "extension": false, "description": "" }, { "name": "ok", "type": "bool", "required": true, "extension": false, "description": "true — списать Stars, false — отменить оплату." }, { "name": "error_message", "type": "string", "required": false, "extension": false, "description": "Показывается плательщику при ok=false." } ], "returns": "true", "notes": [ "Нет ответа за 10 секунд — оплата считается несостоявшейся (PAYMENT_FAILED).", "На устаревший pre_checkout_query_id — QUERY_ID_INVALID." ], "status": "implemented", "verified": "400 QUERY_ID_INVALID" }, { "name": "dropPendingUpdates", "anchor": "dropPendingUpdates", "group": "payments", "http_method": "POST", "path": "/bot/dropPendingUpdates", "description": "Отбрасывает неподтверждённые обновления в очереди бота. Нужен боту, который отстал.", "parameters": [], "returns": "true", "notes": [ "pre_checkout_query живёт всего 10 секунд: без сброса бэклога он протухает незамеченным." ], "status": "implemented", "verified": null }, { "name": "answerShippingQuery", "anchor": "answerShippingQuery", "group": "payments", "http_method": "POST", "path": "/bot/answerShippingQuery", "description": "Распознаётся диспетчером, но всегда отвечает 501 METHOD_NOT_FOUND.", "parameters": [ { "name": "shipping_query_id", "type": "string", "required": false, "extension": false, "description": "" }, { "name": "ok", "type": "bool", "required": false, "extension": false, "description": "" }, { "name": "shipping_options", "type": "array", "required": false, "extension": false, "description": "" } ], "returns": "501", "notes": [ "Оплата Stars не имеет шага доставки — отвечать не на что. Это осознанное решение, а не пропуск." ], "status": "blocked-501", "verified": "501 METHOD_NOT_FOUND" } ], "errors": [ { "marker": "ACCESS_TOKEN_INVALID", "http": 401, "description": "Неверный или неизвестный токен." }, { "marker": "METHOD_NOT_FOUND", "http": "404 / 501", "description": "Неизвестный метод либо фича не собрана в этой сборке." }, { "marker": "BAD_REQUEST", "http": 400, "description": "Неопознанная ошибка." }, { "marker": "CHAT_ID_INVALID", "http": 400, "description": "chat_id отсутствует, равен нулю или не разбирается." }, { "marker": "MESSAGE_ID_INVALID", "http": 400, "description": "message_id отсутствует или ≤ 0." }, { "marker": "MESSAGE_IDENTIFIER_INVALID", "http": 400, "description": "inline_message_id смешан с chat_id/message_id." }, { "marker": "MESSAGE_EMPTY", "http": 400, "description": "Не передан text." }, { "marker": "MESSAGE_TOO_LONG", "http": 400, "description": "Превышен лимит текста." }, { "marker": "MESSAGE_NOT_MODIFIED", "http": 400, "description": "Правка ничего не меняет." }, { "marker": "REPLY_PARAMETERS_INVALID", "http": 400, "description": "Конфликтующие селекторы ответа." }, { "marker": "REPLY_MESSAGE_ID_INVALID", "http": 400, "description": "Отрицательный или некорректный адресат ответа." }, { "marker": "MESSAGE_THREAD_ID_INVALID", "http": 400, "description": "Вне диапазона id верхнего сообщения ephemeral-треда." }, { "marker": "ENTITY_INVALID", "http": 400, "description": "Проблема со списком entity." }, { "marker": "ENTITY_BOUNDS_INVALID", "http": 400, "description": "Смещения entity вне текста." }, { "marker": "ENTITY_TYPE_UNSUPPORTED", "http": 400, "description": "Неизвестный тип entity." }, { "marker": "ENTITIES_TOO_LONG", "http": 400, "description": "Больше 256 entity." }, { "marker": "FILE_ID_INVALID", "http": 400, "description": "Неизвестный или чужой file_id." }, { "marker": "FILE_TOO_BIG", "http": 400, "description": "Файл больше 25 MiB." }, { "marker": "MEDIA_INVALID", "http": 400, "description": "Проблема с медиа." }, { "marker": "BUTTON_INVALID", "http": 400, "description": "Проблема с разметкой кнопки." }, { "marker": "BUTTON_TYPE_INVALID", "http": 400, "description": "Тип кнопки недопустим в этом контексте." }, { "marker": "BUTTON_DATA_INVALID", "http": 400, "description": "callback_data больше 64 байт." }, { "marker": "BUTTON_URL_INVALID", "http": 400, "description": "Некорректный URL кнопки." }, { "marker": "RICH_MESSAGE_INVALID", "http": 400, "description": "Ноль или оба поля html/markdown." }, { "marker": "RICH_MESSAGE_TOO_LONG", "http": 400, "description": "Исходник больше 256 KiB." }, { "marker": "RICH_MESSAGE_DATE_INVALID", "http": 400, "description": "Некорректный tg-time." }, { "marker": "RICH_MESSAGE_BLOCKS_UNSUPPORTED", "http": 400, "description": "blocks разобран, но отклонён." }, { "marker": "RICH_MESSAGE_MEDIA_UNSUPPORTED", "http": 400, "description": "media разобран, но отклонён." }, { "marker": "WEBPAGE_MEDIA_EMPTY", "http": 400, "description": "Rich HTML сослался на удалённое медиа." }, { "marker": "EFFECT_ID_INVALID", "http": 400, "description": "Некорректный message_effect_id." }, { "marker": "VALUE_INVALID", "http": 400, "description": "Некорректный числовой параметр." }, { "marker": "BOT_COMMAND_INVALID", "http": 400, "description": "Некорректный или слишком большой commands." }, { "marker": "BOT_COMMAND_SCOPE_UNSUPPORTED", "http": 400, "description": "Не-default scope или задан language_code." }, { "marker": "EPHEMERAL_MESSAGE_ID_INVALID", "http": 400, "description": "Проблема адресации ephemeral-сообщения." }, { "marker": "EPHEMERAL_TARGET_REQUIRED", "http": 400, "description": "Не передан receiver_user_id/callback_query_id." }, { "marker": "EPHEMERAL_ACTION_EXPIRED", "http": 400, "description": "15-секундное окно истекло." }, { "marker": "QUERY_ID_INVALID", "http": 400, "description": "Неизвестный или устаревший query id." }, { "marker": "USER_ID_INVALID", "http": 400, "description": "Некорректный user_id." }, { "marker": "RESULT_ID_INVALID", "http": 400, "description": "Некорректный id inline-результата." }, { "marker": "RESULT_ID_EMPTY", "http": 400, "description": "Пустой id inline-результата." }, { "marker": "RESULT_TYPE_INVALID", "http": 400, "description": "Не article." }, { "marker": "OFFSET_INVALID", "http": 400, "description": "offset в getUpdates меньше −10000." }, { "marker": "ALLOWED_UPDATES_INVALID", "http": 400, "description": "Не JSON-массив из ≤ 100 строк." }, { "marker": "ALLOWED_UPDATES_UNSUPPORTED", "http": 501, "description": "Шлюз без сервиса управления обновлениями." }, { "marker": "MAX_CONNECTIONS_INVALID", "http": 400, "description": "Вне 1..100." }, { "marker": "SECRET_TOKEN_INVALID", "http": 400, "description": "Символы вне [A-Za-z0-9_-] или длиннее 256." }, { "marker": "WEBHOOK_URL_INVALID", "http": 400, "description": "Не абсолютный http(s)-URL или недопустимый порт." }, { "marker": "CERTIFICATE_PINNING_UNSUPPORTED", "http": 400, "description": "Передан certificate." }, { "marker": "IP_ADDRESS_UNSUPPORTED", "http": 400, "description": "Передан ip_address." }, { "marker": "WEBHOOK_UNSUPPORTED", "http": 501, "description": "Шлюз без сервиса webhooks." }, { "marker": "USER_PERMISSION_DENIED", "http": 403, "description": "Emoji status без разрешения пользователя." }, { "marker": "PREMIUM_ACCOUNT_REQUIRED", "http": 400, "description": "Emoji status без Premium у пользователя." }, { "marker": "GIFT_ID_INVALID", "http": 400, "description": "Неизвестный gift_id." }, { "marker": "BALANCE_TOO_LOW", "http": 400, "description": "Недостаточно Stars на балансе бота." }, { "marker": "STAR_COUNT_INVALID", "http": 400, "description": "Некорректное число Stars." }, { "marker": "MONTH_COUNT_INVALID", "http": 400, "description": "Месяцев вне 1..120." }, { "marker": "IDEMPOTENCY_KEY_INVALID", "http": 400, "description": "Конфликт request_id/Idempotency-Key." }, { "marker": "PAYMENT_FORM_INVALID", "http": 400, "description": "Платёжная форма отклонена." }, { "marker": "CHAT_WRITE_FORBIDDEN", "http": 400, "description": "Нет прав на запись." }, { "marker": "CHAT_ADMIN_REQUIRED", "http": 400, "description": "Не хватает прав администратора." }, { "marker": "USER_BOT_REQUIRED", "http": 400, "description": "Адресат не является ботом." }, { "marker": "CONFLICT", "http": 409, "description": "Параллельный опрос или активная доставка webhook." }, { "marker": "INTERNAL_SERVER_ERROR", "http": "500 / 503", "description": "Сбой хранилища или транспорта." } ], "limits": [ { "limit": "Длина текста", "value": "4096 символов после разбора" }, { "limit": "Длина подписи", "value": "1024 символа" }, { "limit": "Entity на сообщение", "value": "256" }, { "limit": "Id inline-результата", "value": "64 байта" }, { "limit": "Callback data", "value": "64 байта" }, { "limit": "Команд в setMyCommands", "value": "100" }, { "limit": "Размер загрузки", "value": "25 MiB на файл" }, { "limit": "Записей в allowed_updates", "value": "100" }, { "limit": "limit в getUpdates", "value": "по умолчанию и максимум 100" }, { "limit": "timeout в getUpdates", "value": "0..50 секунд" }, { "limit": "max_connections", "value": "1..100, по умолчанию 40" }, { "limit": "Исходник rich-сообщения", "value": "256 KiB" }, { "limit": "Окно ephemeral-действия", "value": "15 секунд" }, { "limit": "Срок жизни очереди обновлений", "value": "24 часа (TELESRV_BOT_API_UPDATE_RETENTION)" } ] }