Перейти к содержанию
13 минут чтения
Тема: Практика Laravel · Планировщик · Напоминания

Как отправлять напоминания о записи через Telegram-бота на Laravel

Для примера напомним клиенту о консультации за час до начала. Запись может перенестись или отмениться, а сервер — пропустить минуту запуска. Поэтому напоминание должно храниться в БД, проверять актуальную запись перед отправкой и отличать подтверждённый отказ Telegram от потерянного ответа.

Что хранить кроме даты отправки

Используем Laravel 12 с PHP 8.3+ и обычный Telegram Bot API через HTTP-клиент Laravel. Те же основные приёмы доступны в Laravel 13, который требует PHP 8.3+. Предполагается, что пользователь уже открыл личный чат с ботом и в приложении сохранён проверенный chat_id. Наличие номера телефона или username не позволяет боту начать личную переписку.

Для небольшого потока покажем отдельную Artisan-команду, которая раз в минуту выбирает до 20 готовых напоминаний. Она отправляет сообщения последовательно с ограниченным таймаутом. Если объём растёт, эту же логику можно вынести в задания очереди; правила проверки версии записи и результата отправки сохраняются.

В appointments нужны id, status (confirmed/cancelled), starts_at, timezone, version и telegram_chat_id. В appointment_reminders — id, appointment_id, appointment_version, due_at, state, attempts, telegram_message_id. Время starts_at и due_at храните в UTC; timezone содержит исходную зону IANA, например Europe/Moscow. Не используйте локальное время сервера как время клиента.

Ограничение UNIQUE(appointment_id, appointment_version) задаёт одно напоминание за час для каждой версии записи. Для нескольких интервалов добавьте reminder_kind в ключ. Индекс (state, due_at) ускоряет выборку. Version увеличивается при переносе, смене получателя и других изменениях, влияющих на уведомление. Это прикладные таблицы вашего проекта; готовой модели Appointment в Laravel нет.

Считаем время и создаём напоминание

Уточняйте у клиента зону записи: время консультации может относиться к зоне кабинета, а не телефона. На форме покажите дату, время и название зоны. Для зон с переводом часов неоднозначное или несуществующее местное время нужно разрешить при записи, до вычисления напоминания.

PHP · перевод подтверждённого времени в UTC
<?php
declare(strict_types=1);

use Carbon\CarbonImmutable;

// Значение и зона уже проверены формой записи.
$zone = 'Europe/Moscow';
$start = CarbonImmutable::createFromFormat('!Y-m-d H:i', '2026-11-10 15:00', $zone);
if ($start === false) {
    throw new InvalidArgumentException('Некорректное время записи');
}
$startsAtUtc = $start->utc();
$dueAtUtc = $startsAtUtc->subHour();

В этом примере консультация начинается в 12:00 UTC, напоминание готово с 11:00 UTC. Используем неизменяемую дату, чтобы вычитание часа не сдвинуло само начало встречи. Общую timezone приложения и соединение БД настройте на UTC.

Создание записи и строки appointment_reminders выполняйте в одной транзакции. Для новой строки задайте state=pending, attempts=0, appointment_version равной версии записи. Если запись создана меньше чем за час до начала, выберите явное правило: отправить в ближайшую минуту либо не создавать часовое напоминание. В этом руководстве отправляем в ближайшую минуту, пока событие ещё не началось.

Не сравнивайте due_at с текущей минутой на точное равенство. Выборка due_at <= now() подхватит пропущенный запуск. Начавшиеся события отсекаются отдельной проверкой starts_at > now().

Подключаем команду к планировщику Laravel

Создайте команду и зарегистрируйте расписание. Само имя команды ничего не отправляет, пока не реализован handle. Пример ниже использует стандартный каталог app/Console/Commands.

Bash · в вашем Laravel-приложении
php artisan make:command SendAppointmentReminders
PHP · routes/console.php
<?php
use Illuminate\Support\Facades\Schedule;

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

На сервере вашего приложения один раз настройте запуск schedule:run каждую минуту. Замените путь своим; если планировщик уже запущен, вторую cron-строку добавлять не нужно.

Bash · строка crontab
* * * * * cd /path/to/your-app && php artisan schedule:run >> /dev/null 2>&1

Проверить регистрацию можно командой php artisan schedule:list. Для локальной разработки подходит php artisan schedule:work. withoutOverlapping использует блокировку cache и ограничивает пересечение именно запусков команды; уникальные строки и атомарный захват напоминания всё равно нужны. На нескольких серверах понадобится согласованная конфигурация общего cache и, при необходимости, onOneServer.

Планировщик не должен запускать «15:00» отдельно в зоне каждого клиента. Он проверяет готовые UTC-моменты раз в минуту. Это упрощает работу с разными зонами и переходами на летнее время; ограничения timezone-расписаний описаны в документации Laravel Scheduler.

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

В config/services.php добавьте секцию telegram с token из env("TELEGRAM_BOT_TOKEN"). Реальный токен хранится в окружении, не в коде. Схема таблиц выше должна быть создана миграциями вашего приложения. Ниже — содержимое класса команды целиком; во время выполнения не нужны модели с неочевидными casts.

PHP · app/Console/Commands/SendAppointmentReminders.php
<?php
declare(strict_types=1);

namespace App\Console\Commands;

use Carbon\CarbonImmutable;
use Illuminate\Console\Command;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Http;

final class SendAppointmentReminders extends Command
{
    protected $signature = 'appointments:remind';
    protected $description = 'Send due appointment reminders';

