Перейти к содержанию
34 минуты чтения
Тема: Практика Laravel · Обучение · Прогресс

Как сделать обучающий мини-курс через Telegram-бота

Для примера соберём небольшой курс об основах Telegram-ботов: пять коротких занятий и проверочный вопрос после каждого. Бот сохранит результат, откроет следующий урок после правильного ответа и паузы в 24 часа, поможет продолжить после перерыва и позволит отключить напоминания. Реализуем весь цикл на PHP и Laravel, включая обработку старых кнопок и повторов.

Опишите, что считается прохождением урока

Получить сообщение, прочитать материал и выполнить задание — разные события. Telegram не даёт этому учебному боту надёжного доказательства прочтения. Поэтому completed увеличивается только после правильного ответа на вопрос текущего урока. Отправка текста и нажатие «Продолжить» сами по себе не засчитывают занятие.

Пять уроков курса: первый пройден, второй открыт, остальные закрыты. Отключение напоминаний сохраняет прогресс.
Пять уроков курса: первый пройден, второй открыт, остальные закрыты. Отключение напоминаний сохраняет прогресс.
Поясняющая схема курса из примера: первый урок завершён, второй открыт. Переход требует правильного ответа и паузы в 24 часа.

У каждого урока есть два варианта ответа. Это простая автоматическая проверка, а не оценка свободного текста: участник может ошибиться и попробовать снова. Для курса с эссе, фотографиями или проверкой наставником понадобятся отдельные состояния submitted и reviewed, очередь проверки и понятные сроки ответа. Не подменяйте такую проверку кнопкой «Я всё сделал», если обещаете оценку задания.

Условие

Поведение

Первый /start

Открывается урок 1, напоминания выключены

Неверный ответ

Тот же урок и возможность повторить

Верный ответ на урок 1–4

Результат сохраняется; следующий урок доступен через 24 часа

Возвращение спустя неделю

/continue показывает актуальный этап без сброса

/stop

Выключает напоминания, сохраняя курс и ответы

Верный ответ на урок 5

Курс завершён, новые напоминания не планируются

Пауза отсчитывается от верного ответа, а не от регистрации и не от полуночи. Это ровно 86 400 секунд в UTC: смена часового пояса или переход на летнее время не меняют условие. Время отправки «каждый день в 10:00 по местному времени» — другая задача; её стоит строить с явным часовым поясом и настройками уведомлений.

Подготовьте отдельного бота и приложение

Пример рассчитан на PHP 8.3+ в 64-битной среде и Laravel 13. Нужны Composer, HTTPS, база данных и постоянно работающий отправитель. Для тестового курса используем SQLite через pdo_sqlite; содержимое базы должно сохраняться между запусками. Статический массив в PHP хранит материалы, а не прогресс пользователей.

Bash · новый учебный проект
composer create-project "laravel/laravel:^13.0" course-bot
cd course-bot

Создайте отдельного бота в BotFather и настройте .env. База SQLite и .env не должны находиться в public. BOT_WEBHOOK_SECRET сгенерируйте случайно, например из 32 случайных байтов в hex; обозначения ниже нужно заменить своими значениями.

ENV · дополнение .env
APP_URL=https://course-bot.example.com
APP_DEBUG=false
BOT_TOKEN=TOKEN_FROM_BOTFATHER
BOT_WEBHOOK_SECRET=RANDOM_SECRET_GENERATED_FOR_THIS_BOT
PHP · config/guidebot.php
<?php

declare(strict_types=1);
return ['token' => env('BOT_TOKEN'), 'secret' => env('BOT_WEBHOOK_SECRET')];

Создайте app/GuideBot для Event, Lessons, Dialogue, Outbox, Telegram и Webhook, а app/Console/Commands — для Deliver, Remind и SetupWebhook. Ниже даны все эти файлы. Пример самостоятельный: код языкового бота из соседней статьи устанавливать не требуется. У двух учебных приложений совпадают имена классов и таблиц, поэтому не копируйте оба набора в один проект без объединения схемы.

Храните прогресс отдельно от доставки сообщений

PHP · database/migrations/2026_11_20_000001_create_course_bot_tables.php
<?php

declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class () extends Migration {
    public function up(): void
    {
        Schema::create('demo_users', function (Blueprint $t): void {
            $t->bigInteger('chat_id')->primary();
            $t->unsignedInteger('course_version')->default(1);
            $t->unsignedInteger('completed')->default(0);
            $t->unsignedInteger('active_lesson')->default(0);
            $t->bigInteger('available_at')->default(0);
            $t->boolean('reminders')->default(false);
            $t->bigInteger('reminder_due')->nullable();
            $t->unsignedInteger('revision')->default(0);
            $t->index(['reminders', 'reminder_due']);
        });
        Schema::create('demo_answers', function (Blueprint $t): void {
            $t->id();
            $t->bigInteger('chat_id');
            $t->unsignedInteger('lesson');
            $t->string('choice', 1);
            $t->bigInteger('answered_at');
            $t->unique(['chat_id', 'lesson']);
        });
        Schema::create('demo_updates', fn (Blueprint $t) => $t->bigInteger('update_id')->primary());
        Schema::create('demo_outbox', function (Blueprint $t): void {
            $t->id();
            $t->bigInteger('chat_id');
            $t->string('event_key')->unique();
            $t->text('payload');
            $t->string('kind');
            $t->unsignedInteger('revision')->default(0);
            $t->string('state');
            $t->unsignedInteger('attempts');
            $t->bigInteger('next_at');
            $t->bigInteger('message_id')->nullable();
            $t->integer('error_code')->nullable();
            $t->index(['state', 'next_at']);
        });
    }
    public function down(): void
    {
        Schema::dropIfExists('demo_outbox');
        Schema::dropIfExists('demo_updates');
        Schema::dropIfExists('demo_answers');
        Schema::dropIfExists('demo_users');
    }
};

completed — число успешно выполненных занятий, active_lesson — открытый урок с незавершённым заданием, ноль означает ожидание следующего открытия. available_at хранит Unix-время разрешённого перехода. Например, completed=2 и active_lesson=3 означает, что первые два занятия пройдены, третье выдано, но ещё не засчитано.

demo_answers хранит успешные ответы: уникальная пара chat_id + lesson дополнительно запрещает повторно засчитать урок. Неверные попытки здесь не сохраняются; если преподавателю нужна статистика ошибок, добавьте отдельную таблицу попыток, не меняя смысл completed. demo_updates защищает обработку повторно пришедшего Telegram Update.

revision увеличивается при изменении этапа или предпочтения напоминаний. Напоминание запоминает эту версию, и отправитель перед запросом проверяет её снова. Поэтому сообщение о старом уроке, которое долго лежало в очереди, можно отменить. Это не мешает отправлять обычные ответы на команды.

course_version=1 относится ко всему учебному сценарию. Не меняйте местами уроки и правильные ответы v1 после начала обучения: старая кнопка содержит тот же номер. Для содержательной переработки нужен v2, отдельное сопоставление прогресса и явное решение, что делать с уже зачисленными учениками. В этой статье у всех пользователей одна неизменяемая версия.

Задайте пять занятий с проверяемыми заданиями

PHP · app/GuideBot/Lessons.php
<?php

declare(strict_types=1);

namespace App\GuideBot;

final class Lessons
{
    /** @return array<int, array{title:string, body:string, question:string, options:array<string,string>, correct:string}> */
    public static function all(): array
    {
        return [
            1 => [
                'title' => 'Токен и первый запуск',
                'body' => 'Токен выдаёт BotFather. Он разрешает обращаться к API от имени бота, поэтому его хранят в закрытом окружении сервера. Пользователь сам открывает личный чат и нажимает Start. Бот не получает право написать любому человеку по известному username.',
                'question' => 'Задание: выберите место хранения токена.',
                'options' => ['a' => 'JavaScript страницы', 'b' => 'Закрытое окружение сервера'], 'correct' => 'b',
            ],
            2 => [
                'title' => 'Получение событий',
                'body' => 'Webhook — HTTPS-адрес вашего приложения, куда Telegram отправляет Update. Проверяйте секретный заголовок до обработки. Успешный HTTP-ответ подтверждает приём события, поэтому важные данные надо сохранить до ответа. Сетевую отправку сообщений можно выполнить отдельно.',
                'question' => 'Задание: что сделать до ответа HTTP 200?',
                'options' => ['a' => 'Надёжно сохранить результат обработки', 'b' => 'Только записать сообщение в память'], 'correct' => 'a',
            ],
            3 => [
                'title' => 'Повторная доставка',
                'body' => 'Одно событие может поступить повторно. Уникальный update_id помогает не провести одну операцию дважды. Проверку события и изменение прогресса объединяют транзакцией. Случайный новый идентификатор при каждой попытке не позволяет распознать повтор.',
                'question' => 'Задание: какой ключ нужен для повтора одного Update?',
                'options' => ['a' => 'Новый UUID на каждый запрос', 'b' => 'Исходный update_id'], 'correct' => 'b',
            ],
            4 => [
                'title' => 'Доступ к данным',
                'body' => 'Кнопка может содержать номер заказа или урока, но этот номер не доказывает право доступа. Состояние выбирают для отправителя события и проверяют допустимость действия. В личном боте пользователь не должен менять чужой прогресс, подставив ID в callback_data.',
                'question' => 'Задание: откуда брать владельца прогресса?',
                'options' => ['a' => 'Из проверенного отправителя события', 'b' => 'Из user_id в тексте кнопки'], 'correct' => 'a',
            ],
            5 => [
                'title' => 'Неизвестный результат отправки',
                'body' => 'При подтверждённом ответе 429 повтор планируют после retry_after. При таймауте ответ мог потеряться уже после отправки сообщения. Такой исход требует отдельного состояния и проверки: слепой повтор способен создать дубль. Отправка сообщения и запись в вашу БД не являются одной транзакцией.',
                'question' => 'Задание: что означает таймаут sendMessage?',
                'options' => ['a' => 'Сообщение точно не отправлено', 'b' => 'Результат может быть неизвестен'], 'correct' => 'b',
            ],
        ];
    }
}

