Используем Symfony для создания Telegram-бота

Веб-разработка
29 августа 2023
15 мин чтения
Используем Symfony для создания Telegram-бота

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

Для этого нам надо зайти в чат с @BotFather и выполнить команду /newbot.

Используем Symfony для создания Telegram-бота - изображение 1

Затем ввести имя бота и его никнэйм (username).

После этого в сообщении получим HTTP API token вида

Используем Symfony для создания Telegram-бота - изображение 0

Этап № 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 для создания Telegram-бота - изображение 2

В современных Symfony-приложениях переменную окружения можно внедрить непосредственно в сервис с помощью атрибута #[Autowire] либо настроить аргумент через config/services.yaml. Необязательно сначала переносить токен в общий ParameterBagInterface.

Например, для класса сервиса можно использовать конструктор:

use Symfony\Component\DependencyInjection\Attribute\Autowire;

public function __construct(
    #[Autowire('%env(TELEGRAM_BOT_TOKEN)%')]
    private readonly string $token,
) {
}

Этот фрагмент показывает внедрение зависимости; полный пример сервиса отправки сообщений приведён ниже.

Используем Symfony для создания Telegram-бота - изображение 3

Этап № 3 – создаём отправитель сообщений и проверяем отправку сообщений в Telegram.

Теперь, когда у нас есть токен, следует его проверить и отправить сообщение куда-либо, например себе в личные сообщения. Но как узнать свой chat_id?

Для отправки личного сообщения боту нужен идентификатор чата — chat_id. Обычный @username пользователя не является универсальной заменой этого идентификатора: бот не может произвольно начинать личную переписку с любым пользователем Telegram.

Для тестирования сначала откройте бота и нажмите «Запустить». Затем получите обновления через getUpdates и найдите message.chat.id. Если для бота уже настроен webhook, метод getUpdates работать одновременно с ним не будет: необходимо использовать получаемые webhook-события либо временно отключить webhook.

  1. Запускаем общение с ботом через кнопку «Запустить» и отправляем ему любое текстовое сообщение.
  2. Идём по HTTP API ссылке – можно через браузер, но я в примере буду использовать curl + jq и терминал.
Используем Symfony для создания Telegram-бота - изображение 4

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

Используем Symfony для создания Telegram-бота - изображение 5

В ответе Telegram Bot API находим message.chat.id. Это идентификатор чата, который будем использовать для тестирования отправки сообщений. Не путайте его с message.from.id: в личном диалоге они обычно совпадают, но в группах и других типах чатов могут различаться.

Если сохраняете идентификаторы в базе данных, используйте тип, который способен вместить значения Telegram ID. Не следует рассчитывать на обычный 32-битный integer.

Теперь идём в Symfony и создаём «сервис отправки сообщений в телеграм».

Создаём файл src/Service/TelegramSender.php с кодом:

Используем Symfony для создания Telegram-бота - изображение 6

Сервис отправки сообщений должен обрабатывать не только HTTP-ошибки, но и ошибки соединения, тайм-ауты и некорректные ответы API. В Telegram успешный HTTP-ответ необходимо дополнительно проверять по полю ok. Логировать полный URL с токеном или секретные данные запроса нельзя.

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

На данном этапе нужно убедиться только в возможности отправки сообщений.

Создаём код («Symfony команду»), в которой протестируем отправку сообщений и затем будем использовать эту команду для обработки запуска бота (/start).

Используем Symfony для создания Telegram-бота - изображение 7

Идём в терминал и вызываем команду:

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

php bin/console app:telegram:command:start "$TELEGRAM_TEST_CHAT_ID"

Команда сработает при условии, что в проекте уже зарегистрирована соответствующая Symfony-команда, показанная выше.

Если сообщение отправляется, то необходимо «допилить код» так, чтобы при передаче «параметра эмуляции отправки сообщения» сообщение не уходило по-настоящему, а лишь выводило результат в терминал. Это поможет нам отлаживать и тестировать приложение на различных условиях без спама в настоящего бота.

Для этого допишем код так:
src/Service/TelegramSender.php – изменения отмечены красными точками:

Используем Symfony для создания Telegram-бота - изображение 8

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

Используем Symfony для создания Telegram-бота - изображение 9

Теперь выполняем команду и проверяем что сообщение не отправляется в телеграм, а выводится в терминал.

Теперь запускаем команду в режиме эмуляции:

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 — альтернативные способы обработки обновлений. Одновременно для одного бота их использовать нельзя.

Картинка для понимания:

Используем Symfony для создания Telegram-бота - изображение 10

Предположим, что маршрут нашего приложения будет /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 для создания Telegram-бота - изображение 11

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

Используем Symfony для создания Telegram-бота - изображение 12

При использовании 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/.

Используем Symfony для создания Telegram-бота - изображение 13

Теперь текстовые сообщения передаются на обработку в app:telegram:command:dialog.

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

Основной код DialogCommand:

Используем Symfony для создания Telegram-бота - изображение 14

На что тут следует обратить внимание?

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

В этой сущности можно хранить состояние диалога. Для поля 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 и других технологиях.

Редакция NJ Soft
Редакция NJ Soft
Редактор блога

Поделиться:

Нужна разработка или поддержка проекта?

Разрабатываем веб-сервисы и мобильные приложения, дорабатываем и поддерживаем существующие проекты. Расскажите о задаче — предложим решение.