В предыдущей статье «Краткий обзор подсистемы команд в Symfony», мы рассмотрели возможности «команд» и на «синтетических примерах» рассказали об удобстве применения.
В этой статье покажем, как ещё могут использоваться Symfony-команды. Для живого примера возьмём задачу создания Telegram-бота. Функционал будет простым: отреагировать на команду /start, запросив код подтверждения, и обработать ввод кода, проверив его формат и актуальность.
Исходный пример был написан в 2023 году. Основные принципы работы Symfony и Telegram Bot API остаются применимыми, но некоторые технические детали требуют обновления: для новых проектов стоит использовать PHP-атрибуты, защищать webhook секретным токеном и учитывать современные способы интеграции с API.
Пример сценария:
Пример диалога:
Пользователь:
/startБот: Привет! Введите ваш код подтверждения в формате XXX-XXX. Пользователь:123-0Бот: Неверный формат, введите код в формате XXX-XXX. Пользователь:123-123Бот: Спасибо! Проверяю ваш код! Бот: Код верный!
Главная цель – показать, как используется Symfony Framework и его компоненты (подсистемы).
Содержание
- Этап № 1 – получаем API token для телеграм бота
- Этап № 2 – решаем, как хранить HTTP API token внутри Symfony
- Этап № 3 – создаём отправитель сообщений и проверяем отправку сообщений в Telegram.
- Этап № 4 – создаём и задаём webhook для обработки диалогов с телеграм ботом
- Этап № 5 – обработка ввода и контекст общения
- Итоги
Этап № 1 – получаем API token для телеграм бота
Для этого нам надо зайти в чат с @BotFather и выполнить команду /newbot.

Затем ввести имя бота и его никнэйм (username).
После этого в сообщении получим HTTP API token вида

Этап № 2 – решаем, как хранить HTTP API token внутри Symfony
Токен Telegram-бота — это секрет, который позволяет выполнять действия от имени бота через API. Его нельзя хранить в исходном коде, публиковать в репозитории или передавать в примерах HTTP-запросов, доступных посторонним.
Для локальной разработки подойдёт переменная окружения в .env.local. В production лучше использовать переменные окружения сервера или специализированное хранилище секретов, например Symfony Secrets. Если токен предполагается менять через интерфейс приложения, необходимо отдельно продумать защищённое хранение, права доступа и аудит изменений.
Для упрощения будем использовать .env и .env.local. В .env можно указать имя переменной с пустым значением, а реальный токен поместить в .env.local, который не должен попадать в Git-репозиторий. Для production переменную следует задавать через окружение приложения или защищённое хранилище.
Если токен случайно оказался в публичном репозитории, его необходимо отозвать и выпустить новый через BotFather.
Итого: в любом случае начинаем с хранения токена в .env.local, а дальше действуем по обстоятельствам, при этом в .env прописываем пустое значение.

В современных Symfony-приложениях переменную окружения можно внедрить непосредственно в сервис с помощью атрибута #[Autowire] либо настроить аргумент через config/services.yaml. Необязательно сначала переносить токен в общий ParameterBagInterface.
Например, для класса сервиса можно использовать конструктор:
use Symfony\Component\DependencyInjection\Attribute\Autowire;
public function __construct(
#[Autowire('%env(TELEGRAM_BOT_TOKEN)%')]
private readonly string $token,
) {
}
Этот фрагмент показывает внедрение зависимости; полный пример сервиса отправки сообщений приведён ниже.

Этап № 3 – создаём отправитель сообщений и проверяем отправку сообщений в Telegram.
Теперь, когда у нас есть токен, следует его проверить и отправить сообщение куда-либо, например себе в личные сообщения. Но как узнать свой chat_id?
Для отправки личного сообщения боту нужен идентификатор чата — chat_id. Обычный @username пользователя не является универсальной заменой этого идентификатора: бот не может произвольно начинать личную переписку с любым пользователем Telegram.
Для тестирования сначала откройте бота и нажмите «Запустить». Затем получите обновления через getUpdates и найдите message.chat.id. Если для бота уже настроен webhook, метод getUpdates работать одновременно с ним не будет: необходимо использовать получаемые webhook-события либо временно отключить webhook.
- Запускаем общение с ботом через кнопку «Запустить» и отправляем ему любое текстовое сообщение.
- Идём по HTTP API ссылке – можно через браузер, но я в примере буду использовать curl + jq и терминал.

