Обработка start-payload в Telegram на PHP: маппинг в БД, безопасность и лимиты

Технология 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:

  1. Opaque-токены (UUID / random hash): Ссылка содержит случайный hex-идентификатор из 16–32 символов (например, lead_id = bin2hex(random_bytes(16))), который заранее сохраняется в таблице БД pending_payloads вместе со сроком жизни (TTL), флагом одноразового использования (is_used) и целевыми параметрами.
  2. 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 в продакшене

  1. Формат данных: Строго проверяйте incoming payload на соответствие лимиту 64 байт и регулярному выражению /^[A-Za-z0-9_-]+$/.
  2. Криптографическая проверка: Никогда не передавайте права доступа или скидки в открытом виде (?start=discount100). Используйте одноразовые токены из БД или HMAC-подпись.
  3. Разделение FSM и Deep Links: При получении команды /start с параметром сбрасывайте незавершенные шаги ввода пользователя, чтобы старый контекст не искажал обработку новой ссылки.
  4. Идемпотентность и таймауты: Принимайте webhook мгновенно (отдавая 200 OK), а задачи обработки привязок сущностей при необходимости выносите в асинхронные очереди (Laravel Queue, Yii Queue).

Если вам нужна профессиональная разработка сложных ботов и Mini Apps, обратитесь к специалистам BotCreator.

Новые статьи — в Telegram

Разбираем, что автоматизировать в бизнесе и как это работает на практике. Без спама.