Перейти к содержанию
32 минуты чтения
Тема: Практика Laravel · Локализация · Диалоги

Как сделать Telegram-бота на нескольких языках

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

Сначала определите правила выбора языка

Перевод пары приветствий не делает бота многоязычным. Пользователь должен видеть на выбранном языке инструкции, подписи кнопок, ошибки ввода и сообщения, которые приходят позже без нового входящего Update. При этом технические команды и значения callback_data остаются стабильными: переводится надпись «Помощь», а действие help не меняет смысл.

В объекте User поле language_code необязательно и содержит языковой тег. В этом примере ru и ru-RU выбирают русский, en и en-US — английский. Неизвестный язык или отсутствие поля приводят к английскому. Это подсказка для первого контакта; по ней нельзя надёжно определить страну, валюту или часовой пояс. Объект User.

Ситуация

Решение в примере

Первый контакт

Нормализовать language_code и сохранить ru или en

Пользователь выбрал язык кнопкой

Сохранить новый выбор и подтвердить на новом языке

Следующий Update пришёл с другим language_code

Использовать сохранённый выбор

В выбранном словаре нет строки

Использовать английский перевод и записать ключ в журнал

Строки нет и в английском

Отправить безопасную запасную фразу без служебного ключа

Мы намеренно не переопределяем язык после первого сохранения, даже если первый выбор был автоматическим. Так поведение предсказуемо: смена языка Telegram на телефоне не меняет незавершённый диалог. Команда /language всегда доступна. Русский и английский обозначаем собственными названиями, без флагов: язык не равен гражданству.

Создайте отдельное приложение и таблицы

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

Bash · новое учебное приложение
composer create-project "laravel/laravel:^13.0" language-bot
cd language-bot
php artisan lang:publish

Создайте тестового бота через BotFather. В .env задайте значения ниже и параметры своей БД. BOT_WEBHOOK_SECRET должен быть случайной строкой, например 64 шестнадцатеричных символа; приведённые обозначения не являются рабочими секретами. Корнем сайта будет public, а .env и база SQLite останутся вне него.

ENV · дополнение .env
APP_URL=https://language-bot.example.com
APP_DEBUG=false
APP_LOCALE=en
APP_FALLBACK_LOCALE=en
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 для классов диалога и транспорта, app/Console/Commands — для команд. Каждый блок ниже является отдельным файлом с указанным именем. Скопируйте миграцию в database/migrations; таблицы demo_* предназначены для этого отдельного приложения, не для вставки в существующую БД BotGate.

PHP · database/migrations/2026_11_20_000001_create_language_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->string('locale', 5);
            $t->string('locale_source', 10);
            $t->string('name', 60)->nullable();
            $t->boolean('awaiting_name')->default(false);
        });
        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_users');
    }
};

chat_id хранится в bigint, имя может отсутствовать, awaiting_name показывает шаг диалога. locale_source различает первоначальное определение и ручное переключение. demo_updates защищает повтор обработки события, demo_outbox сохраняет исходящий ответ независимо от текущего HTTP-запроса. Не очищайте журнал событий при каждом перезапуске: это снова разрешит обработку старых повторов.

Переведите весь словарь диалога

Laravel поддерживает PHP-файлы словарей в lang/ru и lang/en. В свежем приложении lang может отсутствовать, поэтому выше выполнен lang:publish. Создайте в каждом языковом каталоге файл bot.php. Ключи — смысловые идентификаторы, а не исходные русские предложения: редактура фразы не должна ломать вызовы из кода. Локализация Laravel.

Одни и те же просьба ввести имя, ошибка и кнопки на русском и английском; ручной выбор языка сохраняется.
Одни и те же просьба ввести имя, ошибка и кнопки на русском и английском; ручной выбор языка сохраняется.
Поясняющая схема диалога. Подписи взяты из словарей статьи; интерфейс Telegram условно не воспроизводится.
PHP · lang/ru/bot.php
<?php

declare(strict_types=1);
return [
    'welcome' => "Здравствуйте! Это учебный бот записи.\nКак к вам обращаться? Напишите имя длиной от 2 до 60 символов.",
    'ask_name' => 'Напишите имя длиной от 2 до 60 символов.',
    'saved' => 'Спасибо, :name. Имя сохранено. Это демонстрация: реальная запись на приём не создаётся.',
    'choose_language' => 'Выберите язык. Он будет сохранён для следующих сообщений.',
    'language_saved' => 'Язык изменён на русский.',
    'language_button' => 'Изменить язык',
    'help_button' => 'Помощь',
    'help' => '/start — начать диалог; /language — выбрать язык; /help — помощь. Уведомления придут на сохранённом языке.',
    'bad_name' => 'Имя должно содержать от 2 до 60 символов. Попробуйте ещё раз.',
    'unknown' => 'Не удалось распознать команду. Используйте /start, /language или /help.',
    'stale' => 'Эта кнопка больше не поддерживается. Откройте /language или /start.',
    'notice' => 'Учебное уведомление по заявке :reference: статус обновлён. Ответьте /help, если нужна помощь.',
];
PHP · lang/en/bot.php
<?php