Материал специально короткий и помещается в одно текстовое сообщение. В рабочем курсе занятие можно разделить на блоки, приложить документ или видео, а после него отправить вопрос. Успешная загрузка файла в Telegram не должна автоматически закрывать задание. Для длинных текстов учитывайте ограничения и разбиение сообщений.

В callback_data будет версия курса, номер урока и буква ответа. Идентификатор пользователя туда не входит: владельца определяет проверенный отправитель события. Правильный ответ хранится на сервере. Сам формат кнопки не считается доверенным — обработчик сверяет номер с реально открытым уроком и текущим completed.

Такой вопрос проверяет понимание конкретного положения из материала. Если нужна более серьёзная проверка знаний, расширьте банк вопросов и критерии, а не усложняйте транспорт. Для учебного примера два варианта позволяют воспроизвести правильный, неправильный и повторный ответ без дополнительных интерфейсов.

Реализуйте выдачу урока, ответ и продолжение

PHP · app/GuideBot/Dialogue.php
<?php

declare(strict_types=1);

namespace App\GuideBot;

use Illuminate\Support\Facades\DB;

final class Dialogue
{
    public function handle(Event $event): void
    {
        DB::table('demo_users')->insertOrIgnore(['chat_id' => $event->chatId]);
        $user = DB::table('demo_users')->where('chat_id', $event->chatId)->lockForUpdate()->first();
        if (!$user || (int) $user->course_version !== 1) {
            throw new \RuntimeException('Unsupported course version');
        }
        $action = $event->action;
        $text = 'Команды: /continue — урок, /progress — прогресс, /remind_on — включить напоминания, /stop — отключить их.';
        $buttons = $this->menu();
        if (in_array($action, ['/stop', '/remind_on'], true)) {
            $enabled = $action === '/remind_on';
            $this->change($user, ['reminders' => $enabled]);
            $text = $enabled ? 'Напоминания включены. Не более одного на текущий этап, не раньше чем через 24 часа.'
                : 'Напоминания отключены. Прогресс сохранён; /continue работает в любое время.';
        } elseif ($action === '/progress') {
            $text = 'Пройдено '.(int) $user->completed.' из 5. Напоминания: '.((bool) $user->reminders ? 'включены.' : 'отключены.');
        } elseif (in_array($action, ['/start', '/continue', 'course:v1:continue'], true)) {
            if ((int) $user->completed === 5) {
                $text = 'Курс завершён: 5 из 5. Поздравляем! Прогресс сохранён.';
            } elseif ((int) $user->active_lesson === 0 && now()->getTimestamp() < (int) $user->available_at) {
                $hours = (int) ceil(((int) $user->available_at - now()->getTimestamp()) / 3600);
                $text = 'Следующий урок ещё закрыт. Осталось не более '.$hours.' ч. Вернитесь через /continue.';
            } else {
                if ((int) $user->active_lesson === 0) {
                    $this->change($user, ['active_lesson' => (int) $user->completed + 1]);
                }
                [$text, $buttons] = $this->lesson((int) $user->active_lesson);
                if ($action === '/start') {
                    $text = "Курс из пяти занятий. Следующий урок — после верного ответа и паузы 24 часа. Напоминания включаются отдельно: /remind_on.\n\n".$text;
                }
            }
        } elseif ($event->callbackId !== null && preg_match('/^course:v1:answer:([1-5]):([ab])$/D', $action, $match)) {
            $lesson = (int) $match[1];
            $choice = $match[2];
            if ($lesson !== (int) $user->active_lesson || $lesson !== (int) $user->completed + 1) {
                $text = 'Этот ответ относится к другому или уже пройденному уроку. Нажмите «Продолжить».';
            } elseif (Lessons::all()[$lesson]['correct'] !== $choice) {
                [$text, $buttons] = $this->lesson($lesson);
                $text = "Пока неверно. Перечитайте объяснение и попробуйте снова.\n\n".$text;
            } else {
                DB::table('demo_answers')->insert([
                    'chat_id' => $event->chatId, 'lesson' => $lesson, 'choice' => $choice, 'answered_at' => now()->getTimestamp(),
                ]);
                $this->change($user, ['completed' => $lesson, 'active_lesson' => 0,
                    'available_at' => $lesson < 5 ? now()->getTimestamp() + 86400 : 0]);
                $text = $lesson === 5 ? 'Верно! Курс завершён: 5 из 5. Поздравляем!'
                    : 'Верно! Урок '.$lesson.' пройден. Следующий откроется через 24 часа. Используйте /continue.';
            }
        } elseif ($event->callbackId !== null) {
            $text = 'Эта кнопка не поддерживается. Откройте актуальный урок через /continue.';
        }
        Outbox::add($event->chatId, 'update:'.$event->updateId, ['text' => $text, 'reply_markup' => $buttons]);
    }

