Багато розробників під час надсилання заявок із сайту в Telegram обмежуються простою пересилкою тексту повідомлення в менеджерський чат. Однак із зростанням обсягу продажів такий підхід швидко призводить до хаосу: менеджери перебивають один одного, забирають одних і тих самих клієнтів або пропускають нові звернення. Нативний способ вирішити цю проблему — надсилати заявку з інтерактивною Inline-кнопкою «Взяти в роботу» прямо в Telegram.
У цій статті ми побудуємо надійний сценарій на PHP: від генерації криптографічно стійкого ідентифікатора заявки та запису в PostgreSQL/MySQL до коректної обробки Webhook з урахуванням гонки запитів і суворих лімітів Telegram Bot API.
Схема роботи та структура даних
Загальний алгоритм взаємодії складається з двох ключових фаз:
- Фаза 1 (Сайт → БД → Telegram): користувач надсилає форму на сайті. PHP-скрипт генерує короткий унікальний
lead_id, зберігає заявку в базу даних зі статусомnewі надсилає повідомлення в чат відділу продажів із прикріпленою Inline-кнопкою. - Фаза 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-кнопок повинні міститися тільки ідентифікатори, що посилаються на записи у вашій базі даних.Типові помилки під час інтеграції
- Використання file_get_contents для виклику API: функції
file_get_contentsне дозволяють гнучко налаштовувати таймаути, читати HTTP-коди відповідей і коректно обробляти 4xx/5xx помилки Telegram. Використовуйте cURL. - Відсутність виклику answerCallbackQuery: якщо не викликати цей метод у відповідь на
callback_query, на кнопці у користувача буде нескінченно крутитися індикатор завантаження, а Telegram може вважати вебхук нестабільним. - Ігнорування стану гонитви (Race Condition): перевірка статусу через
SELECTіз подальшимUPDATEу двох різних SQL-запитах призведе до того, що два менеджери зможуть одночасно взяти один лід. Використовуйте атомарнийUPDATE ... WHERE status = 'new'.
Якщо вам потрібна професійна розробка складних ботів або інтеграція сайту з Telegram Mini Apps, команда BotCreator допоможе реалізувати рішення під ключ.