declare(strict_types=1);
return [
    'welcome' => "Hello! This is a booking demo bot.\nWhat should we call you? Enter a name between 2 and 60 characters.",
    'ask_name' => 'Enter a name between 2 and 60 characters.',
    'saved' => 'Thank you, :name. Your name has been saved. This is a demo: no real appointment has been booked.',
    'choose_language' => 'Choose your language. We will remember it for future messages.',
    'language_saved' => 'Language changed to English.',
    'language_button' => 'Change language',
    'help_button' => 'Help',
    'help' => '/start — start the conversation; /language — choose a language; /help — help. Notifications use your saved language.',
    'bad_name' => 'Your name must contain between 2 and 60 characters. Please try again.',
    'unknown' => 'Command not recognized. Use /start, /language or /help.',
    'stale' => 'This button is no longer supported. Open /language or /start.',
    'notice' => 'Demo notification for request :reference: the status has changed. Send /help if you need assistance.',
];

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

Имя и номер заявки вставляются через :name и :reference. Не склеивайте предложение из кусочков: в другом языке меняются порядок слов и пунктуация. Пользовательское имя не переводится. Отправка в примере идёт без parse_mode, поэтому символы < и & остаются обычным текстом; при переходе к HTML понадобится отдельное экранирование значений для Telegram.

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

Сделайте предсказуемый запасной перевод

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

declare(strict_types=1);

namespace App\GuideBot;

use Illuminate\Support\Facades\Lang;

final class BotText
{
    public static function initial(string $tag): string
    {
        $base = explode('-', strtolower(str_replace('_', '-', $tag)))[0];
        return in_array($base, ['ru', 'en'], true) ? $base : 'en';
    }

    /** @param array<string, string> $replace */
    public static function get(string $key, string $locale, array $replace = []): string
    {
        if (!in_array($locale, ['ru', 'en'], true)) {
            $locale = 'en';
        }
        $full = 'bot.'.$key;
        if (!Lang::hasForLocale($full, $locale)) {
            logger()->warning('Missing bot translation', ['key' => $full, 'locale' => $locale]);
            $locale = 'en';
        }
        $value = Lang::get($full, $replace, $locale, false);
        if (is_string($value) && $value !== $full) {
            return $value;
        }
        logger()->error('Missing fallback translation', ['key' => $full]);
        return 'Message unavailable. Please use /language or try again later.';
    }

    /** @return array<string, mixed> */
    public static function menu(string $locale): array
    {
        return ['inline_keyboard' => [[
            ['text' => self::get('language_button', $locale), 'callback_data' => 'language'],
            ['text' => self::get('help_button', $locale), 'callback_data' => 'help'],
        ]]];
    }
}

BotText проверяет наличие строки именно в выбранном языке, затем обращается к английскому. Обычный Laravel fallback полезен, но сам по себе не обнаруживает проблему: при отсутствии строки во всех словарях наружу может попасть ключ. Обёртка отмечает пропуск в журнале и не показывает клиенту bot.notice. Полный английский словарь остаётся обязательным, а запасная фраза — защитой от ошибки выкладки.

Локаль передаётся в каждый вызов Lang явно. Мы не меняем глобальный App::setLocale и не надеемся, что другой обработчик или долгоживущий worker сбросит язык. Это особенно важно, когда один процесс последовательно обслуживает русского и английского пользователя. В проектах с глобальным переключением локали её нужно восстанавливать в finally.

Меню строится заново на выбранном языке. В callback_data находятся language и help, а не переведённый текст кнопки. Поэтому старое русское «Помощь» продолжит работать после переключения на английский и вызовет актуальную английскую справку. Случайное значение lang:de не добавляет язык в список поддерживаемых.

Свяжите язык со всеми шагами диалога

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

declare(strict_types=1);

namespace App\GuideBot;

use Illuminate\Support\Facades\DB;

