Перейти к содержанию
14 минут чтения
Тема: Интеграции PHP · Deep Linking · Личный кабинет

Как привязать Telegram к аккаунту на сайте и отправлять личные уведомления

Для примера возьмём интернет-магазин с готовым личным кабинетом. Покупатель нажимает «Подключить Telegram», запускает бота и подтверждает подключение на сайте. После этого магазин сможет отправлять ему статус его заказов. Разберём, как связать два аккаунта, не заставляя человека искать chat_id.

Как устроена привязка

Ссылка вида https://t.me/имя_бота?start=код передаёт боту параметр команды /start. Сам переход ещё не означает завершённую привязку: приложению нужно получить соответствующее обновление, а пользователю — подтвердить выбранный аккаунт.

  • Сайт создаёт случайный код для вошедшего пользователя и хранит только его хеш.

  • Бот получает /start с кодом и сохраняет Telegram-аккаунт как кандидата.

  • Личный кабинет показывает кандидата; пользователь проверяет его и подтверждает подключение.

  • Только подтверждённая связь используется для уведомлений.

Это подключение уведомлений к уже существующей учётной записи, а не вход на сайт через Telegram. Не передавайте в ссылке номер заказа, email или простой ID пользователя вместо случайного секрета. Пересланная ссылка может попасть другому человеку, поэтому одного /start недостаточно.

Механизм Deep Linking в документации Telegram

Что подготовить

Нужны собственный бот, уже работающий HTTPS webhook и сайт с авторизацией. Код ниже — ядро интеграции для PHP 8.2+ на 64-битной системе, PDO и SQLite. Он не создаёт регистрацию, маршруты и формы: их подключают к существующему приложению. Схема рассчитана на одного бота и одну связь Telegram с аккаунтом сайта.

Все операции кабинета — создание ссылки, подтверждение и отключение — выполняйте через POST с проверкой авторизации и CSRF. userId берите из серверной сессии, а не из поля формы. Ограничьте частоту создания заявок и попыток их подтверждения.

Если обновления ещё не приходят, сначала настройте и проверьте webhook

Храните SQLite-файл вне публичного каталога. Создайте таблицы один раз в новой тестовой БД. Для MySQL/PostgreSQL адаптируйте схему и транзакционные блокировки; данный пример SQL проверяется именно на SQLite.

SQL · таблицы учебной интеграции
CREATE TABLE telegram_link_requests (
    token_hash TEXT PRIMARY KEY,
    user_id INTEGER NOT NULL,
    expires_at INTEGER NOT NULL,
    candidate_user_id TEXT,
    candidate_chat_id TEXT
);
CREATE TABLE telegram_connections (
    user_id INTEGER PRIMARY KEY,
    telegram_user_id TEXT NOT NULL UNIQUE,
    chat_id TEXT NOT NULL,
    confirmed_at INTEGER NOT NULL
);
PHP · соединение, общее для следующих функций
<?php
declare(strict_types=1);

