Что подготовить и какой способ запуска используем
Понадобятся тестовый бот, PHP 8.3+ на 64-битной системе с cURL, mbstring и PDO SQLite, а также доступный по HTTPS адрес приложения с действительным сертификатом. Если бота ещё нет, начните с BotFather. Сначала откройте его личный чат и нажмите «Старт»: в этом примере подтверждение отправляется в уже начатый диалог.
Mini Apps также называют Web Apps в именах объектов API. Мы используем кнопку меню личного чата с типом web_app и обычный fetch к собственному PHP endpoint. sendData здесь не нужен: он предназначен для другого способа запуска — кнопки обычной клавиатуры. Сначала сервер сохраняет заявку, затем возвращает результат форме. Никакой Telegram-токен в браузер не передаётся.
Создайте такую структуру. Корнем сайта должен быть только public. app.php, установочный скрипт и var с базой не должны быть доступны по HTTP.
mini-app/
app.php
install.php
setup-menu.php
var/
public/
index.html
submit.php
В окружении PHP-процесса задайте BOT_TOKEN — токен именно этого бота. CLI и PHP-FPM могут иметь разные окружения: проверьте значение в обоих без вывода самого секрета. Простое создание .env в таком проекте его не загрузит. Пользователю PHP нужен доступ на запись к var и файлам SQLite. Не размещайте там чужие файлы и резервные копии публично.
Общий PHP-код: проверка Telegram и сохранение
Создайте app.php. Функция validateInitData получает исходную строку Telegram.WebApp.initData. Мы декодируем каждое значение один раз, запрещаем повторяющиеся ключи, исключаем hash, сортируем остальные поля и вычисляем HMAC. Если присутствует поле signature, при этом способе с токеном оно остаётся в проверяемой строке; алгоритм проверки Ed25519 без токена устроен иначе.
Срок в 10 минут и допуск 30 секунд в будущее — политика нашего примера. После истечения срока пользователь переоткрывает приложение. Внутренние часы сервера должны быть синхронизированы. Подпись проверяем до JSON-декодирования user, а ID берём только из подписанных данных. initDataUnsafe на сервер не отправляем.
<?php
declare(strict_types=1);
function botToken(): string
{
$token = getenv('BOT_TOKEN');
if (!is_string($token) || $token === '') {
throw new RuntimeException('Set BOT_TOKEN in the PHP process');
}
return $token;
}
function validateInitData(string $raw, string $token, int $now): int
{
if ($raw === '' || strlen($raw) > 12000) {
throw new DomainException('Invalid Telegram data');
}
$fields = [];
foreach (explode('&', $raw) as $pair) {
$parts = explode('=', $pair, 2);
if (count($parts) !== 2) {
throw new DomainException('Invalid Telegram data');
}
$key = urldecode($parts[0]);
if (!preg_match('/^[a-zA-Z0-9_]+$/D', $key)
|| array_key_exists($key, $fields)) {
throw new DomainException('Invalid Telegram fields');
}
$fields[$key] = urldecode($parts[1]);
}
$hash = $fields['hash'] ?? '';
unset($fields['hash']);
if (!preg_match('/^[a-f0-9]{64}$/D', $hash)) {
throw new DomainException('Invalid Telegram hash');
}
ksort($fields, SORT_STRING);
$lines = [];
foreach ($fields as $key => $value) {
$lines[] = $key.'='.$value;
}
$secret = hash_hmac('sha256', $token, 'WebAppData', true);
$expected = hash_hmac('sha256', implode("\n", $lines), $secret);
if (!hash_equals($expected, $hash)) {
throw new DomainException('Invalid Telegram signature');
}
$date = $fields['auth_date'] ?? '';
if (!ctype_digit($date) || (int) $date < $now - 600 || (int) $date > $now + 30) {
throw new DomainException('Reopen the Mini App');
}
try {
$user = json_decode($fields['user'] ?? '', true, 32, JSON_THROW_ON_ERROR);
} catch (JsonException) {
throw new DomainException('Invalid Telegram user');
}
if (!is_array($user) || !is_int($user['id'] ?? null) || $user['id'] <= 0) {
throw new DomainException('Invalid Telegram user');
}
return $user['id'];
}
function database(): PDO
{
$db = new PDO('sqlite:'.__DIR__.'/var/leads.sqlite', null, null, [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
$db->exec('PRAGMA busy_timeout = 5000');
return $db;
}
function saveLead(PDO $db, int $userId, string $requestId, string $name, string $question): array
{
$insert = $db->prepare('INSERT INTO leads
(user_id, request_id, name, question, created_at, notification)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(user_id, request_id) DO NOTHING');
$insert->execute([$userId, $requestId, $name, $question, time(), 'pending']);
$created = $insert->rowCount() === 1;
$select = $db->prepare('SELECT * FROM leads WHERE user_id = ? AND request_id = ?');
$select->execute([$userId, $requestId]);
$lead = $select->fetch();
if ($lead === false) {
throw new RuntimeException('Lead not found');
}
if ($lead['name'] !== $name || $lead['question'] !== $question) {
throw new LogicException('Request ID already used with different fields');
}
return ['lead' => $lead, 'created' => $created];
}
function telegram(string $method, array $params): mixed
{
$curl = curl_init('https://api.telegram.org/bot'.botToken().'/'.$method);
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($params, JSON_THROW_ON_ERROR),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 3,
CURLOPT_TIMEOUT => 8,
]);
try {
$raw = curl_exec($curl);
if ($raw === false) {
throw new RuntimeException('Telegram result unknown');
}
$body = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (!is_array($body) || !is_bool($body['ok'] ?? null)) {
throw new RuntimeException('Invalid Telegram response');
}
if ($body['ok'] === false) {
throw new UnexpectedValueException('Telegram rejected request');
}
if (curl_getinfo($curl, CURLINFO_HTTP_CODE) !== 200) {
throw new RuntimeException('Unexpected HTTP status');
}
return $body['result'];
} finally {
unset($curl);
}
}
function notifyLead(int $userId, int $leadId): string
{
try {
telegram('sendMessage', [
'chat_id' => $userId,
'text' => 'Заявка №'.$leadId.' сохранена. Спасибо за обращение!',
]);
return 'sent';
} catch (UnexpectedValueException) {
return 'rejected';
} catch (Throwable) {
return 'unknown';
}
}
Сохранение использует составной ключ user_id/request_id. При повторе с теми же полями возвращается прежняя заявка; другой пользователь не получает её по чужому request_id. При изменённых полях сервер отклоняет повтор, а не незаметно перезаписывает запись. В этом небольшом проекте один бот и одна база; для нескольких ботов добавьте bot_id в ключ и запросы.
Подготовленные PDO-запросы отделяют значения формы от SQL. Подпись Telegram подтверждает личность, но поля name и question всё равно остаются пользовательским вводом. При отображении этих значений в кабинете экранируйте их под HTML; при пересылке с parse_mode — под разметку Telegram.
Создаём таблицу один раз
Установочный скрипт запускается из корня проекта в CLI. Он не выполняется при открытии формы и не должен лежать в public.
<?php
declare(strict_types=1);
if (PHP_SAPI !== 'cli') {
http_response_code(404);
exit;
}
require __DIR__.'/app.php';
if (!is_dir(__DIR__.'/var') && !mkdir(__DIR__.'/var', 0700)) {
throw new RuntimeException('Cannot create private storage');
}
database()->exec('CREATE TABLE IF NOT EXISTS leads (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
request_id TEXT NOT NULL,
name TEXT NOT NULL,
question TEXT NOT NULL,
created_at INTEGER NOT NULL,
notification TEXT NOT NULL,
UNIQUE (user_id, request_id)
)');
echo "Storage ready\n";
php install.php
Ожидаемый результат — Storage ready и файл var/leads.sqlite. Ошибка драйвера означает, что в PHP отсутствует PDO SQLite; ошибка доступа требует исправить права на частный каталог. Не переключайте приложение на публичный JSON-файл ради обхода настройки базы.
Принимаем форму в submit.php
Endpoint работает на том же origin, что и страница, и принимает только POST с JSON. Мы не используем cookie-сессию и не включаем CORS для чужих сайтов. Авторизация каждого запроса основана на подписанном initData. Это bearer-данные на ограниченное время: не пишите их в логи и не передавайте в URL.
<?php
declare(strict_types=1);
require dirname(__DIR__).'/app.php';
function respond(int $status, array $body): never
{
http_response_code($status);
header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');
echo json_encode($body, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
exit;
}
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
header('Allow: POST');
respond(405, ['error' => 'Используйте POST']);
}
if (strtolower(trim(explode(';', $_SERVER['CONTENT_TYPE'] ?? '')[0])) !== 'application/json') {
respond(415, ['error' => 'Ожидается JSON']);
}
$raw = file_get_contents('php://input', false, null, 0, 16385);
if ($raw === false || strlen($raw) > 16384) {
respond(413, ['error' => 'Запрос слишком большой']);
}
try {
$data = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
if (!is_array($data)) {
throw new InvalidArgumentException('Некорректная форма');
}
foreach (['initData', 'requestId', 'name', 'question'] as $key) {
if (!is_string($data[$key] ?? null)) {
throw new InvalidArgumentException('Заполните поля формы');
}
}
$userId = validateInitData($data['initData'], botToken(), time());
$name = trim($data['name']);
$question = trim($data['question']);
if (!preg_match('/^[a-f0-9-]{36}$/D', $data['requestId'])
|| mb_strlen($name) < 1 || mb_strlen($name) > 80
|| mb_strlen($question) < 1 || mb_strlen($question) > 1000) {
throw new InvalidArgumentException('Имя: 1–80 знаков; вопрос: 1–1000');
}
$db = database();
$saved = saveLead($db, $userId, $data['requestId'], $name, $question);
$lead = $saved['lead'];
$notification = $lead['notification'];
if ($saved['created']) {
$notification = notifyLead($userId, (int) $lead['id']);
$query = $db->prepare('UPDATE leads SET notification = ? WHERE id = ?');
$query->execute([$notification, $lead['id']]);
}
respond(200, ['saved' => true, 'id' => (int) $lead['id'], 'notification' => $notification]);
} catch (DomainException) {
respond(401, ['error' => 'Переоткройте приложение из Telegram']);
} catch (JsonException|InvalidArgumentException $error) {
respond(422, ['error' => 'Проверьте поля и формат запроса']);
} catch (LogicException) {
respond(409, ['error' => 'Эта отправка уже сохранена с другими полями. Начните новую заявку']);
} catch (Throwable) {
// Do not log the token, initData or the user's form here.
error_log('Mini App submit failed; inspect private application monitoring');
respond(500, ['error' => 'Не удалось подтвердить результат. Повторите те же данные']);
}
При повторе отправка сообщения не выполняется: используется сохранённый notification. Статус sent означает успешный ответ Bot API; rejected — явный отказ Telegram; unknown — исход не удалось надёжно определить. pending может остаться, если процесс завершился между сохранением и обновлением статуса.
Сам факт заявки уже сохранён перед вызовом sendMessage. Потеря ответа Telegram не откатывает её. В учебном примере нет автоматической повторной отправки уведомлений: иначе неизвестный результат мог бы породить дубль в чате. Для рабочего сервиса перенесите уведомления в outbox и worker с отдельным учётом исхода; граница между БД и Telegram всё равно не даёт exactly-once.
Создаём страницу и отправляем данные через fetch
Сохраните страницу как public/index.html. Скрипт Telegram подключается перед нашим кодом. Форма остаётся открытой до серверного ответа; сообщения выводятся через textContent. Если страницу открыли напрямую в браузере без initData, отправка недоступна: подставлять фиктивный Telegram ID нельзя.
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Заявка на консультацию</title>
<script src="https://telegram.org/js/telegram-web-app.js?64"></script>
<style>
* { box-sizing: border-box; }
body { margin: 0; padding: 20px; font: 16px/1.5 system-ui;
color: var(--tg-theme-text-color, #17212b);
background: var(--tg-theme-bg-color, #fff); }
main { max-width: 520px; margin: auto; }
label { display: block; margin: 16px 0; }
input, textarea, button { font: inherit; width: 100%; padding: 12px; }
input, textarea { color: inherit; background: inherit;
border: 1px solid #888; border-radius: 8px; }
button { border: 0; border-radius: 8px; margin-top: 12px;
color: var(--tg-theme-button-text-color, #fff);
background: var(--tg-theme-button-color, #246bce); }
button:disabled { opacity: .55; }
#status { overflow-wrap: anywhere; }
</style>
</head>
<body>
<main>
<h1>Заявка на консультацию</h1>
<form id="lead">
<label>Как к вам обращаться
<input name="name" required maxlength="80" autocomplete="name">
</label>
<label>Ваш вопрос
<textarea name="question" required maxlength="1000" rows="5"></textarea>
</label>
<p>Имя и вопрос будут сохранены для обработки обращения сервисным центром.
Не указывайте пароли и платёжные данные.</p>
<button id="send" type="submit" disabled>Отправить заявку</button>
</form>
<p id="status" role="status" aria-live="polite"></p>
<button id="new" type="button" hidden>Новая заявка</button>
</main>
<script>
const app = window.Telegram && window.Telegram.WebApp;
const form = document.getElementById('lead');
const send = document.getElementById('send');
const status = document.getElementById('status');
const next = document.getElementById('new');
let requestId;
try {
requestId = sessionStorage.getItem('leadRequestId') || crypto.randomUUID();
sessionStorage.setItem('leadRequestId', requestId);
if (!app || !app.initData) throw new Error('Open from Telegram');
app.ready();
app.expand();
send.disabled = false;
} catch (error) {
status.textContent = 'Откройте форму из меню бота в актуальном Telegram.';
}
form.addEventListener('submit', async (event) => {
event.preventDefault();
if (!app || !app.initData || !requestId || send.disabled) return;
send.disabled = true;
next.hidden = true;
status.textContent = 'Сохраняем заявку…';
let saved = false;
try {
const fields = new FormData(form);
const response = await fetch('submit.php', {
method: 'POST', credentials: 'omit',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({initData: app.initData, requestId,
name: fields.get('name'), question: fields.get('question')})
});
const result = await response.json();
if (!response.ok || result.saved !== true) {
if (response.status === 409) next.hidden = false;
throw new Error(result.error || 'Не удалось подтвердить сохранение');
}
saved = true;
status.textContent = 'Заявка №' + result.id + ' сохранена.' +
(result.notification === 'sent' ? ' Подтверждение отправлено в чат.' :
' Отправка подтверждения в чат не подтверждена; заявка уже в базе.');
next.hidden = false;
} catch (error) {
status.textContent = error instanceof Error ? error.message : 'Ошибка связи';
status.textContent += ' При повторе сохраните те же значения полей.';
} finally {
send.disabled = saved;
}
});
next.addEventListener('click', () => {
requestId = crypto.randomUUID();
sessionStorage.setItem('leadRequestId', requestId);
form.reset();
status.textContent = '';
next.hidden = true;
send.disabled = false;
});
</script>
</body>
</html>
requestId сохраняется в sessionStorage этого окна, чтобы повторить операцию после потери ответа, в том числе после перезагрузки страницы. Сами поля в браузерном хранилище не сохраняются: после перезагрузки их нужно заполнить теми же значениями, если отправка уже могла дойти. Новую операцию начинайте кнопкой «Новая заявка» после подтверждения предыдущей либо при конфликте полей. Новое открытие приложения может получить другой requestId — это не пожизненная защита от всех одинаковых обращений.
Отключение кнопки защищает только от случайного двойного клика. Настоящая защита от повтора находится в уникальном ключе БД. Ограничьте размер тела и частоту запросов также на веб-сервере; для рабочего проекта добавьте лимит по проверенному user_id. Подписанный пользователь всё ещё может создавать много новых requestId.
Подключаем кнопку меню к боту
Разместите public на своём HTTPS-домене, например https://mini.example.com/. Проверка адреса должна открывать форму без ошибок сертификата. Затем создайте setup-menu.php и задайте APP_URL в окружении CLI. Скрипт меняет кнопку меню по умолчанию для личных чатов тестового бота, не отправляя сообщения пользователям.
<?php
declare(strict_types=1);
if (PHP_SAPI !== 'cli') {
http_response_code(404);
exit;
}
require __DIR__.'/app.php';
$url = getenv('APP_URL');
if (!is_string($url) || !filter_var($url, FILTER_VALIDATE_URL)
|| parse_url($url, PHP_URL_SCHEME) !== 'https') {
throw new RuntimeException('Set an HTTPS APP_URL');
}
telegram('setChatMenuButton', ['menu_button' => [
'type' => 'web_app', 'text' => 'Оставить заявку',
'web_app' => ['url' => $url],
]]);
echo "Menu button configured\n";
php setup-menu.php
Для запуска через эту кнопку достаточно setChatMenuButton; настройка Main Mini App и ссылок startapp — отдельные способы открытия. Если для конкретного личного чата уже назначена собственная кнопка меню, она может перекрыть общую: проверьте getChatMenuButton для этого чата и при необходимости верните type=default либо настройте его отдельно. Не заменяйте рабочее меню чужого бота ради эксперимента.
Проверяем форму и сбои по шагам
Откройте приложение из личного чата бота и отправьте тестовый вопрос. Должны появиться номер заявки, строка в SQLite и, если отправка доступна, подтверждение в чате.
Откройте тот же URL вне Telegram. Кнопка отправки останется недоступной; серверный запрос без подписи также должен быть отклонён.
В изолированной проверке измените user.id внутри initData, не пересчитывая hash. Сервер должен вернуть 401, не создавая строку.
Проверьте старый auth_date: потребуется переоткрыть приложение. Не убирайте проверку срока ради прохождения теста.
Повторите POST с теми же initData, requestId и полями. Должен вернуться прежний номер без второго sendMessage.
Повторите requestId с изменённым вопросом. Ожидается 409 без изменения первой записи.
Смоделируйте недоступность Telegram после записи. Форма должна подтвердить сохранение и отдельно показать, что отправка сообщения не подтверждена.
Откройте форму на телефоне и компьютере, проверьте тёмную тему, экранную клавиатуру и длинный вопрос.
Это законченный учебный путь одной формы, а не CRM: списка заявок для менеджера, резервного копирования, автоматической повторной доставки и удаления данных по сроку здесь нет. Перед приёмом реальных обращений добавьте эти возможности по своим требованиям, разместите сведения о получателе данных и политику обработки. Не собирайте дополнительные поля «на будущее».
Где в этой схеме применяется BotGate
Пример выше вызывает Telegram напрямую. Если в проекте уже используется BotGate, исходящие setChatMenuButton и sendMessage можно выполнять настроенным серверным клиентом по документации API. Обновите также разбор ошибок под выбранный клиент, не меняя сохранение формы.
Проверка подписи initData выполняется именно с Telegram-токеном этого бота, а не с API-ключом BotGate и не с webhook_secret. Поэтому серверу формы нужен защищённый доступ к токену даже при отправке сообщений через шлюз. В браузере его быть не должно. BotGate не размещает HTML-страницу и не проверяет поля формы вместо вашего PHP endpoint.
Официальная документация
Telegram Mini Apps — подключение JavaScript и способы запуска.
Проверка initData — подпись и auth_date.
setChatMenuButton и sendMessage — меню и подтверждение.
hash_hmac, hash_equals и подготовленные запросы PDO — функции PHP из примера.