    /** @param array<string, int|bool> $fields */
    private function change(\stdClass $user, array $fields): void
    {
        foreach ($fields as $key => $value) {
            $user->{$key} = $value;
        }
        $user->revision = (int) $user->revision + 1;
        $user->reminder_due = (bool) $user->reminders && (int) $user->completed < 5
            ? max(now()->getTimestamp() + 86400, (int) $user->available_at) : null;
        DB::table('demo_users')->where('chat_id', $user->chat_id)->update($fields + [
            'revision' => $user->revision, 'reminder_due' => $user->reminder_due,
        ]);
        // Pending reminder rows are invalidated by revision, without locking them here.
    }

    /** @return array{string, array<string, mixed>} */
    private function lesson(int $number): array
    {
        $lesson = Lessons::all()[$number];
        $rows = [];
        foreach ($lesson['options'] as $choice => $label) {
            $rows[] = [['text' => $label, 'callback_data' => 'course:v1:answer:'.$number.':'.$choice]];
        }
        return ['Урок '.$number.'/5. '.$lesson['title']."\n\n".$lesson['body']."\n\n".$lesson['question'], ['inline_keyboard' => $rows]];
    }

    /** @return array<string, mixed> */
    private function menu(): array
    {
        return ['inline_keyboard' => [[['text' => 'Продолжить', 'callback_data' => 'course:v1:continue']]]];
    }

    public function remind(): void
    {
        $ids = DB::table('demo_users')->where('reminders', true)->where('completed', '<', 5)
            ->where('reminder_due', '<=', now()->getTimestamp())->orderBy('chat_id')->limit(100)->pluck('chat_id');
        foreach ($ids as $id) {
            DB::transaction(function () use ($id): void {
                $user = DB::table('demo_users')->where('chat_id', $id)->lockForUpdate()->first();
                if (!$user || !(bool) $user->reminders || (int) $user->completed >= 5
                    || $user->reminder_due === null || (int) $user->reminder_due > now()->getTimestamp()) {
                    return;
                }
                $text = (int) $user->active_lesson > 0
                    ? 'Вы остановились на уроке '.(int) $user->active_lesson.'. Продолжите, когда будет удобно. /stop отключит напоминания.'
                    : 'Следующий урок уже доступен. Нажмите «Продолжить». /stop отключит напоминания.';
                Outbox::add(
                    (int) $user->chat_id,
                    'reminder:'.$user->chat_id.':'.$user->revision,
                    ['text' => $text, 'reply_markup' => $this->menu()],
                    'reminder',
                    (int) $user->revision
                );
                DB::table('demo_users')->where('chat_id', $id)->update(['reminder_due' => null]);
            }, 3);
        }
    }

    public function canSend(\stdClass $row): bool
    {
        if ($row->kind !== 'reminder') {
            return true;
        }
        return DB::table('demo_users')->where('chat_id', $row->chat_id)->where('reminders', true)
            ->where('completed', '<', 5)->where('revision', $row->revision)->exists();
    }
}

Метод handle вызывается внутри транзакции webhook и блокирует строку ученика. Проверка допустимого шага, сохранение ответа, изменение completed и запись сообщения происходят вместе. Если операция откатится, повтор события не увидит наполовину пройденный урок. Код не делает внешних запросов, пока держит блокировку.

После правильного ответа active_lesson становится нулём. До available_at команда /continue возвращает оставшееся время, округлённое вверх до часа. После срока она открывает completed+1. Уже открытый урок можно запросить повторно в любое время: состояние не сбрасывается, а неполученное или потерявшееся в истории сообщение легко восстановить.

Старая кнопка урока 1 после перехода к уроку 2 не засчитает второй урок. Даже если Telegram прислал новое update_id на повторное нажатие, проверка active_lesson остановит действие. Дедупликация событий и проверка бизнес-состояния решают разные задачи, поэтому нужны обе.

Команда /start тоже продолжает существующий курс. Это сознательное решение: привычное повторное открытие бота не должно стирать результаты. Сброс курса для повторного прохождения потребовал бы отдельной команды с подтверждением, новой попытки обучения и ключей ответов, учитывающих эту попытку. В примере такой команды нет.

Если сообщение с уроком не доставилось, запись об открытии всё равно сохранится, но завершённым урок не станет. Пользователь запросит /continue и получит ту же карточку. Если потерялось подтверждение верного ответа, повтор не увеличит completed второй раз. /progress позволит проверить фактический результат.

Принимайте события только от нужного пользователя

Входящий webhook работает только с личными чатами. Идентификатор владельца берём из from.id и проверяем его совпадение с chat.id, а не читаем из callback_data. Сначала проверяем секретный заголовок, затем в одной транзакции отмечаем update_id, изменяем состояние и создаём ответ. При ошибке транзакция откатывается, успешного подтверждения нет: Telegram сможет повторить событие. Повтор уже сохранённого Update ничего не меняет.

PHP · app/GuideBot/Event.php
<?php

declare(strict_types=1);

