Перейти к содержанию
15 минут чтения
Тема: Практика PHP · Анкеты · Состояние диалога

Как сделать пошаговую анкету в Telegram-боте на PHP

Для примера сделаем анкету для заявки на консультацию: бот спросит имя, описание задачи и попросит подтвердить отправку. Если пользователь отвлечётся или Telegram повторно доставит обновление, приложение должно сохранить понятное состояние диалога и не создать вторую заявку.

Как будет устроен диалог

Пользователь открывает личный чат и вводит /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 · form.php
<?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.

SQL · schema.sql
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 · store-form.php
<?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.

Документация