Как интегрировать Telegram Bot API с сайтом

Интеграция Telegram Bot API с сайтом позволяет связать веб-ресурс с Telegram-ботом. Например, сайт может отправлять уведомления о новых заказах, передавать заявки менеджерам, подтверждать регистрацию, сообщать об изменении статуса доставки или принимать команды от пользователей.

Для подключения потребуются созданный Telegram-бот, токен доступа, серверная часть сайта и обработчик запросов. Рассмотрим, как работает интеграция и что необходимо настроить.

Что такое Telegram Bot API

Telegram Bot API — это программный интерфейс, через который сайт или другое приложение взаимодействует с Telegram-ботом.

С помощью API можно:

• отправлять текстовые сообщения;
• получать сообщения и команды пользователей;
• отправлять изображения, документы и другие файлы;
• создавать кнопки;
• редактировать и удалять сообщения;
• получать информацию о чатах;
• обрабатывать действия пользователей.

Сайт обращается к методам Telegram Bot API через HTTPS-запросы. Для авторизации используется токен бота.

Для чего подключать Telegram-бота к сайту

Интеграция подходит для информационных, коммерческих и сервисных проектов.

Отправка заявок с сайта

После заполнения формы данные можно автоматически отправить в Telegram менеджеру или администратору. В сообщении указывают имя клиента, телефон, электронную почту, выбранную услугу и комментарий.

Уведомления о заказах

Интернет-магазин может сообщать сотрудникам о новых заказах, оплатах, отменах и изменениях статуса доставки.

Авторизация через Telegram

Telegram можно использовать как один из способов идентификации пользователя. При реализации такой функции необходимо проверять полученные данные на сервере, а не доверять параметрам, переданным браузером.

Управление сайтом через бота

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

Такие команды необходимо разрешать только доверенным пользователям.

Что потребуется для интеграции

Перед началом настройки подготовьте:

• Telegram-аккаунт;
• созданного бота;
• токен бота;
• доступ к серверной части сайта;
• HTTPS-соединение;
• идентификатор чата для отправки сообщений;
• язык программирования, работающий на сервере.

Для интеграции подходят PHP, Python, JavaScript, Java, Go и другие языки, поддерживающие HTTP-запросы.

Как создать бота и получить токен

Бот создается через официального служебного бота BotFather.

Последовательность действий:

1. Откройте диалог с BotFather.
2. Отправьте команду /newbot.
3. Укажите отображаемое имя.
4. Придумайте уникальное имя пользователя.
5. Скопируйте полученный токен.

Токен выглядит как длинная строка из цифр и символов. Он предоставляет доступ к управлению ботом, поэтому его нельзя публиковать в статье, отправлять посторонним или хранить в открытом репозитории.

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

Как проверить работу Telegram Bot API

Запросы к API отправляются по адресу следующего вида:

https://api.telegram.org/bot<ТОКЕН>/<МЕТОД>

Вместо <ТОКЕН> указывается токен бота, а вместо <МЕТОД> — название нужного метода.

Для проверки токена используется метод getMe. В случае успешного запроса Telegram возвращает сведения о боте.

Ответ API передается в формате JSON. Поле ok показывает, был ли запрос выполнен успешно. Дополнительные данные находятся в поле result.

Как получить идентификатор чата

Чтобы сайт мог отправить сообщение, необходимо знать chat_id — идентификатор пользователя, группы или канала.

Получение chat_id через getUpdates

Сначала пользователь должен открыть бота и отправить ему сообщение, например команду /start. После этого сервер может запросить новые события методом getUpdates.

В полученном JSON-ответе нужно найти объект chat, внутри которого находится поле id.

Метод getUpdates подходит для тестирования и простых проектов. При активном webhook получать обновления через getUpdates нельзя.

Получение chat_id через webhook

При использовании webhook Telegram самостоятельно отправляет новые события на адрес сайта. Идентификатор чата находится в данных входящего обновления.

Обычно его получают из следующей структуры:

message.chat.id

Структура обновления зависит от типа события. Например, нажатие Inline-кнопки приходит не как обычное сообщение, а как callback-запрос.

Как отправить сообщение с сайта в Telegram

Для отправки текста применяется метод sendMessage. В запросе необходимо передать как минимум два параметра:

• chat_id — получатель;
• text — текст сообщения.

Пример отправки сообщения на PHP

<?php

$token = getenv('TELEGRAM_BOT_TOKEN');
$chatId = getenv('TELEGRAM_CHAT_ID');

$message = "На сайте появилась новая заявка";

$url = "https://api.telegram.org/bot{$token}/sendMessage";

$data = [
    'chat_id' => $chatId,
    'text' => $message
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_TIMEOUT => 10
]);

$response = curl_exec($ch);

if ($response === false) {
    error_log('Ошибка cURL: ' . curl_error($ch));
}

curl_close($ch);

Токен и идентификатор чата в примере загружаются из переменных окружения. Это безопаснее, чем записывать их непосредственно в коде.

Как передать данные из формы сайта