namespace App\GuideBot;

final readonly class Event
{
    public function __construct(
        public int $updateId,
        public int $chatId,
        public string $action,
        public string $language,
        public ?string $callbackId,
    ) {
    }

    /** @param array<string, mixed> $update */
    public static function from(array $update): ?self
    {
        $callback = $update['callback_query'] ?? null;
        $message = is_array($callback) ? ($callback['message'] ?? null) : ($update['message'] ?? null);
        $from = is_array($callback) ? ($callback['from'] ?? null) : (is_array($message) ? ($message['from'] ?? null) : null);
        $chat = is_array($message) ? ($message['chat'] ?? null) : null;
        if (!is_array($from) || !is_array($chat) || ($chat['type'] ?? '') !== 'private'
            || !is_int($from['id'] ?? null) || $from['id'] <= 0 || ($chat['id'] ?? null) !== $from['id']
            || !is_int($update['update_id'] ?? null)) {
            return null;
        }
        $action = is_array($callback) ? ($callback['data'] ?? '') : ($message['text'] ?? '');
        $callbackId = is_array($callback) ? ($callback['id'] ?? null) : null;
        return new self(
            $update['update_id'],
            $from['id'],
            is_string($action) ? trim($action) : '',
            is_string($from['language_code'] ?? null) ? $from['language_code'] : '',
            is_string($callbackId) ? $callbackId : null
        );
    }
}
PHP · app/GuideBot/Webhook.php
<?php

declare(strict_types=1);

namespace App\GuideBot;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;

final class Webhook
{
    public function __invoke(Request $request, Dialogue $dialogue): JsonResponse
    {
        $secret = config('guidebot.secret');
        $provided = $request->header('X-Telegram-Bot-Api-Secret-Token');
        abort_unless(is_string($secret) && $secret !== ''
            && is_string($provided) && hash_equals($secret, $provided), 403);
        abort_if(strlen($request->getContent()) > 131072, 413);
        $update = $request->json()->all();
        $event = Event::from($update);
        if ($event === null) {
            return response()->json(['ok' => true]);
        }
        DB::transaction(function () use ($event, $dialogue): void {
            if (!DB::table('demo_updates')->insertOrIgnore(['update_id' => $event->updateId])) {
                return;
            }
            $dialogue->handle($event);
        }, 3);
        // Telegram executes this method after receiving the webhook response.
        // Its result is not available here; business replies use the outbox.
        return response()->json($event->callbackId === null ? ['ok' => true] : [
            'method' => 'answerCallbackQuery', 'callback_query_id' => $event->callbackId,
        ]);
    }
}
PHP · routes/api.php
<?php

declare(strict_types=1);
use App\GuideBot\Webhook;
use Illuminate\Support\Facades\Route;

Route::post('/telegram', Webhook::class);
PHP · добавьте api в существующий withRouting в bootstrap/app.php
->withRouting(
    web: __DIR__.'/../routes/web.php',
    api: __DIR__.'/../routes/api.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
)

Для кнопок возвращаем answerCallbackQuery прямо в JSON-ответе webhook, чтобы убрать индикатор ожидания. Это поддержанный Telegram способ вызова метода, но результат такого вызова приложению недоступен. Поэтому в нём нет важных подтверждений: они отправляются отдельными сообщениями через outbox. Если обработчик надолго зависнет, индикатор может остаться; не помещайте в транзакцию запросы к CRM или другим API. Ответ методом на webhook.

Webhook — отдельный API-маршрут без браузерной сессии; секретный заголовок заменяет здесь браузерный CSRF-токен, а не отменяет CSRF для сайта. Не отключайте защиту web-маршрутов целиком. Ограничение тела есть и в коде; на веб-сервере также нужен разумный лимит запроса. Не журналируйте BOT_TOKEN, весь URL Telegram или сырые заголовки. Для чтения таблиц используйте закрытый административный доступ.

Маршрут принимает только message и callback_query нужного формата. Группы и события без подходящего личного чата не участвуют в курсе. Для группового обучения понадобится другая модель: один чат уже не равен одному ученику, а сообщение с заданием может быть общим. Не переносите допущение chat_id=from.id в групповой бот.

Добавьте напоминания с явным включением и отменой

PHP · app/Console/Commands/Remind.php
<?php

declare(strict_types=1);

namespace App\Console\Commands;

use App\GuideBot\Dialogue;
use Illuminate\Console\Command;

final class Remind extends Command
{
    protected $signature = 'course:remind';
    protected $description = 'Queue due course reminders';
    public function handle(Dialogue $dialogue): int
    {
        $dialogue->remind();
        return self::SUCCESS;
    }
}
PHP · добавьте в routes/console.php
<?php

declare(strict_types=1);
use Illuminate\Support\Facades\Schedule;

Schedule::command('course:remind')->everyMinute()->withoutOverlapping();

Подписка на напоминания начинается только после /remind_on. Создание ученика, /start и правильный ответ её не включают. Сразу после включения ничего не отправляется: reminder_due ставится не раньше чем через 24 часа. На текущем этапе создаётся максимум одно напоминание; ежедневного преследования до ответа в этом примере нет.

