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

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

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

Кому можно отправлять рассылку

Для обычного личного диалога пользователь сначала должен открыть бота и начать с ним общение. Нельзя собрать произвольные Telegram ID и считать их доступной аудиторией. В нашем приложении рассылка дополнительно требует явного действия «Получать анонсы» или /subscribe после объяснения её содержания.

Сохраняйте согласие отдельно от технической доступности чата. /stop переводит active в false. Новый /start не должен незаметно подписывать человека заново. Команды поступают через проверенный webhook; chat_id и user_id берутся из личного сообщения, а бот — из доверенной настройки обработчика.

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

В отличие от одиночного уведомления через Laravel, здесь важно хранить ход всей кампании. Job в очереди — лишь сигнал обработать получателя, а не единственное место, где существует информация о нём.

Какие данные хранить

Ниже ядро небольшого приложения на Laravel 11–13. Для Laravel 11/12 нужен PHP 8.2+, для Laravel 13 — PHP 8.3+. Очередь и общий cache используют Redis, постоянные данные — транзакционную SQL-БД. Пример отправляет обычный текст через BotGate, без платных ускоренных рассылок.

Создайте миграцию с такими таблицами: строки use расположите в начале файла перед классом, вызовы Schema::create — внутри метода up(). Добавьте down() с удалением таблиц в обратном порядке. Интерфейс запуска кампании должен быть доступен только уполномоченному администратору.

PHP · импорты миграции и тело up()
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('broadcast_subscribers', function (Blueprint $t): void {
    $t->id();
    $t->string('bot_id');
    $t->bigInteger('chat_id');
    $t->boolean('active')->default(false);
    $t->boolean('reachable')->default(true);
    $t->timestamp('consented_at')->nullable();
    $t->unique(['bot_id', 'chat_id']);
});
Schema::create('broadcast_campaigns', function (Blueprint $t): void {
    $t->id();
    $t->string('bot_id');
    $t->text('text');
    $t->string('status')->default('draft');
});
Schema::create('broadcast_deliveries', function (Blueprint $t): void {
    $t->id();
    $t->foreignId('campaign_id')->constrained('broadcast_campaigns');
    $t->foreignId('subscriber_id')->constrained('broadcast_subscribers');
    $t->string('status')->default('pending');
    $t->unsignedInteger('attempts')->default(0);
    $t->timestamp('available_at');
    $t->timestamp('started_at')->nullable();
    $t->bigInteger('message_id')->nullable();
    $t->string('last_error')->nullable();
    $t->unique(['campaign_id', 'subscriber_id']);
    $t->index(['status', 'available_at']);
});
Schema::create('broadcast_limits', function (Blueprint $t): void {
    $t->string('bot_id')->primary();
    $t->timestamp('next_send_at');
});
  • pending — ждёт отправки; available_at ограничивает время следующей попытки.

  • sending — worker уже взял запись и мог начать сетевой запрос.

  • sent — получен успешный ответ с message_id. Это принятие Telegram, а не подтверждение прочтения.

  • skipped — отправка отменена из-за отписки или недоступного адресата.

  • failed — получена определённая ошибка или исчерпаны повторы подтверждённого лимита.

  • unknown — неизвестно, принял ли Telegram сообщение. Автоматически повторять нельзя.

Уникальность campaign_id + subscriber_id не позволяет дважды добавить человека в одну кампанию. Она не делает внешнюю отправку exactly-once: между ответом Telegram и записью sent остаётся окно сбоя. Если процесс погиб в этом окне, запись sending потребует разбора.

Создаём снимок аудитории

Текст и список получателей фиксируем перед началом отправки. Для примера используем обычный текст без parse_mode и консервативный бюджет 3000 единиц UTF-16, учитывающий составные эмодзи. Сначала используйте только тестовые подписки. Переменные $botId и $text ниже приходят из проверенного административного действия; ID бота — публичный ID BotGate.

PHP · создание кампании в административном сервисе
use Illuminate\Support\Facades\DB;

