Как будет устроен диалог
Пользователь открывает личный чат и вводит /form. Дальше идут три шага: name → task → confirm. Команда /back возвращает к предыдущему полю, /cancel удаляет незавершённую анкету, /confirm создаёт заявку только на экране подтверждения. После завершения новую анкету можно начать отдельной командой /form.
Для компактного примера нужны PHP 8.2+ на 64-битной системе, mbstring, PDO SQLite и уже настроенный приём обновлений. Код ниже — обработчик текстовой анкеты и её хранилище. Приём HTTP, проверка подлинности webhook и worker отправки сообщений подключаются в вашем приложении отдельно.
Состояние принадлежит сочетанию bot_id, chat_id и user_id. Обычная переменная PHP исчезнет в конце запроса, а PHP-сессия браузера не связывает обновления Telegram. Поэтому шаг и введённые ответы сохраняем в БД. Для более общего сценария меню сначала пригодится руководство по боту для бизнеса.
ForceReply может упростить ввод ответа, но не хранит шаг анкеты и не проверяет данные. В этом примере используем обычные текстовые сообщения, без зависимости от клавиатуры.
Проверяем ответы и меняем шаг
Вынесем переходы в функцию formStep. Она не обращается к Telegram или БД: получает текущее состояние и текст, возвращает новое состояние, сообщение пользователю и, только после подтверждения, данные заявки. Так правила анкеты можно проверять отдельно от сети.
<?php
declare(strict_types=1);
function formStep(array $state, ?string $text, int $now): array
{
$text = $text === null ? null : trim($text);
$reply = static fn(array $s, string $message, ?array $application = null)
=> ['state' => $s, 'text' => $message, 'application' => $application];
if ($text === '/form') {
return $reply(['step' => 'name', 'expires_at' => $now + 1800],
'Как к вам обращаться? /cancel — отмена.');
}
if ($text === '/cancel') {
return $reply(['step' => 'idle'], 'Анкета отменена. Начать заново: /form.');
}
$step = $state['step'] ?? 'idle';
if (in_array($step, ['idle', 'done'], true)) {
return $reply($state, 'Чтобы заполнить новую анкету, отправьте /form.');
}
if (($state['expires_at'] ?? 0) <= $now) {
return $reply(['step' => 'idle'], 'Время заполнения истекло. Начните с /form.');
}
if ($text === '/back') {
if ($step === 'confirm') {
unset($state['task']);
$state['step'] = 'task';
return $reply($state, 'Опишите задачу заново: от 10 до 1000 символов.');
}
unset($state['name'], $state['task']);
$state['step'] = 'name';
return $reply($state, 'Как к вам обращаться?');
}
if ($text === null || $text === '') {
return $reply($state, 'На этом шаге нужен текст. /back — назад, /cancel — отмена.');
}
if (str_starts_with($text, '/') && !($step === 'confirm' && $text === '/confirm')) {
return $reply($state, 'Используйте /back, /cancel или ответьте на текущий вопрос.');
}
if ($step === 'name') {
if (mb_strlen($text, 'UTF-8') > 80) {
return $reply($state, 'Сократите имя до 80 символов.');
}
$state['name'] = $text;
$state['step'] = 'task';
return $reply($state, 'Опишите задачу: от 10 до 1000 символов. /back — назад.');
}
if ($step === 'task') {
$length = mb_strlen($text, 'UTF-8');
if ($length < 10 || $length > 1000) {
return $reply($state, 'Нужно от 10 до 1000 символов. Уточните описание.');
}
$state['task'] = $text;
$state['step'] = 'confirm';
return $reply($state, "Имя: {$state['name']}\nЗадача: {$text}\n\n"
. '/confirm — отправить, /back — изменить, /cancel — отменить.');
}
if ($step === 'confirm' && $text === '/confirm') {
return $reply(['step' => 'done'], 'Заявка сохранена. Спасибо!',
['name' => $state['name'], 'task' => $state['task']]);
}
return $reply($state, 'Проверьте данные и отправьте /confirm или /back.');
}
Здесь 30 минут отсчитываются от начала анкеты и не продлеваются каждым сообщением. Это наше правило, его можно изменить. Просроченный черновик сбрасывается при следующем обновлении; для пользователей, которые больше не напишут, нужна периодическая очистка. После отмены или успешного подтверждения черновые ответы сразу удаляются из состояния. Срок хранения заявок и исходящих сообщений, где тоже есть введённые данные, задайте отдельно.
Текст отправляется без parse_mode. Поэтому имя «Анна <дизайн>» останется обычным текстом и не сломает HTML-разметку. Изображение или контакт не будут молча превращены в ответ: для них функция получит null и повторит подсказку.
Храним состояние, заявку и ответ одной транзакцией
Для примера используем отдельный SQLite-файл вне публичного каталога. Выполните эту схему один раз при подготовке приложения. Не создавайте таблицы на каждом webhook. В MySQL или PostgreSQL сохраните ту же атомарность, но используйте соответствующие блокировки и синтаксис upsert.
CREATE TABLE form_states (
bot_id TEXT NOT NULL,
chat_id INTEGER NOT NULL,
user_id INTEGER NOT NULL,
state_json TEXT NOT NULL,
PRIMARY KEY (bot_id, chat_id, user_id)
);
CREATE TABLE form_events (
bot_id TEXT NOT NULL,
update_id INTEGER NOT NULL,
PRIMARY KEY (bot_id, update_id)
);
CREATE TABLE applications (
bot_id TEXT NOT NULL,
update_id INTEGER NOT NULL,
chat_id INTEGER NOT NULL,
user_id INTEGER NOT NULL,
data_json TEXT NOT NULL,
PRIMARY KEY (bot_id, update_id)
);
CREATE TABLE form_outbox (
bot_id TEXT NOT NULL,
update_id INTEGER NOT NULL,
payload_json TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
PRIMARY KEY (bot_id, update_id)
);
Следующая функция вызывается после проверки подлинности входящего события. $botId берётся из доверенной настройки маршрута, а не из произвольного поля тела запроса. Она принимает только обычное message в личном чате; edited_message и callback_query этот пример не обрабатывает.
<?php
declare(strict_types=1);
require_once __DIR__ . '/form.php';
function applyFormUpdate(PDO $db, string $botId, array $update, int $now): bool
{
$m = $update['message'] ?? null;
if (!is_array($m) || ($m['chat']['type'] ?? null) !== 'private'
|| !is_int($update['update_id'] ?? null)
|| !is_int($m['chat']['id'] ?? null)
|| !is_int($m['from']['id'] ?? null)
|| $m['chat']['id'] !== $m['from']['id']
|| ($m['from']['is_bot'] ?? false)) {
return false;
}
$chatId = $m['chat']['id'];
$userId = $m['from']['id'];
$updateId = $update['update_id'];
$json = static fn(array $value): string => json_encode(
$value, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
);
// SQLite: блокировка записи получается до чтения состояния.
$db->exec('BEGIN IMMEDIATE');
try {
$seen = $db->prepare('INSERT INTO form_events VALUES (?, ?)
ON CONFLICT (bot_id, update_id) DO NOTHING');
$seen->execute([$botId, $updateId]);
if ($seen->rowCount() === 0) {
$db->exec('COMMIT');
return false;
}
$read = $db->prepare('SELECT state_json FROM form_states
WHERE bot_id = ? AND chat_id = ? AND user_id = ?');
$read->execute([$botId, $chatId, $userId]);
$stored = $read->fetchColumn();
$state = $stored === false ? [] : json_decode($stored, true, 32, JSON_THROW_ON_ERROR);
$result = formStep($state, is_string($m['text'] ?? null) ? $m['text'] : null, $now);
$db->prepare('INSERT INTO form_states VALUES (?, ?, ?, ?)
ON CONFLICT (bot_id, chat_id, user_id)
DO UPDATE SET state_json = excluded.state_json')
->execute([$botId, $chatId, $userId, $json($result['state'])]);
if ($result['application'] !== null) {
$db->prepare('INSERT INTO applications VALUES (?, ?, ?, ?, ?)')
->execute([$botId, $updateId, $chatId, $userId, $json($result['application'])]);
}
$db->prepare('INSERT INTO form_outbox (bot_id, update_id, payload_json)
VALUES (?, ?, ?)')->execute([$botId, $updateId, $json([
'chat_id' => $chatId, 'text' => $result['text'],
])]);
$db->exec('COMMIT');
return true;
} catch (Throwable $e) {
$db->exec('ROLLBACK');
throw $e;
}
}
Подключение PDO должно использовать PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION; задайте busy_timeout, например 5000 мс. Ошибка сохранения должна привести к неуспешной обработке webhook или повтору из вашего надёжного inbox. Возвращать HTTP 200 до сохранения события нельзя.
BEGIN IMMEDIATE исключает одновременное изменение состояния двумя писателями SQLite. Уникальность (bot_id, update_id) отсеивает повтор одного обновления. Это не сортировка: обрабатывайте входящие сообщения последовательно для каждого диалога, а сохранённый inbox — в порядке update_id. Для сценария, чувствительного к запоздалым ответам, храните message_id текущего вопроса и проверяйте reply_to_message; в этом компактном варианте такой проверки нет.
Отправляем подсказку после сохранения
form_outbox хранит намерение отправить ответ. Отдельный worker атомарно переводит запись pending → sending, вызывает sendMessage с payload_json и после успешного ответа сохраняет sent и message_id. Отправку не следует держать внутри транзакции анкеты: сеть может зависнуть, пока БД удерживает блокировку.
Если Telegram вернул подтверждённый 429, назначьте ограниченный отложенный повтор. Если соединение оборвалось после отправки, результат неизвестен: пометьте запись unknown и не отправляйте её автоматически заново. После аварии worker оставшиеся sending требуют такого же разбора. Заявка уже может быть сохранена, даже если пользователь ещё не увидел подтверждение.
В схеме выше показан минимальный payload и статус. Поля message_id, next_attempt_at, число попыток и время захвата добавляются при реализации worker. Полный транспорт доставки не входит в этот пример. Разницу между повторным webhook и повторной отправкой разбираем в статье о дублях сообщений.
Проверяем анкету до запуска
Пройдите /form → имя → описание → /confirm. В applications должна появиться одна запись, а состояние стать done.
Повторите тот же update_id и отдельно пришлите новый /confirm: второй заявки не должно быть в обоих случаях.
Введите слишком длинное имя, короткое описание и отправьте фото. Бот должен остаться на текущем шаге.
Проверьте /back с экрана подтверждения, затем /cancel. Старые значения не должны попасть в новую анкету.
Обработайте обновления двух пользователей и двух ботов: их состояния не должны смешиваться.
Сымитируйте ошибку вставки в outbox. Транзакция должна откатить событие, состояние и заявку, чтобы повтор мог обработать всё заново.
Проверка с фиктивными update выявляет ошибки переходов и транзакций. Перед запуском отдельно проверьте настоящий webhook и ответы в тестовом личном чате. Не используйте заявки реальных клиентов для отладки.
Если обновления приходят через BotGate
Логика formStep и ключи состояния остаются теми же. Входящий запрос BotGate проверяется по X-BotGate-Signature: HMAC вычисляется по исходным байтам тела. Это другая схема, чем заголовок X-Telegram-Bot-Api-Secret-Token прямого webhook Telegram. Настройку смотрите в документации webhook.
Исходящий worker может вызывать $client->bot($publicId)->call('sendMessage', $payload). Если повторами управляет worker, создайте Config с maxRetries: 0. Сам BotGate не хранит шаг вашей анкеты и не заменяет транзакцию в приложении. Установку клиента и проверку подписи показывает руководство по PHP SDK.