Метод remind повторно проверяет срок под блокировкой пользователя, создаёт outbox с уникальным ключом и обнуляет reminder_due в той же транзакции. Повторный запуск планировщика не создаст вторую строку. После нового этапа появится другой revision и, если напоминания разрешены, новый срок.

Когда ученик нажал /stop, напоминание уже может находиться в outbox. Поэтому одной проверки в планировщике недостаточно: canSend проверяет preference, revision и незавершённость курса перед сетевым запросом. Устаревшая строка получает cancelled. При правильном ответе или открытии следующего урока старое напоминание отменяется тем же способом.

Остаётся небольшое окно гонки: /stop может прийти после проверки, когда запрос к Telegram уже начался. Один такой запрос ещё может завершиться; отозвать его из сети нельзя. Не обещайте мгновенное удаление уже отправленного уведомления. После подтверждённой остановки новые напоминания не планируются, а ожидающие отсеиваются при отправке.

Для этого курса напоминание только предлагает вернуться. Оно не открывает занятие и не меняет completed. Это сохраняет контроль за учеником: даже после месяца отсутствия бот не отправит пять уроков подряд и не покажет фиктивное завершение. Повторный /remind_on создаёт новую возможность напомнить через сутки, если человек сам попросил включить её снова. Планировщик Laravel.

Отправляйте сообщения с контролем повторов

Исходящие сообщения сохраняются в demo_outbox вместе с изменением состояния. Отдельная Artisan-команда читает эту таблицу и отправляет их. В примере это небольшая очередь в БД: Laravel queue:work её не обслуживает. Для учебной нагрузки запустите один bot:deliver --watch; при росте нагрузки понадобятся ограничения частоты и распределение работы между процессами. Здесь важнее увидеть границу между сохранением ответа и его доставкой.

PHP · app/GuideBot/Outbox.php
<?php

declare(strict_types=1);

namespace App\GuideBot;

use Illuminate\Support\Facades\DB;

final class Outbox
{
    /** @param array<string, mixed> $payload */
    public static function add(int $chatId, string $key, array $payload, string $kind = 'reply', int $revision = 0): void
    {
        DB::table('demo_outbox')->insertOrIgnore([
            'chat_id' => $chatId, 'event_key' => $key,
            'payload' => json_encode(['chat_id' => $chatId] + $payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),
            'kind' => $kind, 'revision' => $revision, 'state' => 'pending',
            'attempts' => 0, 'next_at' => now()->getTimestamp(),
        ]);
    }
}
PHP · app/GuideBot/Telegram.php
<?php

declare(strict_types=1);

namespace App\GuideBot;

use Illuminate\Support\Facades\Http;

final class Telegram
{
    /** @param array<string, mixed> $payload
     *  @return array{state:string, delay:int, message_id:?int, code:?int} */
    public function call(string $method, array $payload): array
    {
        $unknown = ['state' => 'unknown', 'delay' => 0, 'message_id' => null, 'code' => null];
        $token = config('guidebot.token');
        if (!is_string($token) || $token === '') {
            throw new \LogicException('BOT_TOKEN is missing');
        }
        try {
            $response = Http::connectTimeout(5)->timeout(20)
                ->post('https://api.telegram.org/bot'.$token.'/'.$method, $payload);
            $body = $response->json();
        } catch (\Throwable) {
            return $unknown;
        }
        if (!is_array($body) || $response->serverError()) {
            return $unknown;
        }
        $result = $body['result'] ?? null;
        $messageId = is_array($result) && is_int($result['message_id'] ?? null) ? $result['message_id'] : null;
        if ($response->successful() && ($body['ok'] ?? null) === true
            && ($method !== 'sendMessage' || $messageId !== null)) {
            return ['state' => 'sent', 'delay' => 0, 'message_id' => $messageId, 'code' => null];
        }
        $code = $body['error_code'] ?? null;
        $parameters = $body['parameters'] ?? null;
        $delay = is_array($parameters) ? ($parameters['retry_after'] ?? null) : null;
        if (($body['ok'] ?? null) === false && $code === 429 && is_int($delay) && $delay > 0) {
            return ['state' => 'retry', 'delay' => $delay, 'message_id' => null, 'code' => 429];
        }
        if (($body['ok'] ?? null) === false && is_int($code) && $code >= 400 && $code < 500) {
            return ['state' => 'failed', 'delay' => 0, 'message_id' => null, 'code' => $code];
        }
        return $unknown;
    }
}
PHP · app/Console/Commands/Deliver.php
<?php

declare(strict_types=1);

namespace App\Console\Commands;

use App\GuideBot\{Dialogue, Telegram};
use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;

final class Deliver extends Command
{
    protected $signature = 'bot:deliver {--watch}';
    protected $description = 'Deliver persisted demo messages';

