Перейти к содержанию
33 минуты чтения
Тема: Практика Telegram · PHP · Обратная связь

Как собирать оценки и отзывы клиентов через Telegram-бота

Для примера мастерская закрывает заказ R-1042 и предлагает клиенту оценить работу от 1 до 5. Клиент может добавить комментарий или пропустить его. Низкая оценка создаёт уведомление менеджеру, а публикация текста на сайте требует отдельного выбора. Соберём обработчик на PHP с привязкой к заказу и устойчивым хранением ответов.

Отделите оценку, поддержку и публикацию

Кнопка с числом фиксирует качество конкретного выполненного заказа. Комментарий помогает понять причину, а разрешение на публикацию определяет допустимость вывода текста на сайт. Эти три события не должны автоматически означать друг друга. Клиент может поставить низкую оценку без комментария или оставить полезный текст только для внутренней работы.

Приглашение отправляется после бизнес-события «заказ выполнен», а не после любой оплаты или сообщения. В базе уже должна быть подтверждённая связь заказа с Telegram user_id. Бот не может начать личный диалог с произвольным человеком: сначала клиент должен открыть его, например при оформлении или привязке аккаунта.

В примере одна оценка относится к одному заказу. Первый принятый ответ сохраняется, повторное нажатие не меняет её. Это простое правило для воспроизводимого сценария; если бизнес разрешает редактирование, добавьте версии, время изменения и повторную модерацию, а не заменяйте значение без истории.

Подготовьте тестового бота и структуру

Нужны PHP 8.3+, cURL, mbstring и PDO SQLite. Код рассчитан на один бот, одну БД и один worker на сервере. В production при нескольких экземплярах понадобятся общие блокировки и очередь; простого flock между разными машинами недостаточно.

Структура проекта
public/webhook.php
values.php
common.php
transport.php
schema.sql
init.php
reviews.php
invite.php
demo-order.php
setup-webhook.php
worker.php
Окружение процесса · значения-примеры
APP_DB=/private/customer-reviews.sqlite
BOT_TOKEN=TOKEN_FROM_BOTFATHER
WEBHOOK_SECRET=RANDOM_HEX_64
WEBHOOK_URL=https://example.com/webhook.php
MANAGER_CHAT_ID=TEST_MANAGER_CHAT_ID
PHP · values.php
<?php

declare(strict_types=1);

/**
 *
 * @return array<string,mixed>
 */
function objectValue(mixed $value): array
{
    if (!is_array($value)) {
        throw new InvalidArgumentException('Expected object');
    }
    $result = [];
    foreach ($value as $key => $item) {
        if (!is_string($key)) {
            throw new InvalidArgumentException('Expected object keys');
        }
        $result[$key] = $item;
    }
    return $result;
}

function stringValue(mixed $value): string
{
    if (!is_string($value)) {
        throw new InvalidArgumentException('Expected string');
    }
    return $value;
}

function intValue(mixed $value): int
{
    if (!is_int($value) && !is_string($value)) {
        throw new InvalidArgumentException('Expected integer');
    }
    $integer = filter_var($value, FILTER_VALIDATE_INT);
    if ($integer === false) {
        throw new InvalidArgumentException('Invalid integer');
    }
    return $integer;
}
PHP · common.php
<?php

declare(strict_types=1);
require_once __DIR__.'/values.php';

function envRequired(string $name): string
{
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException('Missing environment: '.$name);
    }
    return $value;
}

