Telegram Bot API

Що нового в Telegram Bot API 10.0–10.5: налаштування бота, віджети, rich-повідомлення, ефемерні повідомлення й гостьовий режим

· 9 хв читання

Telegram Bot API 10.5 вийшов 22 листопада 2026 року — це актуальна версія, у ній 194 методи. За шість релізів гілки 10.x (перший, Bot API 10.0, вийшов 8 травня 2026 року) боти отримали гостьовий режим, rich-повідомлення з таблицями та стримінгом відповідей ШІ, ефемерні повідомлення, які в групі бачить лише один користувач, обробку заявок на вступ через Mini App, захист Mini Apps від викликів із чужих доменів, інтерактивні HTML-віджети просто в повідомленнях (10.4), а в 10.5 — метод setMySettings для налаштування бота з коду й новий об'єкт BotFullInfo у відповіді getMe. Розбираємо, що нового в Telegram Bot API за версіями, — із прикладами запитів і чек-листом міграції.

Bot API 10.0–10.5 коротко

ВерсіяДатаГоловне
10.08 травня 2026Гостьовий режим, live photos (sendLivePhoto), медіа в опитуваннях, видалення реакцій
10.111 червня 2026Rich-повідомлення (sendRichMessage, sendRichMessageDraft), заявки на вступ (answerChatJoinRequestQuery)
10.214 липня 2026Ефемерні повідомлення, спільноти (Communities), апдейт subscription, захист Mini Apps за origin
10.324 серпня 2026EphemeralMessageParameters, кнопки й документи в rich-повідомленнях, DisabledButton, зупинка генерації
10.49 листопада 2026HTML-віджети (sendWidget), ефемерні відповіді на callback-запити в будь-якому чаті, цитати з rich-повідомлень, картка TON-гаманця, теми для поширення чату
10.522 листопада 2026setMySettings, BotFullInfo у getMe, режим callback_query_mode, запрошення в чат із ботом, блоки в згортуваних цитатах

Що нового в Telegram Bot API 10.5: setMySettings, BotFullInfo і запрошення до бота

Налаштування бота з коду. Новий метод setMySettings змінює налаштування, які раніше були доступні лише в @BotFather. Усі параметри необов'язкові — передавайте тільки те, що хочете змінити; метод повертає True:

{
  "supports_inline_queries": true,
  "inline_query_placeholder": "Пошук рецептів...",
  "can_join_groups": false,
  "has_topics_enabled": true,
  "callback_query_mode": "auto"
}

Надішліть цей JSON на https://api.telegram.org/bot<token>/setMySettings або відкрийте setMySettings у тестері, а потім викличте getMe, щоб перевірити результат.

BotFullInfo — зміна, що ламає сумісність. getMe тепер повертає новий об'єкт BotFullInfo замість User, а поля, які приходили лише у відповіді getMe, з User прибрано. У BotFullInfo додано active_usernames, inline_query_placeholder, needs_inline_query_location і has_topic_sidebar. Код, що читає з відповіді getMe поля на кшталт can_join_groups, can_read_all_group_messages або supports_inline_queries, і далі працюватиме — вони є в BotFullInfo. Зламається код, який чекає ці поля в інших об'єктах User, і типізований код, де результат getMe оголошено як User.

Що нового в Telegram Bot API 10.4: віджети, ефемерні відповіді в будь-якому чаті й TON-гаманець

Віджети. Тепер бот може надсилати всередині повідомлення невеликі інтерактивні HTML-блоки. Віджет — це один HTML-документ (до 32768 байтів і до 4096 байтів після стиснення zlib), який застосунок виконує в пісочниці без доступу до мережі, плюс стан, який змінює лише бот: chat_data для одного повідомлення і public_data, спільний усюди, де показано віджет. Нові методи: sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData і editSharedWidgetData; нові апдейти — widget_query і shared_widget_query; для інлайн-режиму додано InputWidgetMessageContent і InputSharedWidgetMessageContent (поки лише на тестовому сервері).

{
  "chat_id": 123456789,
  "html": "<h3>Замовлення №1042</h3><p>2 × Маргарита, 1 × Лимонад</p><p><strong>Разом: $23.50</strong></p>",
  "caption": "Замовлення №1042: $23.50"
}

У продакшені віджети поки працюють лише в особистих чатах і надсилаються із захищеним вмістом, тому переслати їх не можна; групи, інлайн-режим і пересилання працюють на тестовому сервері. Повідомлення з віджетами не можна скопіювати через copyMessage / copyMessages, а право can_send_other_messages тепер поширюється і на віджети. Докладніше — у гайді віджети Telegram, готовий код — у прикладах віджетів.