    public function handle(Telegram $telegram, Dialogue $dialogue): int
    {
        do {
            $ids = DB::table('demo_outbox')->whereIn('state', ['pending', 'retry'])
                ->where('next_at', '<=', now()->getTimestamp())->orderBy('id')->limit(50)->pluck('id');
            foreach ($ids as $id) {
                $row = DB::transaction(function () use ($id, $dialogue): ?\stdClass {
                    $row = DB::table('demo_outbox')->where('id', $id)->lockForUpdate()->first();
                    if (!$row || !in_array($row->state, ['pending', 'retry'], true)
                        || (int) $row->next_at > now()->getTimestamp()) {
                        return null;
                    }
                    if (!$dialogue->canSend($row)) {
                        DB::table('demo_outbox')->where('id', $id)->update(['state' => 'cancelled']);
                        return null;
                    }
                    DB::table('demo_outbox')->where('id', $id)->update([
                        'state' => 'sending', 'attempts' => (int) $row->attempts + 1,
                    ]);
                    return $row;
                });
                if (!$row instanceof \stdClass) {
                    continue;
                }
                try {
                    /** @var array<string, mixed> $payload */
                    $payload = json_decode((string) $row->payload, true, 512, JSON_THROW_ON_ERROR);
                    $result = $telegram->call('sendMessage', $payload);
                } catch (\Throwable) {
                    $result = ['state' => 'unknown', 'delay' => 0, 'message_id' => null, 'code' => null];
                }
                if ($result['state'] === 'retry' && (int) $row->attempts + 1 >= 5) {
                    $result['state'] = 'failed';
                }
                DB::table('demo_outbox')->where('id', $id)->update([
                    'state' => $result['state'], 'next_at' => now()->getTimestamp() + $result['delay'],
                    'message_id' => $result['message_id'], 'error_code' => $result['code'],
                ]);
            }
            if ($this->option('watch')) {
                usleep(500000);
            }
        } while ($this->option('watch'));
        return self::SUCCESS;
    }
}

HTTP-клиент не вызывает retry(). Подтверждённый Telegram 429 переносит попытку на retry_after, максимум — пять попыток. Таймаут, 5xx или непонятное тело дают unknown: ответ мог потеряться после отправки. Статус sending после аварии процесса тоже требует проверки. Уникальный event_key предотвращает повторное создание строки, но не превращает Telegram и вашу БД в одну транзакцию. HTTP-клиент Laravel.

Ответы и напоминания используют одну таблицу, но только kind=reminder зависит от пользовательского разрешения. После /stop бот продолжает отвечать на /progress и /continue: отключение инициативных сообщений не делает курс недоступным. Для полного удаления аккаунта или блокировки общения нужна отдельная продуктовая операция.

Один исходящий процесс помогает сохранять порядок учебного диалога, однако отложенный retry может прийти позже более нового ответа. Поэтому каждая карточка содержит номер урока, а обработчик проверяет актуальное состояние. Не пытайтесь получить строгий порядок сообщений лишь сортировкой SELECT: для этого пришлось бы блокировать очередь конкретного чата до разрешения предыдущей операции.

Запустите webhook, отправитель и расписание

PHP · app/Console/Commands/SetupWebhook.php
<?php

declare(strict_types=1);

namespace App\Console\Commands;

use App\GuideBot\Telegram;
use Illuminate\Console\Command;

final class SetupWebhook extends Command
{
    protected $signature = 'bot:webhook';
    protected $description = 'Register this demo webhook';
    public function handle(Telegram $telegram): int
    {
        $url = config('app.url');
        $secret = config('guidebot.secret');
        if (!is_string($url) || !str_starts_with($url, 'https://') || !is_string($secret)
            || !preg_match('/^[A-Za-z0-9_-]{32,256}$/D', $secret)) {
            $this->error('Set HTTPS APP_URL and a random BOT_WEBHOOK_SECRET first.');
            return self::FAILURE;
        }
        $result = $telegram->call('setWebhook', [
            'url' => rtrim($url, '/').'/api/telegram', 'secret_token' => $secret,
            'allowed_updates' => ['message', 'callback_query'], 'max_connections' => 1,
        ]);
        $this->line($result['state']);
        return $result['state'] === 'sent' ? self::SUCCESS : self::FAILURE;
    }
}
Bash · первичный запуск в каталоге course-bot
php artisan migrate
php artisan route:list --path=api/telegram
php artisan bot:webhook
php artisan bot:deliver --watch

Первые команды создают таблицы и проверяют маршрут, bot:webhook регистрирует публичный HTTPS-адрес. sent означает подтверждённую регистрацию. Не используйте этот токен одновременно в другом приложении: у бота один текущий webhook. Отправитель оставьте работающим в отдельном терминале.

Bash · второй терминал для локальной проверки расписания
php artisan schedule:work

Для постоянной работы запускают отправитель через менеджер процессов и вызывают schedule:run каждую минуту. Ниже образец crontab именно учебного приложения; замените каталог своим. schedule:work и cron не нужно держать одновременно. withoutOverlapping требует исправного хранилища cache для блокировки, а защита от повторного напоминания дополнительно находится в БД.