function database(): PDO
{
    $db = new PDO('sqlite:'.envRequired('APP_DB'), null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    $db->exec('PRAGMA busy_timeout=5000');
    return $db;
}
SQL · schema.sql
CREATE TABLE orders (id TEXT PRIMARY KEY,user_id INTEGER NOT NULL,status TEXT NOT NULL,completed_at INTEGER NOT NULL);
CREATE TABLE reviews (
 id INTEGER PRIMARY KEY AUTOINCREMENT,order_id TEXT NOT NULL UNIQUE,user_id INTEGER NOT NULL,
 token TEXT NOT NULL UNIQUE,expires_at INTEGER NOT NULL,score INTEGER,comment TEXT,
 prompt_message_id INTEGER,publication_allowed INTEGER NOT NULL DEFAULT 0,
 consent_version TEXT,consent_at INTEGER,completed_at INTEGER
);
CREATE TABLE inbox (update_id INTEGER PRIMARY KEY,payload TEXT NOT NULL,state TEXT NOT NULL DEFAULT 'pending');
CREATE TABLE outbox (
 id INTEGER PRIMARY KEY AUTOINCREMENT,dedupe_key TEXT NOT NULL UNIQUE,review_id INTEGER,
 kind TEXT NOT NULL,payload TEXT NOT NULL,state TEXT NOT NULL DEFAULT 'pending',attempts INTEGER NOT NULL DEFAULT 0,
 next_attempt_at INTEGER NOT NULL DEFAULT 0,message_id INTEGER,error_code INTEGER
);
PHP · init.php
<?php

declare(strict_types=1);
require __DIR__.'/common.php';
database()->exec(stringValue(file_get_contents(__DIR__.'/schema.sql')));
echo "Database ready\n";

Токен и БД находятся вне public. MANAGER_CHAT_ID задаёт сотрудник на сервере; callback клиента не может заменить получателя тревоги. Для первого опыта используйте свой тестовый аккаунт и отдельный менеджерский чат, чтобы низкая оценка не попала реальной команде.

Свяжите приглашение с заказом и владельцем

reviews.order_id уникален, а случайный token служит коротким идентификатором в callback_data. В нём нет телефона или внутреннего текста заказа. При обработке дополнительно проверяется user_id: пересланная кнопка не даёт другому человеку права оценить чужую работу.

Интерфейс хранит token в кнопках, но это не замена авторизации. Входящий webhook проверяется секретом Telegram; затем from.id сравнивается с личным chat.id, а запрос к reviews содержит token и user_id одновременно. Правило работает даже если чужой token уже известен.

Приглашение действует 14 дней. Истечение срока блокирует новую оценку и комментарий, но не мешает отозвать разрешение на публикацию уже завершённого текста. Дата выполнения заказа и дата ответа хранятся отдельно: отчёт по качеству должен ясно выбирать, по какой из них он считает период.

Реализуйте оценку и комментарий

PHP · reviews.php
<?php

declare(strict_types=1);

/**
 * @param array<string,mixed> $payload
 */
function enqueue(PDO $db, string $key, ?int $reviewId, string $kind, array $payload): void
{
    $db->prepare('INSERT OR IGNORE INTO outbox(dedupe_key,review_id,kind,payload) VALUES(?,?,?,?)')
        ->execute([$key,$reviewId,$kind,json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE)]);
}
function invite(PDO $db, string $orderId): void
{
    $db->beginTransaction();
    try {
        $q = $db->prepare("SELECT * FROM orders WHERE id=? AND status='completed'");
        $q->execute([$orderId]);
        $order = $q->fetch(PDO::FETCH_ASSOC);
        if (!is_array($order)) {
            throw new RuntimeException('Completed order not found');
        }
        $token = bin2hex(random_bytes(8));
        $db->prepare('INSERT OR IGNORE INTO reviews(order_id,user_id,token,expires_at) VALUES(?,?,?,?)')
            ->execute([$orderId,$order['user_id'],$token,time() + 14 * 86400]);
        $q = $db->prepare('SELECT * FROM reviews WHERE order_id=?');
        $q->execute([$orderId]);
        $r = objectValue($q->fetch(PDO::FETCH_ASSOC));
        $buttons = [];
        for ($score = 1;$score <= 5;$score++) {
            $buttons[] = ['text' => (string)$score,'callback_data' => 'rate:'.stringValue($r['token']).':'.$score];
        }
        enqueue($db, 'invite:'.intValue($r['id']), intValue($r['id']), 'invite', [
            'chat_id' => $order['user_id'],'text' => 'Заказ '.$orderId.' выполнен. Оцените работу от 1 (плохо) до 5 (отлично). Ответ добровольный, публикация обсуждается отдельно.',
            'reply_markup' => ['inline_keyboard' => [$buttons]]]);
        $db->commit();
    } catch (Throwable $e) {
        $db->rollBack();
        throw $e;
    }
}

/**
 * Вызывается внутри транзакции inbox.
 *
 * @param array<string,mixed> $update
 */
