Тестування Telegram Mini App: від браузера до налагодження на телефоні
Тестування Telegram Mini App найзручніше будувати у три шари: спочатку верстка й логіка у звичайному браузері з емуляцією Telegram.WebApp, потім запуск усередині Telegram через HTTPS-тунель із DevTools на пристрої і, нарешті, перевірка initData на сервері. Нижче — покроковий план із командами та кодом, а наприкінці чек-лист, який закриває класичне «у браузері працює, а в Telegram — ні».
Крок 1. Тест Mini App у звичайному браузері
Mini App — це звичайна вебсторінка з підключеним скриптом telegram-web-app.js. У браузері об'єкт window.Telegram.WebApp теж з'явиться, але без даних: initData — порожній рядок, користувача й кольорів теми немає. Тому одразу закладайте запасні значення:
<!DOCTYPE html>
<html lang="uk">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
<h1 id="hello">Завантаження…</h1>
<script>
const tg = window.Telegram.WebApp;
// поза Telegram initData порожній, а initDataUnsafe.user відсутній
const user = tg.initDataUnsafe.user ?? { first_name: 'Тестовий користувач' };
document.getElementById('hello').textContent = `Привіт, ${user.first_name}!`;
document.body.style.background = tg.themeParams.bg_color || '#ffffff';
tg.ready();
</script>
</body>
</html>
Щоб не писати моки вручну, відкрийте Mini App Tester. У звичайному браузері він працює в mock-режимі: емулює Telegram.WebApp, показує живу панель властивостей (version, platform, colorScheme, initData, themeParams, safe areas) і журнал понад 45 подій. Так можна розібратися, як поводяться кнопки, попапи, CloudStorage та інші API, ще до деплою. Пам'ятайте лише, що mock-дані Telegram не підписує, тож серверну перевірку вони (цілком правильно) не пройдуть.
Крок 2. Як підключити міні застосунок у Телеграм до бота
Щоб Mini App відкривався всередині Telegram, потрібні бот (як його створити — у гайді як створити бота в Телеграм) і HTTPS-адреса сторінки. Способи запуску:
/newappв @BotFather — Mini App із прямим посиланням виглядуhttps://t.me/<bot>/<app>; параметрstartappіз посилання передається в застосунок;- кнопка меню бота —
/setmenubuttonабо Bot Settings → Menu Button, а для окремих користувачів — методsetChatMenuButton; - Main Mini App — кнопка «Launch app» у профілі бота й посилання
https://t.me/<bot>?startapp; - кнопки
web_appу reply- та inline-клавіатурах.
Для налагодження найзручніша кнопка меню: її можна переналаштувати одним запитом, не заходячи в @BotFather.
curl -s -X POST "https://api.telegram.org/bot$TOKEN/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"menu_button": {
"type": "web_app",
"text": "Відкрити застосунок",
"web_app": {"url": "https://example.trycloudflare.com"}
}
}'
Якщо передати chat_id свого особистого чату з ботом, кнопка зміниться лише у вас — інші користувачі й далі бачитимуть робочу версію. Готовий тестер теж можна одразу вказати як URL Mini App: https://telegram-bot-api.info/telegram-mini-app-tester.html — усередині Telegram він покаже реальні дані клієнта.
Крок 3. Telegram Mini App на localhost: HTTPS-тунель
Telegram відкриває Mini App лише за HTTPS, а localhost вашого комп'ютера з телефона недоступний. Рішення — тунель, який видає публічну HTTPS-адресу й проксує запити на локальний порт:
# dev-сервер уже запущено, наприклад Vite на порту 5173
# варіант 1: Cloudflare Quick Tunnel
cloudflared tunnel --url http://localhost:5173
# варіант 2: ngrok
ngrok http 5173
Скопіюйте отриману адресу https://… і пропишіть її в @BotFather або через setChatMenuButton. Кілька підводних каменів:
- адреса безкоштовного тунелю зазвичай змінюється після кожного перезапуску — не забувайте оновлювати URL у бота;
- свіжі версії Vite відхиляють запити з незнайомим заголовком
Host— додайте домен тунелю вserver.allowedHosts; - якщо після змін видно стару версію, закрийте й знову відкрийте Mini App: WebView може тримати сторінку в кеші.
Крок 4. Тестове середовище Telegram
У Telegram є окреме тестове середовище з власними акаунтами й ботами. Головний плюс для Mini Apps — там дозволені HTTP-посилання без TLS. Як увійти:
- iOS: 10 разів натисніть на іконку налаштувань → Accounts → Login to another account → Test;
- Telegram Desktop: ☰ Settings → Shift+Alt+правий клік по «Add Account» → «Test Server»;
- macOS: 10 кліків по іконці налаштувань відкриють Debug Menu, далі ⌘+клік по «Add Account».
Середовище повністю окреме: знадобляться новий акаунт і новий бот, створений через @BotFather уже всередині нього. Запити до API такого бота надсилайте на https://api.telegram.org/bot<token>/test/METHOD_NAME. Ліміти на частоту там не підвищені, тож для навантажувальних тестів воно не підходить. Докладне налаштування, зокрема перемикач TEST у нашому Bot API Tester, — у гайді тестовий сервер Telegram.
Крок 5. Налагодження Mini App усередині Telegram
| Платформа | Як увімкнути DevTools |
|---|---|
| iOS | 10 натискань на іконку налаштувань → Allow Web View Inspection; підключіть iPhone до Mac через USB і відкрийте в Safari меню Develop → ваш пристрій |
| Android | Увімкніть налагодження через USB; у налаштуваннях Telegram прогорніть донизу, двічі натисніть і утримуйте номер версії → Enable WebView Debug; відкрийте chrome://inspect/#devices у Chrome |
| Telegram Desktop (Windows, Linux) | Бета-версія: Settings → Advanced → Experimental settings → Enable webview inspection; правий клік у Mini App → Inspect |
| Telegram для macOS | Бета-версія: 5 швидких кліків по іконці налаштувань → Debug Mini Apps; правий клік → Inspect Element |
Пункти меню інколи змінюються, тому звіряйтеся з офіційним розділом Debug Mode for Mini Apps. Якщо підключити DevTools не вдається, відкрийте на пристрої Mini App Tester: він покаже version, platform, тему, safe areas і всі події, які надсилає клієнт. Нові функції у своєму коді обгортайте перевіркою Telegram.WebApp.isVersionAtLeast().
Крок 6. Перевірка initData на сервері
Даним з initDataUnsafe довіряти не можна: їх легко підмінити. Передавайте на бекенд сирий рядок Telegram.WebApp.initData (наприклад, у заголовку Authorization) і перевіряйте підпис:
- розберіть рядок як query string і вилучіть
hash; - зберіть
data_check_string: усі інші поля у виглядіkey=value, відсортовані за ключем і з'єднані символом\n(прибирається лишеhash); - обчисліть
secret_key = HMAC_SHA256(key="WebAppData", message=bot_token); - дані справжні, якщо
hex(HMAC_SHA256(key=secret_key, message=data_check_string))збігається зhash; - перевірте свіжість
auth_date, щоб не приймати старі дані повторно.
Python і Node.js:
import hashlib, hmac, json, time
from urllib.parse import parse_qsl
def validate_init_data(init_data: str, bot_token: str, max_age: int = 3600):
data = dict(parse_qsl(init_data, keep_blank_values=True))
received_hash = data.pop("hash", "")
check_string = "\n".join(f"{k}={v}" for k, v in sorted(data.items()))
secret_key = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
expected = hmac.new(secret_key, check_string.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, received_hash):
return None
if time.time() - int(data.get("auth_date", 0)) > max_age:
return None
data["user"] = json.loads(data.get("user", "null"))
return dataimport crypto from 'node:crypto';
export function validateInitData(initData, botToken, maxAgeSec = 3600) {
const params = new URLSearchParams(initData);
const hash = params.get('hash');
if (!hash) return null;
params.delete('hash');
const dataCheckString = [...params.entries()]
.map(([key, value]) => `${key}=${value}`)
.sort()
.join('\n');
const secretKey = crypto.createHmac('sha256', 'WebAppData').update(botToken).digest();
const expected = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest();
const received = Buffer.from(hash, 'hex');
if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) return null;
const authDate = Number(params.get('auth_date'));
if (!authDate || Date.now() / 1000 - authDate > maxAgeSec) return null;
return { ...Object.fromEntries(params), user: JSON.parse(params.get('user') ?? 'null') };
}Дві типові помилки: рахувати підпис від рядка, не декодованого з URL (значення спершу треба розкодувати, як це роблять URLSearchParams і parse_qsl), і переплутати аргументи першого HMAC — рядок WebAppData є ключем, а токен бота — повідомленням.
Bot API 10.2: захист методів Mini App
Починаючи з Bot API 10.2, Telegram блокує виклики методів Mini App зі сторінок, origin яких відрізняється від домену самого застосунку. Для всіх Mini Apps захист увімкнувся автоматично 20 липня 2026 року. Вимкнути його можна в Mini App @BotFather, але тоді ви самі відповідаєте за те, щоб у застосунку не було посилань на недовірені сайти. Що це означає для тестів:
- якщо після редиректу (OAuth, оплата на зовнішній сторінці) користувач опинився на іншому домені, методи
Telegram.WebAppтам не спрацюють — перевірте такі сценарії окремо; - тримайте всі екрани, що звертаються до API Mini App, на домені, вказаному в бота;
- вимикайте захист лише тоді, коли без цього ніяк, і тоді самі перевіряйте всі зовнішні посилання.
Чек-лист тестування Telegram Mini App перед релізом
telegram-web-app.jsпідключено в<head>раніше за інші скрипти;Telegram.WebApp.ready()викликається, щойно інтерфейс готовий;- кольори беруться з
themeParamsабо CSS-змінних--tg-theme-*, перевірено світлу й темну теми; - у повноекранному режимі враховано
safeAreaInsetіcontentSafeAreaInset; - нові функції обгорнуто в перевірку
isVersionAtLeast()— у користувачів бувають старі клієнти; initDataперевіряється на сервері, включно зauth_date;- усі сторінки з викликами API працюють на одному HTTPS-домені;
- застосунок перевірено на iOS, Android і Desktop.
Далі стануть у пригоді гайди як отримати токен бота (він потрібен для перевірки initData) і що нового в Telegram Bot API 10.5. Якщо вам потрібен лише невеликий інтерактивний блок усередині повідомлення, а не цілий вебзастосунок, погляньте на віджети Telegram з Bot API 10.4. Кнопку меню з адресою вашого Mini App можна налаштувати просто в браузері: setChatMenuButton у Bot API Tester.
Поширені запитання
Чи можна відкрити Telegram Mini App у звичайному браузері?
Так, але Telegram.WebApp там буде без даних: initData порожній, немає користувача й кольорів теми. Верстку та логіку перевіряйте в mock-режимі, наприклад у Mini App Tester, а нативні функції — вже всередині Telegram.
Як протестувати Mini App на localhost?
Підніміть HTTPS-тунель до локального порту (наприклад, cloudflared або ngrok) і вкажіть отриману адресу в @BotFather або через setChatMenuButton. Telegram вимагає HTTPS; HTTP-посилання дозволені лише в тестовому середовищі.
Як зробити міні застосунок у Телеграм і підключити його до бота?
Розмістіть вебсторінку з підключеним telegram-web-app.js на HTTPS і прив'яжіть її до бота: командою /newapp в @BotFather (пряме посилання t.me/<bot>/<app>), через кнопку меню бота або кнопку web_app у клавіатурі.
Як відкрити DevTools для Mini App на телефоні?
На iOS увімкніть Allow Web View Inspection у налагоджувальному меню Telegram і підключіться через Safari на Mac. На Android увімкніть Enable WebView Debug у налаштуваннях Telegram і відкрийте chrome://inspect/#devices у Chrome на комп'ютері.
Як перевірити initData на сервері?
Обчисліть secret_key = HMAC_SHA256(key="WebAppData", message=bot_token), потім HMAC-SHA256 цим ключем від відсортованого рядка key=value усіх полів, крім hash. Результат у hex має збігтися з hash, а auth_date — бути свіжим.
Чому методи Mini App не працюють після переходу на інший сайт?
Із Bot API 10.2 Telegram блокує виклики методів Mini App зі сторінок, origin яких відрізняється від домену застосунку. Для всіх Mini Apps захист увімкнено з 20 липня 2026 року; вимкнути його можна в Mini App @BotFather.
Читайте також
Як створити бота в Телеграм: від @BotFather до першого повідомлення
Як створити бота в Телеграм: реєстрація в @BotFather, токен, перевірка через getMe, перше повідомлення на curl і Python, команди та опис бота.
Що нового в Telegram Bot API 10.0–10.5: налаштування бота, віджети, rich-повідомлення, ефемерні повідомлення й гостьовий режим
Що нового в Telegram Bot API 10.0–10.5: setMySettings і BotFullInfo, HTML-віджети, rich- та ефемерні повідомлення, гостьовий режим — з прикладами.
Ліміти 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.