final class Dialogue
{
    // Called inside the webhook transaction, without HTTP requests.
    public function handle(Event $event): void
    {
        DB::table('demo_users')->insertOrIgnore([
            'chat_id' => $event->chatId, 'locale' => BotText::initial($event->language), 'locale_source' => 'telegram',
        ]);
        $user = DB::table('demo_users')->where('chat_id', $event->chatId)->lockForUpdate()->first();
        if (!$user) {
            throw new \RuntimeException('Missing user');
        }
        $locale = (string) $user->locale;
        $action = $event->action;
        $key = 'unknown';
        $replace = [];
        $buttons = BotText::menu($locale);
        if (in_array($action, ['/language', 'language'], true)) {
            $key = 'choose_language';
            $buttons = ['inline_keyboard' => [[
                ['text' => 'Русский', 'callback_data' => 'lang:ru'],
                ['text' => 'English', 'callback_data' => 'lang:en'],
            ]]];
        } elseif ($event->callbackId !== null && in_array($action, ['lang:ru', 'lang:en'], true)) {
            $locale = substr($action, 5);
            DB::table('demo_users')->where('chat_id', $event->chatId)->update(['locale' => $locale, 'locale_source' => 'manual']);
            $key = 'language_saved';
            $buttons = BotText::menu($locale);
        } elseif ($action === '/start') {
            DB::table('demo_users')->where('chat_id', $event->chatId)->update(['awaiting_name' => true]);
            $key = 'welcome';
        } elseif (in_array($action, ['/help', 'help'], true)) {
            $key = 'help';
        } elseif ($event->callbackId !== null) {
            $key = 'stale';
        } elseif ((bool) $user->awaiting_name && !str_starts_with($action, '/')) {
            $key = 'bad_name';
            if (mb_strlen($action) >= 2 && mb_strlen($action) <= 60) {
                DB::table('demo_users')->where('chat_id', $event->chatId)->update(['name' => $action, 'awaiting_name' => false]);
                $key = 'saved';
                $replace = ['name' => $action];
            }
        }
        $text = BotText::get($key, $locale, $replace);
        if ($key === 'language_saved' && (bool) $user->awaiting_name) {
            $text .= "\n".BotText::get('ask_name', $locale);
        }
        Outbox::add($event->chatId, 'update:'.$event->updateId, ['text' => $text, 'reply_markup' => $buttons]);
    }

    public function notify(int $chatId, string $reference): void
    {
        DB::transaction(function () use ($chatId, $reference): void {
            $user = DB::table('demo_users')->where('chat_id', $chatId)->lockForUpdate()->first();
            if (!$user) {
                throw new \RuntimeException('User must start the bot first');
            }
            Outbox::add($chatId, 'notice:'.$chatId.':'.$reference, [
                'text' => BotText::get('notice', (string) $user->locale, ['reference' => $reference]),
                'reply_markup' => BotText::menu((string) $user->locale),
            ]);
        });
    }

    public function canSend(\stdClass $row): bool
    {
        return true;
    }
}

При первом событии создаётся пользователь. Далее строка блокируется внутри внешней транзакции webhook, чтобы сохранение имени и переключение языка не потеряли изменения друг друга. Команда /start начинает ввод имени, но не сбрасывает язык. /language не отменяет ввод: после выбора бот снова напоминает, что ждёт имя, уже на новом языке.

Ввод имени принимается только на соответствующем шаге. Команда с начальным / не превращается в имя; callback тоже проходит отдельную ветку. После слишком короткого или длинного текста шаг остаётся прежним, и пользователь может исправить ввод. Неизвестная кнопка получает понятный переведённый ответ, а не PHP-ошибку.

Уведомление собирается по locale из БД в момент создания outbox. Текст затем заморожен: повтор отправки не меняет язык и содержание. Поэтому сообщение, уже стоявшее в очереди до переключения, может прийти на старом языке. Новые уведомления будут на новом. Если продукт требует менять и ожидающие сообщения, храните ключ шаблона и параметры, определяйте язык при отправке и отдельно проектируйте поведение при повторе.

Уже отправленные сообщения и кнопки в истории автоматически не переводятся. Здесь бот присылает новый ответ, сохраняя понятную историю. Редактирование предыдущего сообщения возможно, но потребует хранения message_id и отдельной обработки недоступного сообщения; для смены языка это не обязательное условие.

Подключите проверенный входящий webhook

Входящий 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 или сырые заголовки. Для чтения таблиц используйте закрытый административный доступ.

В bootstrap/app.php добавьте api к уже существующему withRouting, сохранив остальные параметры своего приложения. URL будет /api/telegram. Не добавляйте произвольный chat_id из формы или строки запроса: весь диалог привязан к проверенному событию Telegram.

Отправляйте ответы и уведомления из сохранённых данных

Исходящие сообщения сохраняются в 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.

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

declare(strict_types=1);

namespace App\Console\Commands;

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