function reviewUpdate(PDO $db, array $update): void
{
    $callback = $update['callback_query'] ?? null;
    $isCallback = is_array($callback);
    $message = $isCallback ? ($callback['message'] ?? null) : ($update['message'] ?? null);
    if (!is_array($message) || !is_array($message['chat'] ?? null) || $message['chat']['type'] !== 'private') {
        return;
    }
    $user = intValue($message['chat']['id']);
    $from = $isCallback ? ($callback['from'] ?? null) : ($message['from'] ?? null);
    if (!is_array($from) || ($from['id'] ?? null) !== $user) {
        return;
    }
    $text = $isCallback ? ($callback['data'] ?? '') : ($message['text'] ?? '');
    if (!is_string($text)) {
        return;
    }
    $action = '';
    $value = '';
    $token = '';
    if ($isCallback && preg_match('/^(rate|skip|publish):([a-f0-9]{16})(?::([0-5]))?$/D', $text, $m)) {
        $action = $m[1];
        $token = $m[2];
        $value = $m[3] ?? '';
    } elseif (!$isCallback && preg_match('/^\/comment ([a-f0-9]{16}) ([\s\S]+)$/uD', $text, $m)) {
        $action = 'comment';
        $token = $m[1];
        $value = trim($m[2]);
    } elseif (!$isCallback && is_array($message['reply_to_message'] ?? null)) {
        $q = $db->prepare('SELECT token FROM reviews WHERE user_id=? AND prompt_message_id=? AND completed_at IS NULL');
        $q->execute([$user,intValue($message['reply_to_message']['message_id'] ?? 0)]);
        $found = $q->fetchColumn();
        if (is_string($found)) {
            $action = 'comment';
            $token = $found;
            $value = trim($text);
        }
    }
    $updateId = intValue($update['update_id']);
    $reply = static function (string $text) use ($db, $user, $updateId): void {
        enqueue($db, 'ack:'.$updateId, null, 'reply', ['chat_id' => $user,'text' => $text]);
    };
    if ($token === '') {
        $reply('Откройте приглашение к вашему заказу. Комментарий отправляйте ответом на вопрос бота.');
        return;
    }
    $q = $db->prepare('SELECT * FROM reviews WHERE token=? AND user_id=?');
    $q->execute([$token,$user]);
    $r = $q->fetch(PDO::FETCH_ASSOC);
    if (!is_array($r)) {
        $reply('Приглашение недоступно.');
        return;
    }
    $id = intValue($r['id']);
    if ($action !== 'publish' && intValue($r['expires_at']) < time()) {
        $reply('Срок приглашения истёк.');
        return;
    }
    if ($action === 'rate') {
        $score = (int)$value;
        if ($score < 1 || $score > 5) {
            return;
        }
        if ($r['score'] !== null) {
            $reply('Оценка уже принята и не изменена. Ответьте на вопрос о комментарии или используйте /comment '.$token.' ваш текст');
            return;
        }
        $db->prepare('UPDATE reviews SET score=? WHERE id=?')->execute([$score,$id]);
        enqueue($db, 'prompt:'.$id, $id, 'prompt', ['chat_id' => $user,
            'text' => 'Оценка '.$score.' для заказа '.stringValue($r['order_id']).' сохранена. Ответьте на это сообщение комментарием до 2000 символов. Если ответ не привязался: /comment '.$token.' ваш текст',
            'reply_markup' => ['force_reply' => true,'input_field_placeholder' => 'Что понравилось или стоит улучшить?']]);
        enqueue($db, 'skip:'.$id, $id, 'reply', ['chat_id' => $user,'text' => 'Комментарий необязателен.',
            'reply_markup' => ['inline_keyboard' => [[['text' => 'Без комментария','callback_data' => 'skip:'.$token]]]]]);
        if ($score <= 2) {
            enqueue($db, 'low:'.$id, $id, 'manager', ['chat_id' => envRequired('MANAGER_CHAT_ID'),
                'text' => 'Низкая оценка '.$score.'/5 · заказ '.stringValue($r['order_id']).' · отзыв №'.$id.'. Проверьте обращение в рабочей системе.']);
        }
        return;
    }
    if ($action === 'comment' || $action === 'skip') {
        if ($r['score'] === null) {
            $reply('Сначала поставьте оценку.');
            return;
        }
        if ($r['completed_at'] !== null) {
            $reply('Отзыв уже завершён. Текст не изменён.');
            return;
        }
        $comment = $action === 'skip' ? '' : $value;
        if ($action === 'comment' && (mb_strlen($comment) < 1 || mb_strlen($comment) > 2000)) {
            $reply('Комментарий должен содержать от 1 до 2000 символов.');
            return;
        }
        $db->prepare('UPDATE reviews SET comment=?,completed_at=? WHERE id=?')->execute([$comment,time(),$id]);
        if ($comment === '') {
            $reply('Спасибо! Оценка сохранена без комментария.');
            return;
        }
        enqueue($db, 'consent:'.$id, $id, 'reply', ['chat_id' => $user,
            'text' => 'Спасибо! Разрешаете опубликовать этот текст и оценку на сайте компании без Telegram ID и username? По умолчанию отзыв остаётся внутренним. Выбор можно изменить этими же кнопками.',
            'reply_markup' => ['inline_keyboard' => [[['text' => 'Разрешаю','callback_data' => 'publish:'.$token.':1'],['text' => 'Не публиковать / отозвать','callback_data' => 'publish:'.$token.':0']]]]]);
        return;
    }
    if ($action === 'publish' && in_array($value, ['0','1'], true)) {
        if ($r['completed_at'] === null || $r['comment'] === '') {
            $reply('Нет завершённого комментария для публикации.');
            return;
        }
        $db->prepare('UPDATE reviews SET publication_allowed=?,consent_version=?,consent_at=? WHERE id=?')->execute([(int)$value,'site-text-score-anonymous-v1',time(),$id]);
        $reply($value === '1' ? 'Разрешение сохранено. Публикация возможна после проверки менеджером.' : 'Публикация запрещена. Ранее опубликованный отзыв нужно снять с сайта.');
    }
}