Ефемерні відповіді на callback-запити в будь-якому чаті (крім чатів особистих повідомлень каналів). Передайте в ephemeral_message_parameters лише callback_query_id, без receiver_user_id, — і повідомлення побачить тільки той, хто натиснув кнопку. Параметр receiver_user_id і параметр chat_id методів надсилання тепер необов'язкові. Викликати answerCallbackQuery, як і раніше, потрібно.

{
  "text": "Цю відповідь бачите лише ви.",
  "ephemeral_message_parameters": {"callback_query_id": "<callback_query.id>"}
}

Bot API 10.3: EphemeralMessageParameters, кнопки й зупинка генерації

Найважливіша зміна 10.3 ламає зворотну сумісність. Параметри ефемерних повідомлень receiver_user_id і callback_query_id, додані в 10.2, прибрали з 13 методів надсилання (sendMessage, sendPhoto, sendVideo, sendDocument, sendSticker та інших) і перенесли в об'єкт EphemeralMessageParameters, який передається в параметрі ephemeral_message_parameters. Цей самий параметр отримав sendRichMessage. Інші новинки:

Rich-повідомлення: sendRichMessage і стримінг відповідей ШІ

Rich-повідомлення з'явилися в 10.1 і розраховані на структурований контент: звіти, документацію, відповіді ШІ-асистентів. Метод sendRichMessage приймає об'єкт rich_message (InputRichMessage), у якому заповнюється рівно одне з полів: markdown, html або blocks. Rich Markdown за можливості сумісний із GitHub Flavored Markdown: заголовки, таблиці, списки завдань, формули LaTeX, виноски й медіаблоки.

curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendRichMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "rich_message": {
      "markdown": "# Звіт за тиждень\n\n| Метрика | Значення |\n|:---|---:|\n| Нові користувачі | **1 204** |\n| Конверсія | 3,2% |\n\n- [x] Реліз 2.4\n- [ ] Перехід на Bot API 10.3"
    }
  }'

Обмеження: до 32 768 символів тексту, до 500 блоків, до 16 рівнів вкладеності, до 50 медіа й до 20 стовпців у таблиці. Відредагувати надіслане rich-повідомлення можна через editMessageText із параметром rich_message.

Для ШІ-ботів головне — стримінг. sendRichMessageDraft (і sendMessageDraft для звичайного тексту) показує в особистому чаті чернетку, яка оновлюється в міру генерації. Чернетка — тимчасове прев'ю приблизно на 30 секунд: коли відповідь готова, обов'язково надішліть її через sendRichMessage, інакше вона не збережеться в чаті.

import requests

API_URL = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
CHAT_ID, DRAFT_ID = 123456789, 1  # draft_id — будь-яке ненульове число

text = ""
for chunk in ["## Відповідь\n\n", "Збираю дані…", "\n\n- пункт 1\n- пункт 2"]:  # частини від LLM
    text += chunk
    requests.post(f"{API_URL}/sendRichMessageDraft", json={
        "chat_id": CHAT_ID, "draft_id": DRAFT_ID,
        "rich_message": {"markdown": text}, "can_stop": True,
    }, timeout=10)