$databasePath = getenv('TELEGRAM_LINK_DB');
if (!is_string($databasePath) || $databasePath === '') {
    throw new RuntimeException('Задайте абсолютный путь TELEGRAM_LINK_DB вне public');
}
$db = new PDO('sqlite:'.$databasePath, options: [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
$db->exec('PRAGMA busy_timeout = 5000');

Получаем Telegram-аккаунт из webhook

Для прямого webhook Telegram сначала сравните заголовок X-Telegram-Bot-Api-Secret-Token со своим секретом, заданным при setWebhook. Если секрет не задан в приложении или не совпал, отклоните запрос. После этого разберите исходное тело JSON и передайте массив в captureCandidate. Не доверяйте JSON, который посетитель отправил на открытый URL без проверки.

PHP · capture-candidate.php
<?php
declare(strict_types=1);

/** Вызывать только после проверки подлинности webhook.
 *  @param array<string, mixed> $update
 */
function captureCandidate(PDO $db, array $update): bool
{
    $message = $update['message'] ?? null;
    if (!is_array($message) || ($message['chat']['type'] ?? null) !== 'private') {
        return false;
    }
    $text = $message['text'] ?? null;
    $fromId = $message['from']['id'] ?? null;
    $chatId = $message['chat']['id'] ?? null;
    if (!is_string($text) || !is_int($fromId) || !is_int($chatId)
        || $fromId < 1 || $chatId !== $fromId
        || !preg_match('/\A\/start ([a-f0-9]{48})\z/', $text, $match)) {
        return false;
    }
    $query = $db->prepare('UPDATE telegram_link_requests
        SET candidate_user_id = ?, candidate_chat_id = ?
        WHERE token_hash = ? AND expires_at > ? AND candidate_user_id IS NULL');
    $query->execute([(string) $fromId, (string) $chatId, hash('sha256', $match[1]), time()]);
    return $query->rowCount() === 1;
}

Функция принимает только личный диалог и сохраняет ID автора вместе с ID чата. Условие candidate_user_id IS NULL не позволяет повторной доставке или другому предъявителю ссылки заменить уже выбранного кандидата. false означает, что новая кандидатура не сохранена: это может быть обычное сообщение, повтор, истёкшая либо уже предъявленная ссылка.

Для корректного, но уже обработанного события верните успешный HTTP-ответ. При сбое БД верните 5xx, чтобы доставка могла повториться. Подтверждать webhook нужно после завершения записи. Если используете очередь, до HTTP 200 надёжно сохраните событие для обработки.

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

Подтверждаем связь в личном кабинете

Кабинет получает заявку только по user_id из текущей сессии. Покажите числовой Telegram ID кандидата и попросите сверить его с ответом бота. username можно показать дополнительно, но нельзя использовать как постоянный ключ. Если кандидат незнаком, предложите отменить заявку и создать новую ссылку.

Передайте в POST-форме хеш показанной заявки и ID показанного кандидата. Они не заменяют авторизацию и CSRF. Серверная функция повторно проверяет владельца, срок действия и совпадение кандидата; так подтверждение старой формы не применит другую заявку.

PHP · confirm-link.php
<?php
declare(strict_types=1);

function confirmLink(PDO $db, int $userId, string $requestHash, string $expectedTelegramId): void
{
    $db->beginTransaction();
    try {
        $query = $db->prepare('SELECT * FROM telegram_link_requests
            WHERE token_hash = ? AND user_id = ? AND expires_at > ?');
        $query->execute([$requestHash, $userId, time()]);
        $row = $query->fetch(PDO::FETCH_ASSOC);
        if ($row === false || $row['candidate_user_id'] === null
            || $row['candidate_user_id'] !== $expectedTelegramId) {
            throw new RuntimeException('Заявка устарела или аккаунт изменился');
        }
        // Только первичная привязка. Заменять существующую молча нельзя.
        $db->prepare('INSERT INTO telegram_connections
            (user_id, telegram_user_id, chat_id, confirmed_at) VALUES (?, ?, ?, ?)')
            ->execute([$userId, $row['candidate_user_id'], $row['candidate_chat_id'], time()]);
        $db->prepare('DELETE FROM telegram_link_requests WHERE user_id = ?')->execute([$userId]);
        $db->commit();
    } catch (Throwable $e) {
        $db->rollBack();
        throw $e;
    }
}

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

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

Отправляем уведомления и отключаем подключение

Перед отправкой получите chat_id из telegram_connections по владельцу заказа. Не принимайте адрес получателя из запроса клиента. Отправляйте только те сведения, на получение которых пользователь согласился; начните с короткого тестового уведомления без персональных данных.

Отправку через очередь и обработку ошибок разбирает руководство для Laravel

Добавьте в кабинет кнопку «Отключить Telegram». В одной транзакции удалите связь и все незавершённые заявки текущего пользователя. Очередь должна повторно проверять наличие связи перед фактической отправкой. Уже отправленный сетевой запрос отозвать таким отключением нельзя.

Для переподключения используйте новый код и повторное подтверждение. Если пользователь заблокировал бота, остановите уведомления этому получателю; не повторяйте бесконечно одну и ту же ошибку. Отмена подписки в приложении и блокировка бота — разные события.

Если используете BotGate

Deep link по-прежнему ведёт к username вашего Telegram-бота. BotGate передаёт обновления, но не знает, какому аккаунту вашего магазина принадлежит код: таблицы и проверки остаются в вашем приложении.

Для webhook BotGate проверяйте X-BotGate-Signature: HMAC-SHA256 от исходных байтов тела с webhook-секретом бота. Не заменяйте эту проверку сравнением Telegram secret_token и не вычисляйте подпись от заново собранного JSON. После проверки captureCandidate получает тот же массив Update.

Проверка подписи и формат webhook BotGate

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

Проверяем подключение

  • Новый пользователь проходит все шаги; до подтверждения записи в telegram_connections нет.

  • Повторный /start и /start от другого Telegram-аккаунта не заменяют кандидата.

  • Истёкший код, сообщение из группы и запрос с неверным webhook-секретом не создают связь.

  • Подтверждение из чужого кабинета, старой формы или без CSRF отклоняется.

  • Повторное подтверждение и конфликт уникальности не создают вторую связь.

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

Проверьте и аварийный сценарий: временно недоступная тестовая БД не должна приводить к HTTP 200 до сохранения события. Успешный вызов sendMessage подтверждает принятие сообщения Telegram, но не прочтение его человеком.

Источники

Telegram: Deep Linking

Telegram: setWebhook и secret_token

PHP: random_bytes

PHP: транзакции PDO