Форма сайта → Telegram менеджеру на PHP: lead_id, БД и обработка inline-кнопки «Взять в работу»

Многие разработчики при отправке заявок с сайта в Telegram ограничиваются простой пересылкой текста сообщения в менеджерский чат. Однако при росте объема продаж такой подход быстро приводит к хаосу: менеджеры перебивают друг друга, забирают одних и тех же клиентов или пропускают новые обращения. Нативный способ решить эту проблему — отправлять заявку с интерактивной Inline-кнопкой «Взять в работу» прямо в Telegram.

В этой статье мы построим надежный сценарий на PHP: от генерации криптографически стойкого идентификатора заявки и записи в PostgreSQL/MySQL до корректной обработки Webhook с учетом гонки запросов и строгих лимитов Telegram Bot API.

Схема работы и структура данных

Общий алгоритм взаимодействия состоит из двух ключевых фаз:

  1. Фаза 1 (Сайт → БД → Telegram): пользователь отправляет форму на сайте. PHP-скрипт генерирует короткий уникальный lead_id, сохраняет заявку в базу данных со статусом new и отправляет сообщение в чат отделу продаж с прикрепленной Inline-кнопкой.
  2. Фаза 2 (Telegram → Webhook → БД → Telegram): менеджер нажимает кнопку в чате. Telegram отправляет callback_query на ваш Webhook. Сервер атомарно обновляет статус лида в БД, отвечает на нажатие через answerCallbackQuery и изменяет текст исходного сообщения в чате через editMessageText.

Генерация lead_id и отправка заявки в чат

Для создания кратких и уникальных идентификаторов лида не стоит использовать auto-increment ID из БД (это раскрывает объем продаж конкурентам) или громоздкие UUIDv4 (они слишком длинные для жесткого лимита callback_data). Идеально подходит 7 случайных байт, переведенных в hex-строку длиной 14 символов:

$leadId = bin2hex(random_bytes(7)); // Ровно 14 символов, например "a3f81c9b20e4d1"

Ниже приведен рабочий скрипт обработки формы process_lead.php. Он принимает данные формы, создает запись в БД и выполняет безопасный запрос к Telegram API через cURL.

<?php
declare(strict_types=1);

// 1. Чтение конфигурации из окружения
$botToken = getenv('TELEGRAM_BOT_TOKEN') ?: '';
$chatId = getenv('TELEGRAM_MANAGERS_CHAT_ID') ?: '';

if (!$botToken || !$chatId) {
http_response_code(500);
exit(json_encode(['error' => 'Server configuration error']));
}

// 2. Валидация входных данных формы
$name = trim($_POST['name'] ?? '');
$phone = trim($_POST['phone'] ?? '');

if ($name === '' || $phone === '') {
http_response_code(400);
exit(json_encode(['error' => 'Не заполнены обязательные поля']));
}