И ищу своё сообщение (text: «моё сообщение»), в данном примере это будет слово «test».

В ответе Telegram Bot API находим message.chat.id. Это идентификатор чата, который будем использовать для тестирования отправки сообщений. Не путайте его с message.from.id: в личном диалоге они обычно совпадают, но в группах и других типах чатов могут различаться.
Если сохраняете идентификаторы в базе данных, используйте тип, который способен вместить значения Telegram ID. Не следует рассчитывать на обычный 32-битный integer.
Теперь идём в Symfony и создаём «сервис отправки сообщений в телеграм».
Создаём файл src/Service/TelegramSender.php с кодом:

Сервис отправки сообщений должен обрабатывать не только HTTP-ошибки, но и ошибки соединения, тайм-ауты и некорректные ответы API. В Telegram успешный HTTP-ответ необходимо дополнительно проверять по полю ok. Логировать полный URL с токеном или секретные данные запроса нельзя.
Для production также стоит предусмотреть обработку ограничений частоты запросов, повторные попытки при временных ошибках и защиту от дублирования сообщений.
На данном этапе нужно убедиться только в возможности отправки сообщений.
Создаём код («Symfony команду»), в которой протестируем отправку сообщений и затем будем использовать эту команду для обработки запуска бота (/start).

Идём в терминал и вызываем команду:
Перед выполнением команды задайте переменную окружения TELEGRAM_TEST_CHAT_ID с реальным идентификатором тестового чата. Затем выполните:
php bin/console app:telegram:command:start "$TELEGRAM_TEST_CHAT_ID"
Команда сработает при условии, что в проекте уже зарегистрирована соответствующая Symfony-команда, показанная выше.
Если сообщение отправляется, то необходимо «допилить код» так, чтобы при передаче «параметра эмуляции отправки сообщения» сообщение не уходило по-настоящему, а лишь выводило результат в терминал. Это поможет нам отлаживать и тестировать приложение на различных условиях без спама в настоящего бота.
Для этого допишем код так:
src/Service/TelegramSender.php – изменения отмечены красными точками:

И дорабатываем команду:

Теперь выполняем команду и проверяем что сообщение не отправляется в телеграм, а выводится в терминал.
Теперь запускаем команду в режиме эмуляции:
php bin/console app:telegram:command:start --simulate=1 "$TELEGRAM_TEST_CHAT_ID"
Режим --simulate=1 относится к реализации команды из исходного примера и не является встроенным параметром Symfony. Команда должна самостоятельно обработать этот параметр и вместо HTTP-запроса вывести текст в терминал.
Мы должны увидеть одно жёлтое сообщение и строку из константы MESSAGE_START.
Если всё это происходит, то переходим к следующему этапу.
Этап № 4 – создаём и задаём webhook для обработки диалогов с телеграм ботом
Для начала необходимо зарегистрировать webhook — публичный HTTPS-адрес, на который Telegram будет отправлять POST-запросы с объектами Update. Адрес должен быть доступен серверам Telegram, а не только локальному компьютеру разработчика.
Webhook и получение событий через getUpdates — альтернативные способы обработки обновлений. Одновременно для одного бота их использовать нельзя.
Картинка для понимания:

Предположим, что маршрут нашего приложения будет /api/pub/telegram/webhook/. Для регистрации webhook необходимо указать полный публичный HTTPS-адрес, включающий домен.
Зарегистрировать webhook можно через метод setWebhook Telegram Bot API. В production лучше выполнять этот запрос методом POST, передавая URL обработчика и секретный токен в параметрах запроса, а не публиковать токен бота в адресной строке браузера.
Актуальная документация метода: Telegram Bot API — setWebhook.
Пример регистрации через curl с переменными окружения:
curl --fail-with-body --silent --show-error \
--request POST \
"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
--data-urlencode "url=${TELEGRAM_WEBHOOK_URL}" \
--data-urlencode "secret_token=${TELEGRAM_WEBHOOK_SECRET}"
Для выполнения команды должны быть заданы TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_URL и TELEGRAM_WEBHOOK_SECRET. Значения секретов не следует сохранять в истории команд или выводить в журналы.
Рекомендуется обратить внимание на параметры этого метода: https://core.telegram.org/bots/api#setwebhook
Обратите внимание на параметры setWebhook: secret_token позволяет проверять заголовок X-Telegram-Bot-Api-Secret-Token во входящих запросах, max_connections управляет количеством одновременных подключений, а ip_address позволяет указать фиксированный IP-адрес для доставки событий.
Само по себе указание ip_address не является защитой webhook от поддельных запросов. Для проверки источника используйте секретный токен, HTTPS и при необходимости дополнительные сетевые ограничения.
Теперь в Symfony создаём маршрут /api/pub/telegram/webhook/, принимающий только POST-запросы. Для новых проектов используем PHP-атрибут #[Route] вместо устаревших примеров с аннотациями. Обработчик должен проверить секретный заголовок до разбора сообщения и не выполнять действия для запросов с неверным токеном.

В исходном примере контроллер вызывает Symfony-команду, передавая параметры из JSON-объекта Update. Такой подход позволяет повторно использовать обработчик и запускать его из консоли.
Однако для нового проекта не всегда стоит запускать консольное приложение из HTTP-контроллера. Более простой вариант — вынести бизнес-логику в отдельный сервис, а из контроллера и Symfony-команды вызывать один и тот же метод. Это упрощает тестирование и разделяет транспортный слой Telegram и логику диалога.
Для чтения параметров запроса можно использовать json_decode() с режимом исключений. Например:
use Symfony\Component\HttpFoundation\Request;
$data = json_decode(
$request->getContent(),
true,
512,
JSON_THROW_ON_ERROR
);
if (!is_array($data)) {
throw new \UnexpectedValueException('Invalid Telegram update');
}
$chatId = $data['message']['chat']['id'] ?? null;
$text = $data['message']['text'] ?? null;
Этот пример предполагает, что $request — экземпляр Request, полученный контроллером Symfony. Проверку типов, секретного токена и обязательных полей необходимо выполнить до обработки команды.