После отправки формы сервер должен проверить входные данные, сформировать сообщение и вызвать метод sendMessage.

Пример текста уведомления:

Новая заявка

Имя: Иван
Телефон: +7 900 000-00-00
Услуга: Консультация
Комментарий: Перезвонить после 18:00

Перед отправкой необходимо:

• проверить обязательные поля;
• ограничить длину значений;
• удалить недопустимые данные;
• защитить форму от автоматического спама;
• не передавать пароли и платежные реквизиты;
• получить согласие пользователя, если обрабатываются персональные данные.

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

Как настроить webhook

Webhook — это HTTPS-адрес на сайте, на который Telegram отправляет обновления бота.

Например, обработчик может находиться по адресу:

https://example.ru/telegram/webhook.php

Адрес регистрируется с помощью метода setWebhook. После настройки Telegram будет отправлять на него POST-запросы с JSON-данными.

Что делает обработчик webhook

Серверный скрипт должен:

1. Получить тело входящего запроса.
2. Преобразовать JSON в объект или массив.
3. Определить тип события.
4. Проверить пользователя или чат.
5. Выполнить нужное действие.
6. Быстро вернуть успешный HTTP-ответ.

Обработчик не должен выполнять длительные операции до отправки ответа. Сложные задачи лучше передавать в очередь или выполнять отдельным процессом.

Как защитить webhook

Для защиты обработчика рекомендуется:

• использовать только HTTPS;
• создать сложный непредсказуемый путь;
• проверять секретный токен webhook;
• ограничивать доступ к административным командам;
• проверять структуру входных данных;
• вести журнал ошибок без записи конфиденциальных данных.

При регистрации webhook можно передать secret_token. Тогда Telegram добавит его в специальный заголовок входящего запроса, а сервер сможет сравнить значение с ожидаемым.

Webhook или getUpdates: что выбрать

Способ	Как работает	Когда подходит
getUpdates	Сервер регулярно запрашивает новые события	Тестирование, локальная разработка, простые проекты
Webhook	Telegram отправляет события на сайт автоматически	Постоянно работающий сайт, быстрые реакции, рабочий проект

Одновременно использовать оба способа получения обновлений нельзя. Если настроен webhook, метод getUpdates не будет применяться для обычного получения событий.

Для интеграции с действующим сайтом чаще выбирают webhook, поскольку сервер получает данные сразу после появления события.

Частые ошибки при интеграции

Неверный или отозванный токен

Проверьте, не появились ли в токене пробелы и используется ли актуальное значение. При утечке токен необходимо отозвать и выпустить новый.

Неправильный chat_id

Бот не сможет отправить сообщение, если указан неверный идентификатор или у него нет доступа к нужному чату.

Пользователь не запускал бота

Бот не может произвольно начать личный диалог с пользователем. Сначала пользователь должен самостоятельно открыть бота и начать взаимодействие.

Webhook не получает запросы

Проверьте HTTPS, доступность обработчика, HTTP-статус ответа и отсутствие перенаправлений или серверных ошибок.

Текущее состояние webhook можно проверить методом getWebhookInfo.

Данные формы отправляются без проверки

Нельзя напрямую объединять содержимое пользовательских полей с командами, запросами к базе или HTML-кодом. Все входные значения должны проходить серверную проверку.

Как проверить готовую интеграцию

После настройки проведите несколько тестов:

1. Отправьте обычную заявку.
2. Проверьте обязательные поля.
3. Отправьте длинный текст и специальные символы.
4. Проверьте повторную отправку формы.
5. Временно укажите неправильный токен.
6. Проверьте журнал ошибок.
7. Убедитесь, что секретные данные не отображаются пользователю.
8. Проверьте доступ к командам бота с другого аккаунта.

Тестирование должно охватывать не только успешный сценарий, но и ошибки Telegram, проблемы сети и некорректные данные.

Часто задаваемые вопросы

Можно ли подключить Telegram Bot API без библиотеки

Да. Telegram Bot API работает через обычные HTTPS-запросы. Специальная библиотека упрощает разработку, но не является обязательной.

Нужен ли отдельный сервер для бота

Не всегда. Обработчик можно разместить на том же сервере, где работает сайт, если хостинг поддерживает серверный код и исходящие HTTPS-запросы.

Можно ли отправлять сообщения в группу

Да. Бота необходимо добавить в группу и предоставить ему права, необходимые для выбранного сценария. Для отправки сообщения также потребуется идентификатор группы.

Где хранить токен бота

Токен следует хранить на сервере в переменной окружения или закрытом конфигурационном файле. Передавать его в JavaScript-код, выполняемый в браузере, нельзя.

Итог

Для интеграции Telegram Bot API с сайтом необходимо создать бота, получить токен, определить chat_id и настроить серверные HTTPS-запросы.

Если сайту нужно только отправлять уведомления, достаточно метода sendMessage. Для приема команд и других событий потребуется webhook или getUpdates. В рабочем веб-проекте обычно используется webhook с HTTPS, секретным токеном и обязательной проверкой входящих данных.

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