← Все публикации

MORLIX JOURNAL

Разработка и интеграции

Как подключить Telegram Bot API к сайту

Morlix MCP 5 просмотров

Пошагово подключаем Telegram Bot API к сайту: создаём бота, получаем chat_id, отправляем уведомления с PHP и защищаем заявки.

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

В этом руководстве разберём настройку бота, получение идентификатора чата, пример отправки на PHP и проверку ошибок. Пример предназначен для уведомлений команды, а не для отправки личных сообщений посетителям без их участия. Официальное описание методов и полей доступно в документации Telegram Bot API.

Как работает связка сайта и бота

У бота есть секретный токен, который выдаёт BotFather. Приложение использует его при HTTPS-запросах к Bot API. Для исходящего сообщения нужны метод sendMessage, идентификатор получателя chat_id и текст. Бот доставляет сообщение туда, где ему разрешено писать: например, в личный чат сотрудника или в группу, участником которой он является.

Важно разделять два направления. Уведомление о форме — исходящий запрос сайта к Telegram. А если бот должен отвечать на команды, приложению также необходимо получать входящие обновления через webhook или long polling. Настраивать webhook ради одной исходящей заявки не требуется. Принципы обработки входящих событий и повторной доставки подробнее разобраны в статье о вебхуках.

Что подготовить перед подключением

  • Сервер с HTTPS и возможностью выполнять исходящие HTTPS-запросы.
  • Бота, созданного через официальный аккаунт @BotFather, и отдельный тестовый чат.
  • Хранилище для заявок: базу данных или существующую CRM.
  • Секретное хранилище или переменные окружения для токена и chat_id.
  • Возможность посмотреть серверные журналы без вывода секретов и персональных данных.

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

Осьминог охраняет сервер и ключ доступа бота

Шаг 1. Создайте бота и защитите токен

Откройте в Telegram официальный аккаунт @BotFather, выполните команду создания бота и следуйте его подсказкам. Сохраните выданный токен в секретном хранилище окружения приложения. Токен даёт контроль над ботом, поэтому не помещайте его в JavaScript страницы, HTML, репозиторий, скриншоты или сообщения об ошибках. Для тестов удобно создать отдельного бота, чтобы экспериментальная настройка не мешала рабочему каналу.

Если токен утёк, отзовите его через BotFather, выпустите новый и обновите секреты приложения. Проверьте журналы и историю изменений на наличие копий. Смена пароля администратора сайта сама по себе не отзывает токен бота. Разграничение доступа и хранение ключей полезно рассматривать как часть общей стратегии работы с токенами интеграций.

Шаг 2. Получите chat_id и проверьте права

Для личного чата сотрудник сначала открывает бота и нажимает Start или отправляет ему сообщение. Для группы добавьте бота в нужную группу и убедитесь, что ему разрешено писать. Затем можно временно получить входящее обновление методом getUpdates и найти идентификатор в объекте соответствующего чата. Идентификатор группы может быть отрицательным: сохраняйте его целиком как строку, не удаляя знак.

Важное ограничение: getUpdates и webhook не используются одновременно для получения обновлений одного бота. Если у рабочего бота уже настроен webhook, не отключайте его ради теста: используйте отдельного тестового бота либо найдите идентификатор в обработчике входящих событий. Запросы к Bot API содержат токен в адресе, поэтому не публикуйте их целиком и не записывайте в журналы веб-сервера.

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

Шаг 3. Отправьте тестовое сообщение с сервера

Ниже минимальный пример PHP с расширением cURL. Переменные TELEGRAM_BOT_TOKEN и TELEGRAM_CHAT_ID приложение получает из окружения сервера. Не вставляйте реальные значения в исходный код. Сообщение отправляется обычным текстом: это избавляет пример от ошибок разметки при пользовательском вводе.

<?php
function notifyTelegram(string $message): bool {
    $token = getenv('TELEGRAM_BOT_TOKEN');
    $chatId = getenv('TELEGRAM_CHAT_ID');
    if (!$token || !$chatId) {
        error_log('Telegram configuration is missing');
        return false;
    }

    $handle = curl_init('https://api.telegram.org/bot' . $token . '/sendMessage');
    curl_setopt_array($handle, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query([
            'chat_id' => $chatId,
            'text' => $message,
        ]),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 10,
    ]);
    $body = curl_exec($handle);
    $status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
    curl_close($handle);

    $result = is_string($body) ? json_decode($body, true) : null;
    if ($status < 200 || $status >= 300 || !is_array($result) || empty($result['ok'])) {
        error_log('Telegram notification failed; HTTP ' . $status);
        return false;
    }
    return true;
}

