Технология Deep Linking в Telegram Bot API позволяет передавать контекстные параметры при первом запуске или перезапуске бота по ссылке вида t.me/BotUsername?start=payload. Это базовый инструмент для отслеживания источников трафика, привязки CRM-сущностей, активации промокодов или стартовых офферов. Однако на практике разработчики часто сталкиваются с техническими ограничениями формата, некорректным смешиванием payload с текущим состоянием диалога (FSM) и уязвимостями к подмене данных со стороны пользователя.
В этой статье мы подробно разберём, как проектировать архитектуру обработки start-payload на PHP, защитить параметры от подделки и корректно связывать их с записями в вашей базе данных.
Жесткие лимиты Telegram API на start-payload
Telegram накладывает строгие технические ограничения на значение параметра start в URL:
- Максимальная длина: 64 байта (символа).
- Допустимые символы: латинские буквы
A-Z,a-z, цифры0-9, а также символы подчёркивания_и дефиса-. - Спецсимволы: пробелы, точки, слэши, знаки равенства и кириллица запрещены. Передача Base64-строк напрямую затруднена из-за символов
+,/и=, поэтому базовый Base64 требует замены на URL-safe вариант (base64url) или предварительной упаковки.
Если пользователь переходит по ссылке t.me/my_bot?start=ref_12345, Telegram отправляет на ваш Webhook объект Update с типом Message, где текстовое содержимое сообщения превращается в строковую команду:
/start ref_12345Если параметр не соответствует правилам API (например, содержит запрещенные символы или длиннее 64 байт), Telegram либо просто проигнорирует параметр, либо отсечет его, превратив команду в простой /start.
payload vs FSM: различие deep link и продолжения диалога
Типичная ошибка при проектировании бота — путать входной start-payload и текущее состояние пошагового диалога (Finite State Machine).
Deep link — это статическая точка входа (stateless trigger). Она сообщает боту намерение пользователя войти с определенным контекстом. В свою очередь, FSM (Finite State Machine) — это динамическое состояние, сохраняемое на сервере (в Redis или БД) для отслеживания шагов диалога (например, WAITING_FOR_PHONE, WAITING_FOR_EMAIL).
Важно: получение входящего
/start payloadдолжно безопасно сбрасывать текущее незавершённое FSM-состояние пользователя или корректно перенаправлять его в новый сценарий. Если пользователь находился в процессе заполнения анкеты и кликнул по рекламной ссылке?start=promo_autumn, бот не должен пытаться распарситьpromo_autumnкак ответ на прошлый вопрос про имя или телефон.
Защита от подмены: HMAC-подпись против opaque-токенов в БД
Так как поле ввода текста в Telegram доступно каждому пользователю, ничто не мешает клиенту вручную вбить в чат команду /start discount_90 или /start role_admin. Если ваша логика доверяет входящей строке без проверки, система станет уязвимой для перебора и подделки бизнес-данных.
Существует два безопасных подхода к формированию payload:
- Opaque-токены (UUID / random hash): Ссылка содержит случайный hex-идентификатор из 16–32 символов (например,
lead_id = bin2hex(random_bytes(16))), который заранее сохраняется в таблице БДpending_payloadsвместе со сроком жизни (TTL), флагом одноразового использования (is_used) и целевыми параметрами. - HMAC-подпись (Stateless payload): Если создавать запись в БД до клика по ссылке невозможно или неэффективно, короткий ID сущности подписывается криптографическим хэшем с использованием приватного ключа сервера.
Пример 1: Генерация защищенной deep-ссылки с HMAC
Ниже представлен PHP-скрипт для генерации компактного signed payload, помещающегося в лимит 64 символов Telegram API:
<?php
declare(strict_types=1);
function generateSecureStartLink(string $botUsername, string $entityType, int $entityId, string $secretKey): string
{
// Формируем полезную нагрузку: e.g. "order_1042"
$rawPayload = sprintf('%s_%d', $entityType, $entityId);
// Генерируем короткую подпись (8 символов sha256)
$hash = substr(hash_hmac('sha256', $rawPayload, $secretKey), 0, 8);
// Итоговый payload: "order_1042_a3f8c9e1" (гарантированно < 64 байт и удовлетворяет regex [A-Za-z0-9_-])
$payload = sprintf('%s_%s', $rawPayload, $hash);
if (strlen($payload) > 64) {
throw new InvalidArgumentException('Start payload exceeds Telegram 64 bytes limit');
}
return sprintf('https://t.me/%s?start=%s', $botUsername, $payload);
}
// Пример использования:
$appSecret = getenv('APP_SECRET_KEY') ?: 'fallback-secret-key-32-chars-len';
$link = generateSecureStartLink('MyServiceBot', 'lead', 8592, $appSecret);
echo $link;
// Вывод: https://t.me/MyServiceBot?start=lead_8592_9f2a71b4
Обработка Webhook, защита и маппинг в БД на PHP
При получении обновления от Telegram через Webhook необходимо соблюдать дисциплину безопасности:
- Валидировать заголовок
X-Telegram-Bot-Api-Secret-Token. - Обеспечить идемпотентность обработки за счет сохранения и проверки
update_idв базе данных или Redis. - Выполнять запросы к Bot API исключительно через
cURLс проверкой HTTP-статуса иjson_last_error().
Пример 2: Приём Webhook, проверка подписи payload и маппинг сущности
Следующий код демонстрирует полную цепочку: валидацию Webhook, защиту от дубликатов update_id, парсинг payload, валидацию HMAC и отправку ответа в Telegram API.
<?php
declare(strict_types=1);
header('Content-Type: application/json');
$botToken = getenv('TELEGRAM_BOT_TOKEN');
$secretToken = getenv('TELEGRAM_SECRET_TOKEN');
$appSecret = getenv('APP_SECRET_KEY');
if (!$botToken || !$secretToken || !$appSecret) {
http_response_code(500);
echo json_encode(['error' => 'Server configuration missing']);
exit;
}
// 1. Проверка Secret Token от Telegram
$headers = getallheaders();
$incomingSecret = $headers['X-Telegram-Bot-Api-Secret-Token'] ?? $headers['x-telegram-bot-api-secret-token'] ?? '';
if (!hash_equals($secretToken, $incomingSecret)) {
http_response_code(403);
echo json_encode(['error' => 'Invalid secret token']);
exit;
}
// 2. Чтение и парсинг Webhook Body
$rawInput = file_get_contents('php://input');
$update = json_decode($rawInput, true);
if (json_last_error() !== JSON_ERROR_NONE || !is_array($update)) {
http_response_code(400);
echo json_encode(['error' => 'Invalid JSON']);
exit;
}
$updateId = $update['update_id'] ?? null;
$message = $update['message'] ?? null;
if (!$updateId || !$message) {
echo json_encode(['status' => 'ignored']);
exit;
}
// 3. Идемпотентность (эмуляция проверки update_id в БД)
if (!isUpdateIdUnique((int)$updateId)) {
echo json_encode(['status' => 'already_processed']);
exit;
}
$chatId = $message['chat']['id'] ?? null;
$text = trim($message['text'] ?? '');
// 4. Анализ команды /start с payload
if (strpos($text, '/start') === 0 && $chatId) {
$parts = explode(' ', $text, 2);
$payload = $parts[1] ?? null;
if ($payload) {
processStartPayload((int)$chatId, $payload, $botToken, $appSecret);
} else {
sendTelegramMessage((int)$chatId, 'Добро пожаловать без контекста!', $botToken);
}
}
echo json_encode(['status' => 'ok']);
/**
* Валидация подписи payload и связывание с БД
*/
function processStartPayload(int $chatId, string $payload, string $botToken, string $appSecret): void
{
// Ожидаемый формат: type_id_hash (например: lead_8592_9f2a71b4)
$payloadParts = explode('_', $payload);
if (count($payloadParts) !== 3) {
sendTelegramMessage($chatId, 'Неверный формат ссылки.', $botToken);
return;
}
[$type, $idStr, $providedHash] = $payloadParts;
$entityId = (int)$idStr;
$rawPayload = sprintf('%s_%d', $type, $entityId);
$expectedHash = substr(hash_hmac('sha256', $rawPayload, $appSecret), 0, 8);
// Timing-safe проверка HMAC для предотвращения утечек по времени
if (!hash_equals($expectedHash, $providedHash)) {
sendTelegramMessage($chatId, 'Ошибка: Ссылка недействительна или была подделана.', $botToken);
return;
}
// В этой точке payload доказан и легитимен
// Выполняем маппинг на сущность БД и сброс прошлого FSM состояния
resetUserFsmState($chatId);
linkUserToEntity($chatId, $type, $entityId);
$responseText = sprintf('Успешно! Вы привязаны к заявке #%d (тип: %s).', $entityId, htmlspecialchars($type));
sendTelegramMessage($chatId, $responseText, $botToken);
}
/**
* Безопасный вызов Telegram API через cURL
*/
function sendTelegramMessage(int $chatId, string $text, string $botToken): bool
{
$url = sprintf('https://api.telegram.org/bot%s/sendMessage', $botToken);
$data = [
'chat_id' => $chatId,
'text' => $text,
'parse_mode' => 'HTML',
];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
CURLOPT_CONNECTTIMEOUT => 3,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
if ($response === false || $httpCode !== 200) {
error_log(sprintf('Telegram API error: HTTP %d, CurlErr: %s', $httpCode, $curlError));
return false;
}
$decoded = json_decode($response, true);
return isset($decoded['ok']) && $decoded['ok'] === true;
}
function isUpdateIdUnique(int $updateId): bool
{
// Реальный метод проверяет `SELECT id FROM processed_updates WHERE update_id = :id`
return true;
}
function resetUserFsmState(int $chatId): void
{
// Очистка сессии в Redis/DB для перевода диалога в начальное состояние
}
function linkUserToEntity(int $chatId, string $type, int $entityId): void
{
// Сохранение связи сущности с Telegram user_id / chat_id в MySQL/PostgreSQL
}
Чек-лист по работе с Deep Links в продакшене
- Формат данных: Строго проверяйте incoming payload на соответствие лимиту 64 байт и регулярному выражению
/^[A-Za-z0-9_-]+$/. - Криптографическая проверка: Никогда не передавайте права доступа или скидки в открытом виде (
?start=discount100). Используйте одноразовые токены из БД или HMAC-подпись. - Разделение FSM и Deep Links: При получении команды
/startс параметром сбрасывайте незавершенные шаги ввода пользователя, чтобы старый контекст не искажал обработку новой ссылки. - Идемпотентность и таймауты: Принимайте webhook мгновенно (отдавая
200 OK), а задачи обработки привязок сущностей при необходимости выносите в асинхронные очереди (Laravel Queue, Yii Queue).
Если вам нужна профессиональная разработка сложных ботов и Mini Apps, обратитесь к специалистам BotCreator.