При использовании json_decode() мы получаем обычные PHP-массивы. Их структуру и типы значений необходимо проверять самостоятельно либо с помощью DTO и Symfony Validator.
При этом десериализация в объект сама по себе не гарантирует корректность данных: ограничения и правила валидации нужно задавать отдельно. Для небольшого webhook-обработчика ручная проверка нескольких обязательных полей может быть вполне достаточной.
Пример защищённого webhook-контроллера для современного Symfony
Ниже — самостоятельный пример обработки /start, проверки формата кода и подтверждения. Для простоты актуальность кода проверяется через переменную окружения TELEGRAM_CONFIRMATION_CODE. В реальном проекте вместо неё понадобится хранилище одноразовых кодов с привязкой к пользователю, сроком действия, ограничением попыток и атомарным погашением кода.
Установите HTTP-клиент Symfony:
composer require symfony/http-client
Файл src/Controller/TelegramWebhookController.php:
<?php
declare(strict_types=1);
namespace App\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class TelegramWebhookController extends AbstractController
{
private readonly HttpClientInterface $httpClient;
public function __construct(
#[Autowire('%env(TELEGRAM_BOT_TOKEN)%')]
private readonly string $botToken,
#[Autowire('%env(TELEGRAM_WEBHOOK_SECRET)%')]
private readonly string $webhookSecret,
#[Autowire('%env(TELEGRAM_CONFIRMATION_CODE)%')]
private readonly string $confirmationCode,
) {
$this->httpClient = HttpClient::create();
}
#[Route(
path: '/api/pub/telegram/webhook/',
name: 'telegram_webhook',
methods: ['POST']
)]
public function __invoke(Request $request): JsonResponse
{
$receivedSecret = $request->headers->get(
'X-Telegram-Bot-Api-Secret-Token',
''
);
if (!hash_equals($this->webhookSecret, $receivedSecret)) {
return new JsonResponse(['ok' => false], 403);
}
try {
$update = json_decode(
$request->getContent(),
true,
512,
JSON_THROW_ON_ERROR
);
} catch (\JsonException) {
return new JsonResponse(['ok' => false], 400);
}
if (!is_array($update)) {
return new JsonResponse(['ok' => false], 400);
}
$message = $update['message'] ?? null;
if (!is_array($message)) {
return new JsonResponse(['ok' => true]);
}
$chatId = $message['chat']['id'] ?? null;
$text = $message['text'] ?? null;
if (!is_int($chatId) || !is_string($text)) {
return new JsonResponse(['ok' => true]);
}
$text = trim($text);
if (preg_match('~^/start(?:@\\w+)?(?:\\s|$)~u', $text) === 1) {
$answer = 'Привет! Введите код в формате XXX-XXX.';
} elseif (preg_match('/^\\d{3}-\\d{3}$/D', $text) !== 1) {
$answer = 'Неверный формат. Введите код XXX-XXX.';
} elseif (hash_equals($this->confirmationCode, $text)) {
$answer = 'Код верный!';
} else {
$answer = 'Код не найден или уже не действует.';
}
try {
$response = $this->httpClient->request(
'POST',
'https://api.telegram.org/bot' . $this->botToken . '/sendMessage',
[
'json' => [
'chat_id' => $chatId,
'text' => $answer,
],
'timeout' => 10,
]
);
$result = $response->toArray(false);
if ($response->getStatusCode() !== 200
|| ($result['ok'] ?? false) !== true) {
throw new \RuntimeException('Telegram API error');
}
} catch (\Throwable) {
return new JsonResponse(['ok' => false], 503);
}
return new JsonResponse(['ok' => true]);
}
}
В окружении приложения должны быть заданы переменные TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET и TELEGRAM_CONFIRMATION_CODE. Последняя предназначена только для демонстрации.
Ограничения примера: состояние диалога здесь не сохраняется, секрет проверки кода общий, отсутствуют ограничение числа попыток, дедупликация update_id и очередь отправки сообщений. Поэтому пример подходит для демонстрации HTTP-интеграции, но не является готовой системой подтверждения пользователей. При переходе к production эти механизмы обязательны.
На этом этапе наш бот сможет уже отвечать на команду /start , и при этом мы сможем тестировать наш код локально без взаимодействия с API телеграм.
Этап № 5 – обработка ввода и контекст общения
Теперь добавим команду обработки ввода кода, проверки его формата и проверки его актуальности. Для этого создадим Symfony-команду, чтобы её можно было вызывать вот так:
Команду из исходной архитектуры можно запускать следующим образом:
php bin/console app:telegram:command:dialog "$TELEGRAM_TEST_CHAT_ID" '123-123'
Здесь TELEGRAM_TEST_CHAT_ID — переменная окружения с идентификатором тестового чата. Команда должна быть зарегистрирована в проекте, а её аргументы — соответствовать реализации DialogCommand.
Команду назовём DialogCommand, потому что она будет реагировать на любой ввод пользователя. Для этого добавим обработку этой команды в контроллере-обработчике веб-хука /api/pub/telegram/webhook/.

Теперь текстовые сообщения передаются на обработку в app:telegram:command:dialog.
Важно: Telegram может присылать не только текст, но и изображения, документы, голосовые сообщения и другие типы событий. В таких случаях поле message.text отсутствует. Также у объекта Update бывают разные типы содержимого, поэтому нельзя предполагать, что любое событие содержит message. В нашем учебном примере обработку медиа и других типов обновлений пропускаем.
Основной код DialogCommand:

На что тут следует обратить внимание?
- В
switchобрабатывается контекст диалога — его текущее состояние. - Если пользователь уже прошёл проверку кода, обработчик может перейти к следующему сценарию общения. В исходном примере это ответ «Реакция на сообщение {исходное_сообщение}».
TelegramDialogContext— сущность базы данных, связанная с идентификатором чата. Если записи нет, она создаётся в состоянииSTATE_START.- Для использования такого подхода в production необходимо учитывать повторную доставку обновлений, одновременную обработку запросов и уникальность записи по
chatId.


В этой сущности можно хранить состояние диалога. Для поля chatId необходимо задать уникальное ограничение на уровне базы данных. Это позволит находить контекст пользователя и менять его состояние по мере выполнения сценария.
Если бот работает не только в личных сообщениях, модель состояния следует продумать отдельно: в групповых чатах один chatId может соответствовать нескольким пользователям. Для сложных сценариев может понадобиться составной ключ из идентификаторов чата и пользователя.
Итоги
Подход с Symfony-командами и отдельными сервисами позволяет реализовать различные сценарии: подтверждение заявок, уведомления, сбор данных и взаимодействие с внешними API. При необходимости ту же бизнес-логику можно подключить к другим мессенджерам, заменив транспортный слой. Какие существуют альтернативы?
Для интеграции Telegram с современным Symfony можно использовать Symfony Notifier и пакет symfony/telegram-notifier. Этот вариант удобен, если основная задача бота — отправлять уведомления. Для сложных диалогов, обработки webhook и хранения пользовательского состояния всё равно понадобится дополнительная логика.
Существует и библиотека BotMan, предназначенная для создания ботов под разные платформы. Однако перед использованием в новом проекте нужно отдельно проверить активность разработки, совместимость с текущими версиями PHP и Symfony, состояние драйвера Telegram и поддержку необходимых методов API. Сам факт существования репозитория не гарантирует, что библиотека подходит для production.
А что с другими мессенджерами в России?
При использовании Telegram в России необходимо учитывать возможные ограничения отдельных функций и доступности сервиса. Поэтому при проектировании критически важного бизнес-процесса не стоит делать Telegram единственным каналом коммуникации. Желательно предусмотреть альтернативный способ получения уведомлений и взаимодействия с пользователями.
У мессенджера MAX есть собственный Bot API для создания ботов и интеграций. Это отдельный API со своей моделью событий, авторизацией и требованиями к подключению. Нельзя просто заменить адрес Telegram API на MAX и ожидать, что существующий код заработает.
Если приложение должно поддерживать несколько мессенджеров, стоит разделить бизнес-логику, хранение состояния диалога и транспортные адаптеры. Тогда подключение нового канала не потребует переписывания всей системы.
У подхода на стандартных компонентах Symfony есть практическое преимущество: он не требует дополнительного фреймворка для ботов и позволяет использовать привычные сервисы, dependency injection, консольные команды и маршруты.
Для нового проекта мы рекомендуем отделять обработку команд пользователя от Telegram API. Контроллер принимает событие, сервис выполняет бизнес-логику, а отдельный клиент отвечает за отправку сообщений. Такой код проще тестировать, поддерживать и переносить на другие каналы связи.
Можно ли ускорить разработку Telegram-бота с помощью ИИ?
ИИ-инструменты помогают писать Symfony-команды, контроллеры, клиенты API и автоматические тесты. Но сгенерированный код необходимо проверять: нейросеть может предложить небезопасное хранение токенов, пропустить проверку входящих запросов или не учесть повторную доставку событий. Особенно это важно для ботов, работающих с подтверждением операций, заказами и персональными данными. За архитектуру, корректность бизнес-логики, безопасность и поддержку отвечают разработчики, а за выполнение применимых требований 152-ФЗ — оператор персональных данных. Поэтому даже простой бот, созданный с помощью ИИ, перед запуском требует ревью кода и тестирования реальных сценариев работы.
P.S. Если вы планируете автоматизировать обработку заявок, уведомления или внутренние процессы компании, в NJ Soft мы разрабатываем такие интеграции на Symfony и других технологиях.