invite создаёт review и исходящее приглашение одной транзакцией. Повтор события завершения заказа читает ту же запись и не добавляет ещё один invite в outbox. Подготовка сетевого сообщения отделена от отправки: транзакция не держится открытой во время Telegram API.

После оценки бот задаёт вопрос с ForceReply. Успешно отправленный prompt_message_id сохраняется, а ответ ищет review по владельцу и ID именно этого сообщения. Так комментарии к двум заказам одного клиента не смешиваются. Обычный текст без reply не прикрепляется автоматически к «последнему заказу».

В приглашении к комментарию есть запасная команда /comment TOKEN текст. Она нужна, если клиент не использовал ответ на сообщение или результат отправки prompt оказался неизвестен. Эта команда проходит ту же проверку владельца, срока и состояния; знание кода не позволяет писать отзыв за другого пользователя.

Комментарий ограничен 2000 символами, а кнопка «Без комментария» завершает отзыв с пустым текстом. Поздний текст после завершения не заменяет уже сохранённый. Пользователь получает понятное сообщение; оператор при необходимости разбирает исправление отдельно, сохраняя исходный ответ.

Запросите разрешение отдельной кнопкой

После непустого комментария бот показывает точную формулировку: текст и оценка могут быть опубликованы на сайте без Telegram ID и username. По умолчанию publication_allowed=0. Ни высокая оценка, ни факт отправки комментария не меняют это поле.

Сначала клиент оценивает заказ и пишет комментарий; затем отдельными кнопками разрешает или запрещает публикацию.
Сначала клиент оценивает заказ и пишет комментарий; затем отдельными кнопками разрешает или запрещает публикацию.
Поясняющая схема по сценарию статьи, не снимок Telegram. Вопрос о публикации сокращён; в коде приведён полный текст отдельного согласия.

Разрешение сохраняется вместе с consent_version и consent_at. Версия должна однозначно соответствовать показанному тексту. Если меняете цель, площадку, авторство или состав публикуемых данных, не трактуйте прежний выбор как разрешение на новые условия. Для реального продукта формулировку и сроки хранения согласуйте с ответственным за обработку данных.