requests.post(f"{API_URL}/sendRichMessage", json={
    "chat_id": CHAT_ID, "rich_message": {"markdown": text},
}, timeout=10)
const API_URL = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const CHAT_ID = 123456789, DRAFT_ID = 1; // draft_id — будь-яке ненульове число
const post = (method, body) => fetch(`${API_URL}/${method}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(10_000),
});

let text = "";
for (const chunk of ["## Відповідь\n\n", "Збираю дані…", "\n\n- пункт 1\n- пункт 2"]) { // частини від LLM
  text += chunk;
  await post("sendRichMessageDraft", {
    chat_id: CHAT_ID, draft_id: DRAFT_ID,
    rich_message: { markdown: text }, can_stop: true,
  });
}

await post("sendRichMessage", {
  chat_id: CHAT_ID, rich_message: { markdown: text },
});

Із can_stop користувач побачить кнопку зупинки, а бот отримає апдейт stopped_message_generation — за ним варто перервати генерацію на боці моделі. Порожній текст у sendMessageDraft або тег <tg-thinking> у rich-чернетці показують заглушку «Thinking...».

Ефемерні повідомлення: відповідь, яку бачить один учасник

Ефемерні повідомлення (10.2) дають змогу ботові відповісти в групі так, що повідомлення побачать лише конкретний користувач і сам бот: привітання, підказки, персональні зведення. Правила надсилання з документації:

Із версії 10.4 ефемерно відповісти на натискання кнопки можна в будь-якому чаті (крім чатів особистих повідомлень каналів): достатньо передати callback_query_id без receiver_user_id. Запит у форматі Bot API 10.3 з явним отримувачем:

curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": -1001234567890,
    "text": "Це повідомлення бачите лише ви",
    "ephemeral_message_parameters": {
      "receiver_user_id": 123456789,
      "callback_query_id": "ID_З_CALLBACK_QUERY"
    }
  }'

У відповіді об'єкт Message матиме поле ephemeral_message_id. За ним повідомлення редагують методами editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup і видаляють через deleteEphemeralMessage:

curl -s -X POST "https://api.telegram.org/bot$TOKEN/deleteEphemeralMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": -1001234567890, "receiver_user_id": 123456789, "ephemeral_message_id": 17}'

Працює і зворотний напрямок: якщо в setMyCommands позначити команду прапорцем is_ephemeral, її виклик користувачем не побачать інші учасники чату.

Заявки на вступ: answerChatJoinRequestQuery

Із версії 10.1 бот, призначений обробляти заявки на вступ до чату, отримує в апдейті chat_join_request поле query_id. Відреагувати треба протягом 10 секунд одним із двох способів:

  1. показати користувачеві Mini App (капча, анкета, правила) методом sendChatJoinRequestWebApp з параметрами chat_join_request_query_id і web_app_url — застосунок отримає chat_join_request_query_id в initData;
  2. одразу ухвалити рішення методом answerChatJoinRequestQuery.
curl -s -X POST "https://api.telegram.org/bot$TOKEN/answerChatJoinRequestQuery" \
  -H "Content-Type: application/json" \
  -d '{"chat_join_request_query_id": "QUERY_ID_З_АПДЕЙТУ", "result": "approve"}'

Параметр result приймає "approve" (впустити), "decline" (відхилити) або "queue" (залишити рішення іншим адміністраторам). Чи підтримує бот такі запити, видно з поля supports_join_request_queries у відповіді getMe, а бот-охоронця чату вказано в полі guard_bot відповіді getChat.

Bot API 10.0: гостьовий режим, live photos і опитування з медіа

Bot API 10.2: спільноти, підписки й захист Mini Apps

Чек-лист міграції на Bot API 10.5

  1. Якщо ви вже надсилали ефемерні повідомлення у форматі 10.2, перенесіть receiver_user_id і callback_query_id всередину ephemeral_message_parameters.
  2. Якщо в allowed_updates типи перелічено явно, додайте потрібні нові: guest_message, subscription, stopped_message_generation, widget_query, shared_widget_query. Інакше ці апдейти не надходитимуть.
  3. Оновіть бібліотеку (python-telegram-bot, aiogram, grammY, Telegraf) до версії, у changelog якої заявлено підтримку Bot API 10.5. Поки підтримки немає, нові методи можна викликати звичайним HTTP-запитом.
  4. Перевірте Mini Apps: усі сторінки, що звертаються до Telegram.WebApp, мають відкриватися з домену застосунку.
  5. Якщо код розбирає опитування, врахуйте, що тепер у них може бути лише один варіант відповіді.
  6. Якщо код посилається на тип StoryAreaPosition за назвою, перейменуйте його на AreaPosition.
  7. Вважайте результат getMe об'єктом BotFullInfo і не читайте поля, які були лише в getMe (наприклад, can_join_groups), з інших об'єктів User.
  8. У rich-повідомленнях збирайте згортувані цитати з blocks замість text.
  9. Якщо перемикаєте callback_query_mode на "auto" або "inline", навчіть обробник callback-запитів працювати з inline_message_id, коли поля message немає.

Як спробувати нові методи

Усі 194 методи Bot API 10.5 доступні в Bot API Tester: налаштуйте бота через setMySettings, відкрийте sendWidget у тестері й надішліть собі віджет із прикладу вище або sendRichMessage — для rich-повідомлення; знадобиться лише токен тестового бота. Схеми запитів зручно дивитися у Swagger-документації, опис параметрів — у довіднику методів. Базові прийоми надсилання й форматування зібрано в гайді як надіслати повідомлення через бота, обмеження на частоту й розміри — у гайді ліміти Telegram Bot API. Повна історія змін — в офіційному Bot API changelog.

Поширені запитання

Яка остання версія Telegram Bot API?

Bot API 10.5 від 22 листопада 2026 року, у ній 194 методи. Це шостий реліз гілки 10.x, яка почалася 8 травня 2026 року з Bot API 10.0; головні новинки 10.5 — метод setMySettings, яким бот сам змінює свої налаштування, і об'єкт BotFullInfo у відповіді getMe. Попередня версія 10.4 (9 листопада 2026 року) додала HTML-віджети в повідомленнях. Усі зміни Telegram публікує в офіційному changelog на core.telegram.org.

Що таке віджети в Telegram Bot API 10.4?

Невеликі інтерактивні HTML-блоки всередині повідомлення бота. Їх надсилають методом sendWidget: один HTML-документ до 32768 байтів (4096 байтів після стиснення zlib) виконується в пісочниці без мережі, а стан (chat_data, public_data) змінює лише бот. У продакшені віджети поки працюють тільки в особистих чатах із ботом.

Що таке rich-повідомлення в Telegram?

Це повідомлення зі складною структурою: заголовки, таблиці, списки, формули, медіа та кнопки. Їх надсилають методом sendRichMessage (Bot API 10.1), а для потокового виведення відповіді є sendRichMessageDraft.

Що таке ефемерні повідомлення в Telegram-боті?

Повідомлення в групі, які бачать лише один користувач і бот. Вони з'явилися в Bot API 10.2, із версії 10.3 отримувача вказують в об'єкті ephemeral_message_parameters, а з 10.4 бот може ефемерно відповісти на натискання кнопки в будь-якому чаті, крім чатів особистих повідомлень каналів. Доставку не гарантовано, особливо якщо користувач офлайн.

Чи треба переписувати бота під Bot API 10.5?

Зазвичай ні. Перевірте три місця: getMe тепер повертає BotFullInfo, а поля, які приходили лише в getMe, прибрано з User; у згортуваних цитатах rich-повідомлень поле text замінено на blocks; ефемерні повідомлення у форматі 10.2 треба перевести на ephemeral_message_parameters (10.3). Ще в 10.4 тип StoryAreaPosition перейменовано на AreaPosition.

Як спробувати методи Bot API 10.5 без коду?

Відкрийте Bot API Tester: у ньому є всі 194 методи версії 10.5, зокрема setMySettings, sendWidget, sendRichMessage і deleteEphemeralMessage. Вставте токен, заповніть параметри й натисніть Ctrl+Enter.

Як створити бота в Телеграм: від @BotFather до першого повідомлення

Як створити бота в Телеграм: реєстрація в @BotFather, токен, перевірка через getMe, перше повідомлення на curl і Python, команди та опис бота.

Ліміти Telegram Bot API: повідомлення на секунду, помилка 429 і розміри файлів

Ліміти Telegram Bot API в одному місці: повідомлення на секунду, помилка 429 і retry_after, платні розсилки, розміри файлів, довжина тексту й підпису.

Як надіслати повідомлення через бота Telegram: sendMessage, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.

Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати

Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.

Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення

Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.

Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму

Як дізнатися chat id у Телеграм через getUpdates: особистий чат, група, супергрупа, канал і тема форуму. Формати id з -100 і що робити з порожнім result.

Тестовий сервер Telegram: як тестувати бота в тестовому середовищі

Тестовий сервер Telegram для ботів: вхід у тестове середовище, створення тестового бота, запити до Bot API через /test/ і перемикач TEST у тестері.

Віджети Telegram для сайту: вхід через Telegram, вбудовування постів, коментарі й кнопка «Поділитися»

Вхід через Telegram на сайті: новий Telegram Login (OIDC), старий Login Widget із перевіркою hash, вбудовування постів, коментарі та кнопка «Поділитися».

TelegramWidget JavaScript API: властивості, події, коди помилок і ліміти

Довідник TelegramWidget API: властивості, request(), події, коди помилок, CSS-змінні, widget_query та answerWidgetQuery, а також усі ліміти віджетів.

Приклади віджетів Telegram: готовий HTML і код бота на Python

Робочі приклади віджетів Telegram із повним кодом: картка замовлення, лічильник із запитами widget_query, спільне живе опитування та прев'ю в браузері.

Віджети Telegram: інтерактивний HTML просто в повідомленнях бота

Віджети Telegram у Bot API 10.4: що це, як працюють sendWidget, chat_data і public_data, де віджети доступні зараз і чим вони відрізняються від Mini Apps.

Тестування Telegram Mini App: від браузера до налагодження на телефоні

Тестування Telegram Mini App крок за кроком: mock-режим у браузері, HTTPS-тунель для localhost, тестове середовище, DevTools на телефоні та initData.