Сначала определите правила выбора языка
Перевод пары приветствий не делает бота многоязычным. Пользователь должен видеть на выбранном языке инструкции, подписи кнопок, ошибки ввода и сообщения, которые приходят позже без нового входящего 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, как в отдельном руководстве.
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 останутся вне него.
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
declare(strict_types=1);
return ['token' => env('BOT_TOKEN'), 'secret' => env('BOT_WEBHOOK_SECRET')];
Создайте каталог app/GuideBot для классов диалога и транспорта, app/Console/Commands — для команд. Каждый блок ниже является отдельным файлом с указанным именем. Скопируйте миграцию в database/migrations; таблицы demo_* предназначены для этого отдельного приложения, не для вставки в существующую БД BotGate.
<?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.
<?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
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
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
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
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
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
declare(strict_types=1);
use App\GuideBot\Webhook;
use Illuminate\Support\Facades\Route;
Route::post('/telegram', Webhook::class);
->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
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
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
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
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
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;
}
}
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 и выполните команду ниже. Она действительно поставит сообщение вашему тестовому пользователю в очередь.
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 при проверке изменений; одинаковое число строк ещё не доказывает совпадение смысла.
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 у одного тестового бота. Сам перевод диалога от выбранного транспорта не меняется.