if (trim($text) === '' || strlen(mb_convert_encoding($text, 'UTF-16LE', 'UTF-8')) / 2 > 3000) {
    throw new InvalidArgumentException('Текст пустой или превышает бюджет длины.');
}
$campaignId = DB::transaction(function () use ($botId, $text): int {
    DB::table('broadcast_limits')->insertOrIgnore([
        'bot_id' => $botId, 'next_send_at' => now(),
    ]);
    $id = DB::table('broadcast_campaigns')->insertGetId([
        'bot_id' => $botId, 'text' => $text, 'status' => 'draft',
    ]);
    DB::table('broadcast_subscribers')->where('bot_id', $botId)
        ->where('active', true)->where('reachable', true)
        ->orderBy('id')->chunkById(500, function ($subscribers) use ($id): void {
            $rows = [];
            foreach ($subscribers as $subscriber) {
                $rows[] = [
                    'campaign_id' => $id, 'subscriber_id' => $subscriber->id,
                    'status' => 'pending', 'available_at' => now(),
                ];
            }
            DB::table('broadcast_deliveries')->insert($rows);
        });
    DB::table('broadcast_campaigns')->where('id', $id)->update(['status' => 'running']);
    return $id;
});

Планировщик увидит running после фиксации транзакции. Если вместо планировщика вы сразу dispatch-ите задания из этой транзакции, используйте afterCommit(). Для очень большой аудитории подготовку снимка вынесите в отдельную задачу и сохраняйте draft до её полного завершения.

Повтор административного HTTP-запроса не должен создавать новую кампанию: в интерфейсе запуска нужен собственный уникальный ключ операции или переход существующего draft в running. В коде выше показана одна операция создания; его повторный вызов намеренно создаёт другую кампанию. После запуска не редактируйте её текст — для другой версии создавайте новую.

Настраиваем транспорт и классифицируем результат

Bash · установка и конфигурация
composer require botgate/laravel
php artisan vendor:publish --tag=botgate-config
dotenv · окружение приложения
BOTGATE_API_KEY=your-api-key
BOTGATE_TIMEOUT=10
BOTGATE_RETRY_MAX=0
QUEUE_CONNECTION=redis
CACHE_STORE=redis

Laravel-пакет устанавливает SDK как зависимость. Автоматические повторы SDK отключены, потому что решения о повторе ниже принимает приложение. Для Redis-настройки соединения очереди задайте retry_after = 90 секунд: это время повторной выдачи потерянного задания, а не задержка после Telegram 429.

Вынесем один вызов в сервис. При подтверждённом лимите возвращаем limited и время ожидания. При неопределённой ошибке — unknown. В журнал получателя записываем короткий код причины, без ключей, полного HTTP-запроса и текста исключения.

PHP · app/Services/BroadcastTransport.php
<?php
declare(strict_types=1);
namespace App\Services;

use BotGate\Exception\RateLimitException;
use BotGate\Exception\TelegramException;
use BotGate\Laravel\Facades\BotGate;
use Throwable;

final class BroadcastTransport
{
    public function send(string $botId, int $chatId, string $text): array
    {
        try {
            $result = BotGate::bot($botId)->call('sendMessage', [
                'chat_id' => $chatId, 'text' => $text,
            ])->result;
            if (!is_array($result) || !is_int($result['message_id'] ?? null)) {
                return ['status' => 'unknown', 'error' => 'unexpected_response'];
            }
            return ['status' => 'sent', 'message_id' => $result['message_id']];
        } catch (RateLimitException $e) {
            return ['status' => 'limited', 'delay' => max(1, $e->retryAfter() ?? 60),
                'error' => 'botgate_429'];
        } catch (TelegramException $e) {
            $code = $e->telegramErrorCode();
            if ($code === 429) {
                return ['status' => 'limited', 'delay' => max(1, $e->retryAfter() ?? 60),
                    'error' => 'telegram_429'];
            }
            if ($code !== null && $code >= 400 && $code < 500) {
                return ['status' => 'failed', 'error' => 'telegram_' . $code,
                    'unreachable' => $code === 403];
            }
            return ['status' => 'unknown', 'error' => 'telegram_uncertain'];
        } catch (Throwable) {
            return ['status' => 'unknown', 'error' => 'transport_or_application'];
        }
    }
}

Telegram 403 в личном чате может быть связан с блокировкой бота или другой недоступностью адресата. Ниже мы прекращаем доставку этому адресу через reachable=false, сохраняя отдельно active и согласие. Не называйте любой 403 доказательством добровольной отписки. Восстановление reachable выполняйте после проверки доступа или нового явного действия пользователя.

Лимит BotGate и вложенный Telegram 429 различаются: первый даёт RateLimitException, второй — TelegramException с telegramErrorCode(). Если ограничение относится к общему API-ключу для нескольких ботов, общий регулятор должен охватывать все эти боты. Пример ниже предназначен для одного бота с отдельным потоком рассылки.

Отправляем одному получателю