Cron · пример пути, замените своим
* * * * * cd /var/www/course-bot && php artisan schedule:run >> /var/log/course-bot-schedule.log 2>&1

Это команды инфраструктуры отдельного курса, а не команды импорта статьи на сайт BotGate. В планировщике нет sendMessage: он только создаёт задания. Если cron работает, а bot:deliver остановлен, уроки и напоминания будут ждать в outbox. После возобновления устаревшие напоминания пройдут повторную проверку и отменятся.

Пройдите курс и проверьте прерванный сценарий

  • Отправьте /start: должен прийти урок 1. /progress покажет 0 из 5 и выключенные напоминания.

  • Выберите неверный ответ: получите объяснение и тот же вопрос. Прогресс останется нулевым.

  • Выберите верный ответ два раза. Урок засчитывается один раз, а повторное нажатие предлагает продолжить.

  • Сразу отправьте /continue: урок 2 закрыт. Через 24 часа эта команда открывает его.

  • Перезапустите приложение и запросите /continue: откроется прежний незавершённый урок, а не первый.

  • Включите напоминания, дождитесь формирования строки, остановите отправитель и отправьте /stop. После запуска отправителя напоминание должно стать cancelled.

  • Завершите пятый урок: completed=5, reminder_due=NULL, /start не сбрасывает результат.

В автоматической проверке подменяйте время через Carbon::setTestNow и HTTP через Http::fake, запрещая реальные сетевые запросы. Это позволяет проверить 24-часовую границу за секунды. В ручной тестовой копии также можно осторожно приблизить available_at и reminder_due для своего ученика; не ослабляйте проверки времени в рабочем коде ради ускорения опыта.

SQL · проверка своего учебного прогресса
SELECT chat_id, course_version, completed, active_lesson,
       available_at, reminders, reminder_due, revision
FROM demo_users
WHERE chat_id = 123456789;

SELECT lesson, choice, answered_at
FROM demo_answers
WHERE chat_id = 123456789
ORDER BY lesson;

123456789 здесь — вымышленный ID, замените его собственным тестовым chat_id. Набор ответов должен соответствовать completed: после второго урока ровно две успешные записи. Проверяйте также другого ученика: одинаковая кнопка у двух людей должна менять две независимые строки, а не общий счётчик курса.

SQL · состояние исходящих сообщений
SELECT id, chat_id, event_key, state, attempts, next_at, message_id, error_code
FROM demo_outbox
ORDER BY id DESC
LIMIT 20;

Если строки остаются pending, сначала проверьте процесс bot:deliver, его окружение и доступ к той же БД. retry с будущим next_at означает ожидание разрешённой попытки. failed с 403 обычно требует проверки доступности чата и отношений пользователя с ботом; повтор по таймеру здесь не поможет. В failed сохраняется код ошибки, но не сырое описание с возможными данными запроса. unknown и зависшее sending разбирайте отдельно по конкретной операции и чату.

После выяснения причины можно повторить конкретную строку: остановите отправитель, проверьте ID, payload и отсутствие уже полученного сообщения, затем верните только её в pending с attempts=0 и next_at=текущему Unix-времени. Если Telegram мог принять первый запрос, повтор способен создать дубль — это осознанное решение оператора. Не возвращайте массово все sending/unknown в очередь. Для уже доставленного сообщения сохраните подтверждённый message_id и состояние sent, затем возобновите отправитель.

Если нужно исправить прогресс ученика вручную, сначала разберите ответы и активную версию курса. Простое изменение completed без согласования active_lesson, available_at, demo_answers и revision оставит противоречивое состояние. Исправление следует выполнять отдельной административной операцией в транзакции с журналом причины; обычное продолжение обучения такой операции не требует.

Как расширить курс и где здесь BotGate

Для нескольких курсов добавьте course_id к зачислению, ответам, событиям и callback_data. Для повторного прохождения понадобится enrollment_id или номер попытки. Материалы можно перенести в таблицы и редактор, но опубликованные версии нужно сохранять: правка вопроса не должна задним числом менять смысл уже принятого ответа.

Вложения и проверка наставником расширяют модель задания. Платный доступ проверяют перед выдачей каждого урока, а не только перед первым /start. Сертификат создают после подтверждённого завершения с уникальным номером выдачи. Эти функции не реализованы в текущем примере; его результат — последовательный курс с автоматическим вопросом и сохраняемым прогрессом.

Если Telegram вызывается через BotGate, курс, время открытия и разрешения на напоминания остаются в вашем приложении. Меняется транспорт и проверка входящих событий по контракту BotGate. Прямой X-Telegram-Bot-Api-Secret-Token из этой статьи не является проверкой подписи webhook сервиса. Не подключайте тот же токен к двум конкурирующим получателям событий.

Для отправки через Laravel-пакет используйте руководство по интеграции и согласуйте один уровень повторов. BotGate не определяет, выполнил ли ученик задание, и не восстанавливает прогресс из истории чата: источником этих решений остаётся ваша БД.