Как устроена привязка
Ссылка вида https://t.me/имя_бота?start=код передаёт боту параметр команды /start. Сам переход ещё не означает завершённую привязку: приложению нужно получить соответствующее обновление, а пользователю — подтвердить выбранный аккаунт.
Сайт создаёт случайный код для вошедшего пользователя и хранит только его хеш.
Бот получает /start с кодом и сохраняет Telegram-аккаунт как кандидата.
Личный кабинет показывает кандидата; пользователь проверяет его и подтверждает подключение.
Только подтверждённая связь используется для уведомлений.
Это подключение уведомлений к уже существующей учётной записи, а не вход на сайт через Telegram. Не передавайте в ссылке номер заказа, email или простой ID пользователя вместо случайного секрета. Пересланная ссылка может попасть другому человеку, поэтому одного /start недостаточно.
Что подготовить
Нужны собственный бот, уже работающий HTTPS webhook и сайт с авторизацией. Код ниже — ядро интеграции для PHP 8.2+ на 64-битной системе, PDO и SQLite. Он не создаёт регистрацию, маршруты и формы: их подключают к существующему приложению. Схема рассчитана на одного бота и одну связь Telegram с аккаунтом сайта.
Все операции кабинета — создание ссылки, подтверждение и отключение — выполняйте через POST с проверкой авторизации и CSRF. userId берите из серверной сессии, а не из поля формы. Ограничьте частоту создания заявок и попыток их подтверждения.
Если обновления ещё не приходят, сначала настройте и проверьте webhook
Храните SQLite-файл вне публичного каталога. Создайте таблицы один раз в новой тестовой БД. Для MySQL/PostgreSQL адаптируйте схему и транзакционные блокировки; данный пример SQL проверяется именно на SQLite.
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
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');
Создаём одноразовую ссылку
В обработчике кнопки кабинета вызовите createLink с ID вошедшего пользователя и username своего бота без @. 24 случайных байта превращаются в 48 допустимых для start символов. Заявка действует десять минут; новая ссылка заменяет прежние заявки этого пользователя.
<?php
declare(strict_types=1);
function createLink(PDO $db, int $userId, string $botUsername): string
{
if ($userId < 1 || !preg_match('/\A[A-Za-z0-9_]+\z/', $botUsername)) {
throw new InvalidArgumentException('Проверьте пользователя и имя бота');
}
$token = bin2hex(random_bytes(24));
$db->beginTransaction();
try {
$db->prepare('DELETE FROM telegram_link_requests WHERE user_id = ?')->execute([$userId]);
$db->prepare('INSERT INTO telegram_link_requests (token_hash, user_id, expires_at) VALUES (?, ?, ?)')
->execute([hash('sha256', $token), $userId, time() + 600]);
$db->commit();
} catch (Throwable $e) {
$db->rollBack();
throw $e;
}
return 'https://t.me/'.$botUsername.'?start='.$token;
}
Выведите полученную ссылку в кнопке, экранируя HTML-атрибут штатными средствами шаблонизатора. Не записывайте полный URL и команду /start в логи и аналитику: код даёт возможность предъявить Telegram-аккаунт для привязки. Не включайте сторонние виджеты на страницу с секретной ссылкой.
Ожидаемый результат: появилась одна заявка с хешем и сроком действия, а в ссылке находится исходный код. Если кнопка ведёт не к вашему боту, исправьте username до дальнейшей проверки.
Получаем Telegram-аккаунт из webhook
Для прямого webhook Telegram сначала сравните заголовок X-Telegram-Bot-Api-Secret-Token со своим секретом, заданным при setWebhook. Если секрет не задан в приложении или не совпал, отклоните запрос. После этого разберите исходное тело JSON и передайте массив в captureCandidate. Не доверяйте JSON, который посетитель отправил на открытый URL без проверки.
<?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
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, но не прочтение его человеком.