    public function handle(): int
    {
        $token = (string) config('services.telegram.token');
        if ($token === '') {
            $this->error('Не настроен токен Telegram');
            return self::FAILURE;
        }
        $rows = DB::table('appointment_reminders')
            ->where('state', 'pending')->where('due_at', '<=', now())
            ->orderBy('due_at')->limit(20)->get();

        foreach ($rows as $row) {
            // Только один процесс может изменить pending на sending.
            $claimed = DB::table('appointment_reminders')->where('id', $row->id)
                ->where('state', 'pending')->where('due_at', '<=', now())
                ->where('attempts', '<', 5)->update([
                    'state' => 'sending', 'attempts' => DB::raw('attempts + 1'),
                ]);
            if ($claimed !== 1) {
                continue;
            }
            $query = DB::table('appointment_reminders')->where('id', $row->id);
            $row = $query->first();
            $appointment = DB::table('appointments')->where('id', $row->appointment_id)->first();
            if ($appointment === null || $appointment->status !== 'confirmed'
                || (int) $appointment->version !== (int) $row->appointment_version
                || CarbonImmutable::parse($appointment->starts_at, 'UTC')->lte(now())) {
                $query->update(['state' => 'cancelled']);
                continue;
            }
            $when = CarbonImmutable::parse($appointment->starts_at, 'UTC')
                ->setTimezone($appointment->timezone)->format('d.m.Y H:i');
            try {
                $response = Http::connectTimeout(2)->timeout(5)
                    ->post('https://api.telegram.org/bot'.$token.'/sendMessage', [
                        'chat_id' => (string) $appointment->telegram_chat_id,
                        'text' => 'Напоминаем о консультации '.$when.' ('.$appointment->timezone.').',
                    ]);
            } catch (ConnectionException) {
                $query->update(['state' => 'unknown']);
                continue;
            }
            $body = $response->json();
            if ($response->successful() && is_array($body)
                && ($body['ok'] ?? null) === true
                && is_int($body['result']['message_id'] ?? null)) {
                $query->update([
                    'state' => 'sent', 'telegram_message_id' => $body['result']['message_id'],
                ]);
            } elseif (is_array($body) && ($body['ok'] ?? null) === false
                && ($body['error_code'] ?? null) === 429
                && (int) $row->attempts < 5) {
                $wait = max(1, (int) ($body['parameters']['retry_after'] ?? 60));
                $query->update(['state' => 'pending', 'due_at' => now()->addSeconds($wait)]);
            } else {
                $knownRejection = !$response->serverError() && is_array($body)
                    && ($body['ok'] ?? null) === false;
                $query->update(['state' => $knownRejection ? 'failed' : 'unknown']);
            }
        }
        return self::SUCCESS;
    }
}

Это консервативный пример: HTTP-клиент не вызывает retry, а таймаут не вызывает повтор sendMessage. После подтверждённого Telegram 429 строка снова становится pending, не более пяти попыток всего. Due_at задаёт нижнюю границу повтора, поэтому планировщик может отправить позже, но не раньше retry_after.

Зависшее sending после аварийного завершения процесса тоже требует разбора как неизвестный результат. Не возвращайте все sending в pending по истечении пяти минут: сообщение могло дойти до клиента до падения процесса. Для эксплуатации добавьте время захвата, журнал состояния и оповещение о failed/unknown без токена и полного URL запроса.

В этой команде транзакция БД не удерживается во время HTTP. У неё остаётся короткое окно между чтением записи и запросом Telegram: перенос или отмена в этот момент не могут отозвать уже начатую отправку. Это нужно учитывать в интерфейсе отмены. Запись sent подтверждает успешный ответ API, но не прочтение сообщения клиентом.

Переносим или отменяем запись

При переносе начните транзакцию, заблокируйте строку appointments для обновления и увеличьте version. Запишите новые starts_at/timezone, отмените старые pending-напоминания и создайте одно pending для новой версии. Сохраните транзакцию целиком. Не меняйте дату у уже отправленной строки: история должна показывать, какое уведомление действительно ушло.

При отмене тем же способом задайте status=cancelled, увеличьте version и отмените pending. Команда после захвата сверит версию и статус ещё раз. Отмена, сохранённая до этого чтения, остановит отправку; старые задания очереди, если вы их добавите, тоже должны проходить эту проверку.

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

При большом потоке планировщик может только создавать задания очереди. Передавайте ID напоминания, а в handle задания заново загружайте appointment. Долгая задержка Job::delay сама по себе не решает отмену и изменение версии. Запуск worker и базовая настройка очереди разобраны в статье об уведомлениях Laravel.

Проверяем время, отмену и сбои

  • Создайте тестовую запись на 15:00 Europe/Moscow: starts_at должен быть 12:00 UTC, due_at — 11:00 UTC.

  • Перенесите её до времени отправки. Старая версия не должна отправляться; у новой остаётся одно напоминание.

  • Отмените запись, а затем запустите команду: отправок быть не должно. Повторный запуск после sent тоже ничего не отправляет.

  • Сдвиньте due_at в прошлое при будущем starts_at: уведомление подхватывается. Прошедшее событие пропускается.

  • Через Http::fake проверьте ok=true, 429 с retry_after, 403 и соединение без ответа. Они должны давать sent, pending, failed и unknown соответственно.

Убедитесь, что сервисный мониторинг замечает пропуск планировщика и рост failed/unknown. Рабочий cron не доказывает доставку сообщения. Для тестов используйте отдельный чат, а не реальных клиентов.

При отправке через BotGate бизнес-таблицы и расписание остаются у вас. Пример выше обращается напрямую к Telegram; его нельзя переключить только заменой токена. Подключите транспорт по документации API или используйте Laravel-пакет. В таком варианте отдельно учитывайте лимит самого сервиса и ответ Telegram, чтобы решение о повторе принимал один уровень приложения.

Дополнительные источники: планировщик Laravel, HTTP-клиент и его тестирование, sendMessage Telegram.