Форма сайту → 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

Розбираємо, що автоматизувати в бізнесі та як це працює на практиці. Без спаму.