final class Notify extends Command
{
    protected $signature = 'bot:notify {chat} {reference}';
    protected $description = 'Queue one translated demo notification';
    public function handle(Dialogue $dialogue): int
    {
        $chat = filter_var($this->argument('chat'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
        $reference = $this->argument('reference');
        if ($chat === false || !is_string($reference) || !preg_match('/^[A-Za-z0-9-]{1,40}$/D', $reference)) {
            $this->error('Use a positive chat ID and a short reference.');
            return self::FAILURE;
        }
        $dialogue->notify($chat, $reference);
        $this->info('Stored in outbox; this does not confirm delivery.');
        return self::SUCCESS;
    }
}

Команда bot:notify нужна для проверки фонового уведомления без нового сообщения пользователя. Она принимает уже известный chat_id и короткий номер учебной заявки. Повтор той же пары не создаст новую строку. В настоящей системе ключ должен содержать идентификатор конкретного события смены статуса, иначе второе законное обновление той же заявки будет ошибочно признано повтором.

Эта команда доступна администратору в CLI. Не превращайте её в публичный HTTP endpoint без проверки полномочий и принадлежности заявки. В рабочем приложении вызывайте notify из обработчика подтверждённого бизнес-события. Отправлять уведомления произвольному Telegram ID, который ещё не начал диалог с ботом, этот пример не позволяет.

Запустите и пройдите русский и английский сценарии

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 · запуск в каталоге учебного приложения
php artisan migrate
php artisan route:list --path=api/telegram
php artisan bot:webhook
php artisan bot:deliver --watch

migrate создаёт таблицы, route:list должен показать POST api/telegram, bot:webhook при подтверждённой регистрации выводит sent. Последняя команда остаётся работающим процессом: держите её в отдельном терминале, а в рабочем окружении используйте менеджер процессов. APP_URL должен уже открываться по HTTPS. После изменения config-кэша обновите его обычным способом и перезапустите долгоживущий отправитель.

  • Откройте тестового бота и отправьте /start. На русском языке Telegram должно появиться русское приглашение ввести имя.

  • Введите один символ: бот покажет русскую ошибку и продолжит ждать имя.

  • Откройте /language, выберите English, затем снова введите один символ. Ошибка и кнопки должны стать английскими.

  • Введите Anna: получите английское подтверждение с именем. После перезапуска приложения /help останется английским.

  • Для уведомления найдите собственный chat_id в demo_users и выполните команду ниже. Она действительно поставит сообщение вашему тестовому пользователю в очередь.

Bash · замените CHAT_ID своим тестовым chat_id
php artisan bot:notify CHAT_ID DEMO-001

Создайте второй тестовый диалог на другом языке: уведомления обоим пользователям должны использовать разные сохранённые локали. Повторите DEMO-001 для первого чата — новой строки быть не должно. Для ещё одного уведомления используйте новый номер DEMO-002. Так проверяется не только приветствие, но и путь без входящего Update.

Проверьте отсутствие перевода и типовые ошибки

Проверка

Ожидаемый результат

language_code отсутствует или равен неподдерживаемому тегу

Первый ответ по-английски; ручной выбор доступен

Повтор одного update_id

Нет повторного сохранения и второй строки outbox

Удалена одна русская строка в тестовом словаре

Английский текст и Missing bot translation в журнале

Ключ отсутствует в обоих словарях

Запасная фраза без имени внутреннего ключа

Одинаковый worker обслуживает ru и en

Каждый ответ использует явную локаль

В очередь попал старый текст до смены языка

Он сохраняет прежний язык; новые сообщения используют новый

Проверку удаления строки делайте в тестовой копии и верните словарь после опыта. При изменении PHP-словарей учитывайте долгоживущие процессы и OPcache: одной правки файла может быть недостаточно, если приложение продолжает держать старый перевод в памяти. Сравнивайте наборы ключей ru/en и имена placeholders при проверке изменений; одинаковое число строк ещё не доказывает совпадение смысла.

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, затем возобновите отправитель.

Если диалог переведён, а меню команд Telegram осталось на другом языке, это отдельный механизм setMyCommands со scope и language_code. Ручной выбор в вашей БД не меняет язык клиента Telegram. Для меню, которое должно следовать ручному выбору, потребуется подходящий chat scope и управление ранее заданными списками. Это разобрано в статье о меню команд.

Если отправка идёт через BotGate

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

Не заменяйте только URL в приведённом Telegram-клиенте: у BotGate другая авторизация и собственные транспортные ошибки. Входящие события сервиса также проверяются по его контракту подписи, а не по X-Telegram-Bot-Api-Secret-Token этого прямого webhook. Не регистрируйте два конкурирующих webhook у одного тестового бота. Сам перевод диалога от выбранного транспорта не меняется.