Кнопка «Не публиковать / отозвать» остаётся доступной и после согласия. Код сразу меняет текущий запрет; публикационный процесс обязан учитывать его при чтении и удалять уже выведенный материал. Если сайт использует кеш, поисковый индекс или отдельный экспорт, дополнительно организуйте их обновление. Ответ бота сам по себе не удаляет копии из другой системы.

SQL · внутренний отбор для проверки менеджером
SELECT id,order_id,score,comment,consent_version,consent_at
FROM reviews
WHERE publication_allowed=1 AND completed_at IS NOT NULL AND comment<>'';

Эта выборка — список кандидатов для внутренней проверки, не публичный API. На сайт передавайте только разрешённые поля и экранируйте текст. Не публикуйте order_id, user_id, token и служебные отметки; проверьте также, не написал ли клиент телефон или адрес внутри самого комментария. Статья реализует сбор и текущее разрешение, а не автоматическую публикацию отзывов.

Отправьте менеджеру сигнал о низкой оценке

Оценки 1 и 2 создают строку outbox с ключом low:review_id. Повтор callback не создаёт второй сигнал. В сообщение входят оценка, номер заказа и внутренний номер отзыва; полный комментарий не пересылается автоматически в общий чат. По номеру сотрудник открывает разрешённую рабочую систему.

Не блокируйте сохранение отзыва из-за недоступного менеджерского чата. Клиент уже ответил, и это бизнес-событие нужно сохранить независимо от доставки тревоги. Ошибка Telegram меняет состояние outbox, а не score. Если менеджерский бот удалён или лишён прав, оператор увидит failed и восстановит доставку после проверки.

Сигнал должен вести к понятному действию: проверить заказ, связаться с клиентом по разрешённому каналу и зафиксировать результат. Не обещайте автоматическую компенсацию и не отправляйте агрессивные предложения изменить оценку. Для полноценного разговора поддержки подходит операторская группа.

Принимайте обновления и обрабатывайте очередь

PHP · public/webhook.php
<?php

declare(strict_types=1);
require dirname(__DIR__).'/common.php';
$secret = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
if (!is_string($secret) || !hash_equals(envRequired('WEBHOOK_SECRET'), $secret)) {
    http_response_code(403);
    exit;
}
$raw = file_get_contents('php://input', false, null, 0, 65537);
if (!is_string($raw) || strlen($raw) > 65536) {
    http_response_code(413);
    exit;
}
try {
    $update = objectValue(json_decode($raw, true, 32, JSON_THROW_ON_ERROR));
    if (!is_int($update['update_id'] ?? null)) {
        http_response_code(400);
        exit;
    }
    database()->prepare('INSERT OR IGNORE INTO inbox(update_id,payload) VALUES(?,?)')->execute([$update['update_id'],$raw]);
    http_response_code(200);
} catch (Throwable) {
    http_response_code(503);
}
PHP · transport.php
<?php

declare(strict_types=1);

/**
 * @param array<string,mixed> $params
 *
 * @return array{state:string,retry_after:int,message_id:?int,code:?int}
 */
function sendTelegram(string $method, array $params): array
{
    $curl = curl_init('https://api.telegram.org/bot'.envRequired('BOT_TOKEN').'/'.$method);
    if ($curl === false) {
        throw new RuntimeException('HTTP init failed');
    }
    curl_setopt_array($curl, [CURLOPT_POST => true,CURLOPT_POSTFIELDS => json_encode($params, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],CURLOPT_RETURNTRANSFER => true,CURLOPT_CONNECTTIMEOUT => 5,CURLOPT_TIMEOUT => 20]);
    $raw = curl_exec($curl);
    $http = (int)curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    return classifyTelegram($http, is_string($raw) ? $raw : null);
}

/**
 * @return array{state:string,retry_after:int,message_id:?int,code:?int}
 */