Job использует общий Redis-lock на бота, чтобы два worker не отправляли рассылку одновременно. Под блокировкой он захватывает pending, проверяет отписку и общий next_send_at. Перед сетевым вызовом SQL-транзакция закрывается. Интервал в одну секунду — консервативная настройка примера, а не обещание отсутствия лимитов.

PHP · app/Jobs/SendBroadcastRecipient.php
<?php
declare(strict_types=1);
namespace App\Jobs;

use App\Services\BroadcastTransport;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;

final class SendBroadcastRecipient implements ShouldQueue
{
    use Dispatchable, Queueable;

    public int $tries = 1;
    public int $timeout = 30;
    public bool $failOnTimeout = true;

    public function __construct(public int $deliveryId) {}

    public function handle(BroadcastTransport $transport): void
    {
        $botId = DB::table('broadcast_deliveries as d')
            ->join('broadcast_campaigns as c', 'c.id', '=', 'd.campaign_id')
            ->where('d.id', $this->deliveryId)->value('c.bot_id');
        if (!is_string($botId)) {
            return;
        }
        $lock = Cache::lock('broadcast:' . $botId, 60);
        if (!$lock->get()) {
            return; // pending останется для следующего прохода планировщика.
        }
        try {
            $item = DB::transaction(function () use ($botId): ?array {
                $d = DB::table('broadcast_deliveries')->where('id', $this->deliveryId)
                    ->lockForUpdate()->first();
                if (!$d || $d->status !== 'pending' || $d->available_at > now()->toDateTimeString()) {
                    return null;
                }
                $c = DB::table('broadcast_campaigns')->where('id', $d->campaign_id)->first();
                if (!$c || $c->status !== 'running') {
                    return null;
                }
                $s = DB::table('broadcast_subscribers')->where('id', $d->subscriber_id)
                    ->lockForUpdate()->first();
                $delivery = DB::table('broadcast_deliveries')->where('id', $d->id);
                if (!$s || $s->bot_id !== $botId || !$s->active || !$s->reachable) {
                    $delivery->update(['status' => 'skipped']);
                    return null;
                }
                $limit = DB::table('broadcast_limits')->where('bot_id', $botId)
                    ->lockForUpdate()->first();
                if (!$limit || $limit->next_send_at > now()->toDateTimeString()) {
                    return null;
                }
                DB::table('broadcast_limits')->where('bot_id', $botId)
                    ->update(['next_send_at' => now()->addSecond()]);
                $delivery->update([
                    'status' => 'sending', 'started_at' => now(), 'attempts' => $d->attempts + 1,
                ]);
                return ['chat_id' => (int) $s->chat_id, 'subscriber_id' => (int) $s->id,
                    'text' => $c->text, 'attempt' => $d->attempts + 1];
            });
            if ($item === null) {
                return;
            }
            $outcome = $transport->send($botId, $item['chat_id'], $item['text']);
            DB::transaction(function () use ($outcome, $item, $botId): void {
                $changes = ['status' => $outcome['status'],
                    'last_error' => $outcome['error'] ?? null];
                if ($outcome['status'] === 'sent') {
                    $changes['message_id'] = $outcome['message_id'];
                }
                if ($outcome['status'] === 'limited') {
                    $next = now()->addSeconds($outcome['delay']);
                    DB::table('broadcast_limits')->where('bot_id', $botId)
                        ->update(['next_send_at' => $next]);
                    $changes['status'] = $item['attempt'] < 5 ? 'pending' : 'failed';
                    $changes['available_at'] = $next;
                }
                if ($outcome['unreachable'] ?? false) {
                    DB::table('broadcast_subscribers')->where('id', $item['subscriber_id'])
                        ->update(['reachable' => false]);
                }
                DB::table('broadcast_deliveries')->where('id', $this->deliveryId)
                    ->where('status', 'sending')->update($changes);
            });
        } finally {
            $lock->release();
        }
    }
}

Задание не вызывает release(): повторный запуск обеспечивается выборкой pending из БД. Поэтому $tries=1 не конфликтует с отложенными попытками после 429. Счётчик attempts в самой записи ограничивает реальные вызовы до пяти; дубли заданий и ожидание lock его не увеличивают.

Все worker должны использовать один Redis и общий префикс cache. HTTP timeout равен 10 секундам, job timeout — 30, срок lock — 60, Redis retry_after — 90. При аварийном завершении job запись sending не возвращается автоматически в pending. Для таймаутов worker требуется поддерживаемое окружение с PCNTL; запуск в примере рассчитан на Linux.