$sent = notifyTelegram('Тестовое уведомление с сайта');

Это проверка связи, а не законченный обработчик формы. Она проверяет HTTP-ответ и поле ok, ограничивает ожидание и не пишет URL с токеном в лог. В реальном приложении вызывайте функцию из фонового обработчика после сохранения заявки. Не используйте ответ Telegram как единственное доказательство того, что заявка записана: сначала убедитесь в сохранении на вашей стороне.

Шаг 4. Подключите форму и очередь

Когда посетитель отправляет форму, сервер должен проверить обязательные поля и их длину, применить защиту от спама и сохранить заявку. Дальше создайте задачу уведомления с внутренним идентификатором заявки. Очередь обработает её отдельно и отправит в Telegram сообщение вроде «Новая заявка № 1842. Откройте карточку в системе». При необходимости добавьте только согласованный минимальный набор данных.

Фоновая очередь полезна, потому что внешняя сеть может отвечать медленно или временно отказывать. Посетителю не нужно ждать сетевой тайм-аут, а ваша команда не потеряет заявку из-за кратковременного сбоя. Храните статус задачи, число попыток и время последней ошибки; ограничивайте частоту повторов и включите уведомление администратору, если доставка не восстановилась.

Почему повторная отправка требует осторожности

Если Telegram вернул явную ошибку до принятия сообщения, задачу можно обработать по правилам очереди и документации API. Но тайм-аут или обрыв соединения не доказывает, что сообщение не доставлено: сервер мог принять запрос, а ответ не дошёл. Слепой повтор способен создать дубль. Отмечайте такой результат как неопределённый и сверяйте его с доступными данными доставки; внутренний номер заявки в сообщении помогает людям заметить повтор.

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

Осьминог рядом с очередью сообщений и уведомлениями

Защита формы и персональных данных

Токен должен быть доступен только серверному процессу, которому он нужен. Ограничьте права на конфигурационные файлы и доступ к чатам, используйте HTTPS, регулярно обновляйте зависимости и проверяйте резервные каналы уведомлений. Не передавайте токен в клиентские аналитические события и не показывайте пользователю подробный ответ внешнего API.

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

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

Если бот должен принимать сообщения

Для двусторонней интеграции отдельно спроектируйте получение обновлений. При webhook Telegram отправляет обновления на публичный HTTPS-адрес приложения; long polling предполагает, что приложение регулярно запрашивает обновления. Выберите один способ для конкретного бота и не отключайте существующий webhook, пока не понимаете последствия.

Для webhook проверьте секретный заголовок, если он настроен через secret_token при регистрации адреса, и сравнивайте значение безопасным способом. Ограничьте размер тела запроса, проверяйте структуру данных и быстро подтверждайте приём; длительную работу переносите в очередь. Храните идентификаторы обработанных обновлений, чтобы повторная доставка не приводила к повторному действию. Секрет вебхука отличается от токена бота; храните оба отдельно.

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

Диагностика: что проверять при ошибке

  • Нет сообщения, но заявка сохранена. Посмотрите статус задачи, HTTP-код и ответ API без токена; проверьте исходящий доступ сервера к Telegram.
  • Ошибка авторизации. Убедитесь, что используется действующий токен нужного бота и секрет обновлён во всех экземплярах приложения.
  • Чат не найден или запись запрещена. Перепроверьте chat_id, знак идентификатора группы, участие бота и его права; для личного чата пользователь должен начать диалог.
  • Сообщение пришло дважды. Проверьте повторную отправку формы, повтор задачи после тайм-аута и обработку входящих обновлений.
  • Форма работает медленно. Убедитесь, что обращение к Telegram вынесено в очередь и не блокирует ответ посетителю.
  • Нет входящих обновлений. Проверьте выбранный способ получения, доступность webhook и то, что другой обработчик не забирает обновления.

Чек-лист перед запуском

  1. Тестовый и рабочий боты разделены, секреты не попали в код и журналы.
  2. Заявка сохраняется до уведомления, при ошибке Telegram данные не исчезают.
  3. Рабочий chat_id и права бота проверены тестовой отправкой.
  4. Данные в сообщении минимальны, доступ к чату и карточке заявки ограничен.
  5. Очередь контролирует ошибки, а неопределённый результат не вызывает бесконечных повторов.
  6. Форма защищена от спама, настроен мониторинг и ответственный за сбои.
  7. Если нужны входящие сообщения, отдельно проверены webhook, секрет и защита от повторной обработки.

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

← Вернуться ко всем публикациям