function classifyTelegram(int $http, ?string $raw): array
{
    $unknown = ['state' => 'unknown','retry_after' => 0,'message_id' => null,'code' => null];
    if ($raw === null || $http >= 500) {
        return $unknown;
    }
    $body = json_decode($raw, true);
    if (!is_array($body)) {
        return $unknown;
    }
    $result = $body['result'] ?? null;
    if ($http === 200 && ($body['ok'] ?? false) === true) {
        $id = is_array($result) && is_int($result['message_id'] ?? null) ? $result['message_id'] : null;
        return ['state' => 'sent','retry_after' => 0,'message_id' => $id,'code' => null];
    }
    if (($body['ok'] ?? null) !== false || !is_int($body['error_code'] ?? null)) {
        return $unknown;
    }
    $code = $body['error_code'];
    $parameters = $body['parameters'] ?? null;
    if ($code === 429 && is_array($parameters) && is_int($parameters['retry_after'] ?? null) && $parameters['retry_after'] > 0) {
        return ['state' => 'retry','retry_after' => $parameters['retry_after'],'message_id' => null,'code' => $code];
    }
    return ['state' => $code >= 400 && $code < 500 ? 'failed' : 'unknown','retry_after' => 0,'message_id' => null,'code' => $code];
}
PHP · worker.php
<?php

declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/reviews.php';
require __DIR__.'/transport.php';
$lock = fopen(envRequired('APP_DB').'.worker.lock', 'c');
if ($lock === false || !flock($lock, LOCK_EX | LOCK_NB)) {
    exit(0);
}
$db = database();
$q = $db->prepare("SELECT * FROM inbox WHERE state='pending' ORDER BY update_id LIMIT 20");
$q->execute();
foreach ($q->fetchAll(PDO::FETCH_ASSOC) as $data) {
    $row = objectValue($data);
    $update = objectValue(json_decode(stringValue($row['payload']), true, 32, JSON_THROW_ON_ERROR));
    $callback = $update['callback_query'] ?? null;
    if (is_array($callback) && is_string($callback['id'] ?? null)) {
        try {
            sendTelegram('answerCallbackQuery', ['callback_query_id' => $callback['id']]);
        } catch (Throwable) {
        }
    }
    $db->beginTransaction();
    try {
        reviewUpdate($db, $update);
        $db->prepare("UPDATE inbox SET state='done' WHERE update_id=?")->execute([$row['update_id']]);
        $db->commit();
    } catch (Throwable) {
        $db->rollBack();
        $db->prepare("UPDATE inbox SET state='review' WHERE update_id=?")->execute([$row['update_id']]);
    }
}
$q = $db->prepare("SELECT * FROM outbox WHERE state IN ('pending','retry') AND next_attempt_at<=? ORDER BY id LIMIT 20");
$q->execute([time()]);
foreach ($q->fetchAll(PDO::FETCH_ASSOC) as $data) {
    $row = objectValue($data);
    $db->prepare("UPDATE outbox SET state='sending',attempts=attempts+1 WHERE id=?")->execute([$row['id']]);
    try {
        $r = sendTelegram('sendMessage', objectValue(json_decode(stringValue($row['payload']), true, 32, JSON_THROW_ON_ERROR)));
    } catch (Throwable) {
        $r = ['state' => 'unknown','retry_after' => 0,'message_id' => null,'code' => null];
    }
    if ($r['state'] === 'sent' && $r['message_id'] === null) {
        $r['state'] = 'unknown';
    }
    if ($r['state'] === 'retry' && intValue($row['attempts']) + 1 >= 5) {
        $r['state'] = 'failed';
    }
    $db->beginTransaction();
    try {
        $db->prepare('UPDATE outbox SET state=?,next_attempt_at=?,message_id=?,error_code=? WHERE id=?')
            ->execute([$r['state'],time() + $r['retry_after'],$r['message_id'],$r['code'],$row['id']]);
        if ($row['kind'] === 'prompt' && $r['state'] === 'sent') {
            $db->prepare('UPDATE reviews SET prompt_message_id=? WHERE id=?')->execute([$r['message_id'],$row['review_id']]);
        }
        $db->commit();
    } catch (Throwable $e) {
        $db->rollBack();
        throw $e;
    }
}

Webhook подтверждает приём после сохранения update_id и сырого JSON. Worker в транзакции изменяет review, создаёт исходящие сообщения и отмечает inbox как done. Авария до commit откатывает все три действия, а повторный update_id не добавляет новую входящую запись.

answerCallbackQuery нужен для завершения индикатора кнопки. Здесь он выполняется в начале обработки; ошибка или просроченность подтверждения не отменяют уже полученную оценку. Держите worker работающим постоянно и не ставьте его на минутный cron. Для большой очереди нужен отдельный быстрый путь подтверждения кнопок и ограничение нагрузки. CallbackQuery.