Планировщик, пауза и продолжение

В routes/console.php добавьте выборку одного доступного получателя на каждого бота. Laravel scheduler должен быть настроен штатным способом. everySecond работает в течение запуска schedule:run; если scheduler остановился, строки pending сохранятся и будут выбраны после его восстановления.

PHP · routes/console.php
use App\Jobs\SendBroadcastRecipient;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schedule;

Schedule::call(function (): void {
    $bots = DB::table('broadcast_campaigns')->where('status', 'running')
        ->distinct()->pluck('bot_id');
    foreach ($bots as $botId) {
        $id = DB::table('broadcast_deliveries as d')
            ->join('broadcast_campaigns as c', 'c.id', '=', 'd.campaign_id')
            ->join('broadcast_limits as l', 'l.bot_id', '=', 'c.bot_id')
            ->where('l.next_send_at', '<=', now())
            ->where('c.bot_id', $botId)->where('c.status', 'running')
            ->where('d.status', 'pending')->where('d.available_at', '<=', now())
            ->orderBy('d.id')->value('d.id');
        if ($id !== null) {
            SendBroadcastRecipient::dispatch((int) $id)->onQueue('telegram-broadcast');
        }
    }
})->everySecond();
Bash · отдельный worker в тестовом окружении
php artisan queue:work redis --queue=telegram-broadcast --tries=1 --timeout=30

Пока очередь недоступна или отстаёт, повторный проход может поставить дубликат задания. Job повторно проверяет состояние в БД и не отправляет sent заново. Контролируйте размер очереди: для большой базы добавьте ограничение выдачи заданий и отдельное состояние их резервирования с восстановлением после сбоя.

Для паузы установите status=paused у выбранной кампании. Для продолжения верните running. Уже начатый сетевой запрос может завершиться; pending подождут, а sent, skipped, failed и unknown не попадут в выборку. Не используйте «повторить все failed jobs» как способ продолжить рассылку.

Показывайте администратору число записей по каждому статусу. Отсутствие pending ещё не означает успешное завершение, если есть sending или unknown. После подтверждённой остановки погибшего worker старые sending переводят в unknown с журналом решения; просто истёкшее время не доказывает, что сообщение не ушло.

Пример не создаёт интерфейс отчётов и не переводит кампанию в completed автоматически. Завершайте её после разбора всех результатов. Массовые ошибки ключа, прав или параметров — повод поставить кампанию на паузу и исправить причину, а не повторять отправку каждому пользователю.

Скорость и ограничения Telegram

Общий лимит бота разделяют рассылка, ответы на команды и другие уведомления. Начните с небольшой скорости, оставьте запас для диалогов и учитывайте лимиты выбранного транспорта. Ускорять отправку простым добавлением worker бесполезно, если они не используют общий регулятор.

В нашем примере bot-level lock и next_send_at координируют именно этот поток рассылки. Если другие части приложения тоже отправляют сообщения, подключите их к общему ограничителю. Для нескольких ботов с единым API-ключом дополнительно учитывайте ограничение на ключ. Значение retry_after нельзя сокращать ради скорости.

Таймаут не равен отказу: сообщение могло уйти до обрыва соединения. Для unknown администратор принимает отдельное решение с учётом риска дубля; API sendMessage не предоставляет универсальный пользовательский ключ идемпотентности. Подробнее — ошибка 429 и дубли сообщений.

Проверяем на небольшой тестовой аудитории

  • Создайте кампанию с двумя собственными тестовыми аккаунтами. Успешные записи должны стать sent с message_id.

  • Отпишитесь через /stop после создания снимка: ещё не начатая доставка этому адресату должна стать skipped.

  • Запустите два одинаковых задания: фактическая отправка получателю должна произойти один раз при нормальном ответе.

  • Подставьте Telegram 429 и отдельный HTTP 429 BotGate: проверьте задержку для всего бота и предел в пять попыток.

  • Подставьте 403: только этот адресат должен стать unreachable, а согласие active не должно измениться.

  • Сымитируйте таймаут после вызова: запись должна стать unknown и не попасть в следующую автоматическую отправку.

  • Остановите worker после захвата: запись sending не должна самопроизвольно повториться.

  • Поставьте кампанию на паузу, затем продолжите: выбираются оставшиеся pending, текст и успешные результаты сохраняются.

Проверки с поддельным транспортом подтверждают логику состояний. Реальную очередь, Redis-lock между процессами и доставку Telegram проверьте отдельно в своём тестовом окружении до включения аудитории.

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