// 3. Подключение к БД и генерация lead_id
$pdo = new PDO('mysql:host=localhost;dbname=crm;charset=utf8mb4', 'db_user', 'db_password', [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);

$leadId = bin2hex(random_bytes(7));

$stmt = $pdo->prepare("
INSERT INTO leads (id, name, phone, status, created_at)
VALUES (:id, :name, :phone, 'new', NOW())
");
$stmt->execute([
':id' => $leadId,
':name' => $name,
':phone' => $phone,
]);

// 4. Формирование сообщения и Inline-клавиатуры
// callback_data: "take:a3f81c9b20e4d1" (19 байт из 64 допустимых)
$messageText = sprintf(
"<b>Новая заявка с сайта!</b>

<b>ID:</b> %s
<b>Имя:</b> %s
<b>Телефон:</b> %s",
htmlspecialchars($leadId, ENT_QUOTES, 'UTF-8'),
htmlspecialchars($name, ENT_QUOTES, 'UTF-8'),
htmlspecialchars($phone, ENT_QUOTES, 'UTF-8')
);

$payload = [
'chat_id' => $chatId,
'text' => $messageText,
'parse_mode' => 'HTML',
'reply_markup' => [
'inline_keyboard' => [
[
[
'text' => '🔒 Взять в работу',
'callback_data' => 'take:' . $leadId,
]
]
]
]
];

// 5. Отправка cURL запроса к Telegram API
$ch = curl_init('https://api.telegram.org/bot' . $botToken . '/sendMessage');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_TIMEOUT => 5,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);

if ($response === false) {
error_log("cURL Error while sending lead {$leadId}: " . $curlError);
http_response_code(500);
exit(json_encode(['error' => ' Ошибка отправки сообщения']));
}

$result = json_decode($response, true);
if ($httpCode !== 200 || json_last_error() !== JSON_ERROR_NONE || empty($result['ok'])) {
error_log("Telegram API Error for lead {$leadId}: " . $response);
http_response_code(502);
exit(json_encode(['error' => 'Ошибка взаимодействия с Telegram']));
}

echo json_encode(['success' => true, 'lead_id' => $leadId]);

Обработка Callback Query на Webhook

Когда менеджер нажимает кнопку в чате, Telegram отправляет запрос на ваш Webhook-обработчик. На этом этапе необходимо реализовать три обязательных защитных механизма:

  • Проверка Secret Token: подтверждение того, что запрос пришел именно от Telegram (заголовок X-Telegram-Bot-Api-Secret-Token).
  • Дедупликация (Идемпотентность): защита от повторной обработки одного и того же update_id при ретраях со стороны Telegram.
  • Атомарный UPDATE в БД: исключение ситуации («race condition»), когда два менеджера одновременно нажимают кнопку на разных устройствах.

Ниже представлен код обработчика telegram_webhook.php:

<?php
declare(strict_types=1);

$botToken = getenv('TELEGRAM_BOT_TOKEN') ?: '';
$secretToken = getenv('TELEGRAM_SECRET_TOKEN') ?: '';

// 1. Проверка Secret Token
$receivedToken = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
if ($secretToken === '' || !hash_equals($secretToken, $receivedToken)) {
http_response_code(403);
exit('Unauthorized');
}

// 2. Парсинг сырого JSON
$rawInput = file_get_contents('php://input');
$update = json_decode($rawInput, true);

if (json_last_error() !== JSON_ERROR_NONE || !isset($update['update_id'])) {
http_response_code(400);
exit('Invalid payload');
}

$pdo = new PDO('mysql:host=localhost;dbname=crm;charset=utf8mb4', 'db_user', 'db_password', [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);

// 3. Проверка идемпотентности по update_id
$updateId = (int)$update['update_id'];
$stmt = $pdo->prepare("INSERT IGNORE INTO processed_updates (update_id, created_at) VALUES (?, NOW())");
$stmt->execute([$updateId]);

if ($stmt->rowCount() === 0) {
// Данный update_id уже был успешно обработан ранее
http_response_code(200);
exit('Already processed');
}

// 4. Обработка callback_query
if (isset($update['callback_query'])) {
$cb = $update['callback_query'];
$callbackId = $cb['id'];
$chatId = $cb['message']['chat']['id'] ?? null;
$messageId = $cb['message']['message_id'] ?? null;
$managerData = $cb['from'];
$data = $cb['data'] ?? '';

if (str_istartswith($data, 'take:')) {
$leadId = substr($data, 5);
$managerName = trim(($managerData['first_name'] ?? '') . ' ' . ($managerData['last_name'] ?? ''));
$managerText = $managerName !== '' ? $managerName : ('ID: ' . $managerData['id']);

// Атомарный UPDATE для защиты от гонки условий
$updateStmt = $pdo->prepare("
UPDATE leads
SET status = 'taken', manager_id = :manager_id, taken_at = NOW()
WHERE id = :id AND status = 'new'
");
$updateStmt->execute([
':manager_id' => $managerData['id'],
':id' => $leadId,
]);

$isSuccess = $updateStmt->rowCount() > 0;

// Вспомогательная функция для вызова Telegram API через cURL
$telegramApi = function (string $method, array $params) use ($botToken) {
$ch = curl_init("https://api.telegram.org/bot{$botToken}/{$method}");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($params),
CURLOPT_TIMEOUT => 5,
]);
$res = curl_exec($ch);
curl_close($ch);
return $res;
};

if ($isSuccess) {
// Вплывающее уведомление пользователю
$telegramApi('answerCallbackQuery', [
'callback_query_id' => $callbackId,
'text' => 'Заявка успешно закреплена за вами!',
'show_alert' => false,
]);

// Обновляем текст сообщения, меняем кнопку
$oldText = $cb['message']['text'] ?? '';
$newText = $oldText . "

✅ <b>Взял в работу:</b> " . htmlspecialchars($managerText, ENT_QUOTES, 'UTF-8');

$telegramApi('editMessageText', [
'chat_id' => $chatId,
'message_id' => $messageId,
'text' => $newText,
'parse_mode' => 'HTML',
'reply_markup' => ['inline_keyboard' => []] // Удаляем кнопку
]);
} else {
// Заявка уже была взята кем-то другим
$telegramApi('answerCallbackQuery', [
'callback_query_id' => $callbackId,
'text' => '⚠️ Заявку уже взял другой менеджер!',
'show_alert' => true,
]);
}
}
}

// Всегда возвращаем HTTP 200 OK для Telegram
http_response_code(200);
echo 'OK';

Лимиты callback_data и уплотнение payload

Telegram Bot API накладывает жесткое ограничение: параметр callback_data в Inline-кнопке не может превышать 64 байта. Попытка передать туда длинный JSON или объёмную строку приведет к ошибке 400 Bad Request: BUTTON_DATA_INVALID.

Считаем размер нашей строки:

  • Префикс действия: take: — 5 байт.
  • Значение lead_id (14 hex-символов из bin2hex(random_bytes(7))) — 14 байт.
  • Итого: 19 байт.

Это оставляет запас в 45 байт, что позволяет при необходимости передать дополнительный аргумент (например, take:a3f81c9b20e4d1:fast) без риска выйти за лимит API.

Никогда не храните конфиденциальные данные (телефоны клиентов, токены) внутри callback_data. Внутри Inline-кнопок должны находиться только идентификаторы, ссылающиеся на записи в вашей базе данных.

Типичные ошибки при интеграции

  1. Использование file_get_contents для вызова API: функции file_get_contents не позволяют гибко настраивать таймауты, читать HTTP-коды ответов и корректно обрабатывать 4xx/5xx ошибки Telegram. Используйте cURL.
  2. Отсутствие вызова answerCallbackQuery: если не вызвать этот метод в ответ на callback_query, на кнопке у пользователя будет бесконечно крутиться индикатор загрузки, а Telegram может счесть вебхук нестабильным.
  3. Игнорирование состяния гонки (Race Condition): проверка статуса через SELECT с последующим UPDATE в двух разных SQL-запросах приведет к тому, что два менеджера смогут одновременно взять один лид. Используйте атомарный UPDATE ... WHERE status = 'new'.

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

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

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