Отправитель фиксирует sending перед сетью. Подтверждённый 429 переносит попытку на retry_after, максимум пять попыток. Таймаут или 5xx оставляют unknown. Состояние sending после аварии тоже требует проверки: Telegram мог принять сообщение до записи message_id. Повтор приглашения, prompt и тревоги нельзя считать одинаково безвредным.

Плохой входящий формат переводит запись в review; после исправления причины можно вернуть конкретный inbox в pending. Сетевые unknown в outbox автоматически не переигрываются. Уникальность ключа защищает постановку задачи, но не гарантирует однократную физическую доставку.

Пройдите полный сценарий на своём аккаунте

PHP · demo-order.php
<?php

declare(strict_types=1);
require __DIR__.'/common.php';
$user = intValue($argv[1] ?? '');
if ($user <= 0) {
    throw new InvalidArgumentException('Use your test Telegram user ID');
}
database()->prepare("INSERT INTO orders(id,user_id,status,completed_at) VALUES('R-1042',?,'completed',?)")->execute([$user,time()]);
echo "Test order R-1042 created\n";
PHP · invite.php
<?php

declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/reviews.php';
$id = $argv[1] ?? '';
if (!preg_match('/^[A-Z0-9-]{1,40}$/D', $id)) {
    throw new InvalidArgumentException('Usage: php invite.php R-1042');
}
invite(database(), $id);
echo "Invitation queued\n";
PHP · setup-webhook.php
<?php

declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/transport.php';
$result = sendTelegram('setWebhook', ['url' => envRequired('WEBHOOK_URL'),'secret_token' => envRequired('WEBHOOK_SECRET'),'allowed_updates' => ['message','callback_query']]);
if ($result['state'] !== 'sent') {
    throw new RuntimeException('Webhook configuration not confirmed');
}
echo "Webhook configured\n";
Bash · подготовка теста
php init.php
php setup-webhook.php
php demo-order.php YOUR_TEST_TELEGRAM_USER_ID
php invite.php R-1042
php worker.php

Перед invite.php откройте тестового бота и нажмите Start. В demo-order.php вместо placeholder передайте числовой ID своего аккаунта, связанного с заказом. После worker.php ожидается одно приглашение с пятью кнопками. Эта команда уже отправляет сообщения в настроенные тестовые чаты.

Bash · обработка во время проверки
while true; do
  php worker.php
  sleep 1
done

Поставьте 2, ответьте на вопрос комментарием, затем выберите «Не публиковать». В БД должна быть одна оценка, один комментарий, publication_allowed=0 и одна менеджерская задача. Потом нажмите «Разрешаю» и снова отзовите разрешение: score и comment должны остаться прежними.

SQL · проверить ответ и доставку
SELECT id,order_id,user_id,score,comment,publication_allowed,consent_version FROM reviews;
SELECT id,dedupe_key,kind,state,attempts,message_id,error_code FROM outbox ORDER BY id;

Проверьте повторы, чужие кнопки и два заказа

  • Повтор invite.php для того же заказа оставляет один review и одно приглашение.

  • Повтор оценки 2, затем нажатие 5 не перезаписывают первый ответ и не удваивают тревогу.

  • Другой Telegram-пользователь не оценивает заказ по известному token.

  • Комментарии к двум разным prompt_message_id попадают в свои заказы.

  • Комментарий без reply получает инструкцию, а не случайную привязку.

  • Публикация запрещена по умолчанию; явное разрешение и отзыв меняют только соответствующее поле.

  • Ошибка отправки менеджеру не стирает клиентскую оценку.

Для рабочей нагрузки добавьте срок хранения переписки, частотные ограничения и мониторинг зависших sending/unknown. Не отправляйте новые просьбы об оценке после каждого повторного бизнес-события и не превращайте необязательный отзыв в условие выдачи результата заказа.

Основной код использует прямой Telegram webhook. При подключении BotGate заменяются исходящий транспорт и проверка входящего HMAC; схема заказов, разрешений и очереди остаётся вашей. Не запускайте setup-webhook.php поверх управляемого подключения BotGate. Формат webhook сервиса отличается от X-Telegram-Bot-Api-Secret-Token.