Перейти к содержанию
32 минуты чтения
Тема: Практика Telegram Widgets · HTML · PHP · Статус заказа

HTML-виджеты в Telegram: как сделать интерактивную карточку прямо в сообщении

Для примера отправим покупателю карточку заказа прямо в личный чат с ботом. Магазин поменяет статус на «Готов к выдаче», а пользователь сможет обновить карточку и подтвердить получение. Соберём HTML и PHP-обработчики, свяжем сообщение с заказом и разберём ситуацию, когда действие уже сохранено, но ответ на нажатие не дошёл.

Три состояния карточки заказа №1042: принят, готов к выдаче с кнопкой «Я получил заказ», получен.
Три состояния карточки заказа №1042: принят, готов к выдаче с кнопкой «Я получил заказ», получен.
Карточка заказа из HTML-примера ниже. Это макет, а не снимок клиента Telegram.

Что доступно сейчас и когда выбирать виджет

На момент подготовки материала production Telegram поддерживает Widgets только в личном чате с ботом; такие сообщения защищены от пересылки. Возможности групп, inline-отправки и пересылаемых карточек из документации относятся к тестовой среде. Пример ниже рассчитан на production и одного покупателя.

Актуальная доступность и среда выполнения: Telegram Widgets

Widget — компактный интерфейс сообщения. В нашем сценарии ему достаточно номера заказа, статуса и двух действий. Mini App удобнее для каталога, адресов, ввода комментария, нескольких экранов и полноценного оформления заказа. Если нужна только кнопка «Где заказ?», обычное сообщение с inline-клавиатурой проще поддерживать.

Сначала определите, какую работу карточка сокращает. Здесь покупатель не открывает приложение ради одного статуса; магазин не создаёт новое сообщение на каждом изменении. Но обновлённая карточка не заменяет отдельное уведомление «Можно забирать», если человеку действительно нужен сигнал.

Выбор интерфейса подробнее: Когда нужен Mini App, а когда достаточно бота

Как связаны HTML, состояние и нажатие

HTML задаёт внешний вид и обработчики. После отправки его нельзя заменить внутри старого сообщения: новую версию шаблона нужно отправлять новой карточкой. Данные заказа храним отдельно в chat_data. public_data оставляем пустым, is_shared=false: персональная карточка не должна превращаться в общий объект для нескольких покупателей.

Нажатие передаёт widget_query боту. После проверки владельца и ревизии бот сохраняет решение в БД. answerWidgetQuery отвечает открытой карточке, а editMessageWidgetData отдельно обновляет данные сообщения.
Нажатие передаёт widget_query боту. После проверки владельца и ревизии бот сохраняет решение в БД. answerWidgetQuery отвечает открытой карточке, а editMessageWidgetData отдельно обновляет данные сообщения.
Два результата одного действия: ответ конкретному запросу и сохранённое состояние сообщения. Обе операции используют решение, уже записанное в БД.
  • Сервер сохраняет заказ, владельца и пару chat_id/message_id. Номер заказа не берётся на доверии из интерфейса.

  • Карточка читает chatData и рисует текущий статус. Кнопка передаёт короткое действие через TelegramWidget.request.

  • Webhook получает widget_query. Сервер проверяет владельца и ревизию, сохраняет решение и отвечает через answerWidgetQuery.

  • Отдельный процесс публикует последнее состояние через editMessageWidgetData. Событие chatDataChanged перерисовывает карточку.

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

Параметры отправки и связанные методы: Методы Bot API для Widgets

Подготовка отдельного примера на PHP

Нужны PHP 8.3+ на 64-битной системе с curl, PDO SQLite и zlib, бот, публичный HTTPS endpoint и один сервер с локальной БД. Основной пример работает напрямую с Telegram Bot API. Не используйте для эксперимента webhook рабочего бота: у бота один активный webhook, установка нового адреса заменяет предыдущий.

Структура проекта
order-widget/
  common.php
  init.php
  schema.sql
  orders.php
  telegram.php
  order.php
  publish.php
  setup.php
  widget.html
  public/webhook.php
Окружение процесса · значения-примеры
APP_DB=/srv/order-widget/var/orders.sqlite
TELEGRAM_TOKEN=REPLACE_WITH_BOT_TOKEN
TELEGRAM_WEBHOOK_SECRET=REPLACE_WITH_RANDOM_SECRET
TELEGRAM_WEBHOOK_URL=https://example.com/webhook.php

Переменные должны быть доступны и PHP-FPM, и CLI. Самостоятельный PHP не читает .env: используйте окружение менеджера процессов, а для локальной консоли export NAME=value. Секрет webhook — случайная строка из букв, цифр, дефиса или подчёркивания; для примера подойдёт hex от random_bytes(32). Веб-сервер отдаёт только public, var находится снаружи и доступен на запись обоим процессам.

SQL · schema.sql
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    owner_id INTEGER NOT NULL,
    status TEXT NOT NULL DEFAULT 'new' CHECK(status IN ('new','ready','received')),
    revision INTEGER NOT NULL DEFAULT 1
);
CREATE TABLE cards (
    order_id INTEGER PRIMARY KEY REFERENCES orders(id),
    chat_id INTEGER NOT NULL,
    message_id INTEGER,
    state TEXT NOT NULL DEFAULT 'pending',
    published_revision INTEGER NOT NULL DEFAULT 0,
    retry_at INTEGER NOT NULL DEFAULT 0,
    UNIQUE(chat_id,message_id)
);
CREATE TABLE decisions (
    query_id TEXT PRIMARY KEY,
    actor_id INTEGER NOT NULL,
    order_id INTEGER NOT NULL REFERENCES orders(id),
    response TEXT NOT NULL,
    created_at INTEGER NOT NULL
);
PHP · common.php
<?php
declare(strict_types=1);

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

function database(): PDO
{
    $path = setting('APP_DB');
    if (!is_file($path)) {
        throw new RuntimeException('Run init.php first');
    }
    $db = new PDO('sqlite:'.$path, options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    $db->exec('PRAGMA foreign_keys=ON; PRAGMA busy_timeout=3000');
    return $db;
}

/** @param list<int|string|null> $params */
function sql(PDO $db, string $query, array $params = []): PDOStatement
{
    $statement = $db->prepare($query);
    $statement->execute($params);
    return $statement;
}

/**
 * @param list<int|string|null> $params
 * @return array<string, int|string|null>|null
 */
function row(PDO $db, string $query, array $params = []): ?array
{
    $value = sql($db, $query, $params)->fetch(PDO::FETCH_ASSOC);
    if ($value === false) {
        return null;
    }
    /** @var array<string, int|string|null> $value */
    return $value;
}

/**
 * @template T
 * @param callable(): T $work
 * @return T
 */
function atomic(PDO $db, callable $work): mixed
{
    $db->exec('BEGIN IMMEDIATE');
    try {
        $result = $work();
        $db->exec('COMMIT');
        return $result;
    } catch (Throwable $e) {
        $db->exec('ROLLBACK');
        throw $e;
    }
}

/** @return array<string, mixed> */
function objectJson(string $raw): array
{
    $value = json_decode($raw, true, 64, JSON_THROW_ON_ERROR);
    if (!is_array($value) || array_is_list($value)) {
        throw new InvalidArgumentException('Expected JSON object');
    }
    $object = [];
    foreach ($value as $key => $item) {
        if (!is_string($key)) {
            throw new InvalidArgumentException('Expected string keys');
        }
        $object[$key] = $item;
    }
    return $object;
}

function finish(int $status): never
{
    http_response_code($status);
    header('Cache-Control: no-store');
    exit;
}

function requestHeader(string $key): string
{
    $value = $_SERVER[$key] ?? '';
    return is_string($value) ? $value : '';
}
PHP · init.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
if (PHP_SAPI !== 'cli') { exit(1); }
$path = setting('APP_DB');
if (file_exists($path)) { throw new RuntimeException('Database already exists'); }
$schema = file_get_contents(__DIR__.'/schema.sql');
if ($schema === false) { throw new RuntimeException('Missing schema'); }
$db = new PDO('sqlite:'.$path, options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec($schema);
echo "Database created\n";

orders — состояние заказа. cards — место его отображения и опубликованная ревизия. decisions фиксирует результат конкретного запроса. При переносе в существующий магазин используйте его таблицу заказов и проверенный Telegram ID владельца; не добавляйте публичный endpoint, принимающий произвольные order_id и owner_id.

Если заказ оформляется на сайте, сначала нужна Привязка Telegram к аккаунту сайта

HTML карточки и обработка ответа

Весь шаблон помещается в один файл. Внешних библиотек, fetch и адреса вашего API здесь нет: обращение идёт через TelegramWidget. Текст вставляется через textContent. Ревизия r не позволяет позднему ответу вернуть интерфейс к более старому статусу. Кнопка подтверждения появляется только для ready, но это лишь удобство интерфейса — сервер всё равно проверяет переход.

HTML · widget.html
<!doctype html>
<html lang="ru">
<meta charset="utf-8">
<style>
body { margin: 0; padding: 16px; font-family: system-ui;
  color: var(--tg-theme-text-color); background: var(--tg-theme-bg-color); }
h3 { margin: 0 0 8px; }
p { margin: 8px 0; overflow-wrap: break-word; }
.actions { display: flex; flex-wrap: wrap; gap: 8px; }
button { padding: 12px; border: 0; border-radius: 10px;
  color: var(--tg-theme-button-text-color); background: var(--tg-theme-button-color); }
#hint { color: var(--tg-theme-hint-color); font-size: .9em; }
</style>
<h3 id="title">Заказ</h3>
<p id="status">Обновите карточку, чтобы узнать статус.</p>
<div class="actions">
  <button id="refresh">Обновить</button>
  <button id="received" hidden>Я получил заказ</button>
</div>
<p id="hint"></p>
<script>
const W = window.TelegramWidget;
const title = document.getElementById('title');
const status = document.getElementById('status');
const hint = document.getElementById('hint');
const refresh = document.getElementById('refresh');
const received = document.getElementById('received');
let current = null;
let busy = false;
const labels = { new: 'Принят', ready: 'Готов к выдаче', received: 'Получен' };
function draw() {
  refresh.disabled = busy;
  received.disabled = busy;
  received.hidden = !current || current.status !== 'ready';
  if (!current) return;
  title.textContent = 'Заказ №' + current.id;
  status.textContent = labels[current.status] || 'Уточните статус';
}
function accept(raw) {
  try {
    const next = JSON.parse(raw);
    if (!next || !Number.isInteger(next.r) || !Number.isInteger(next.id)) return;
    if (current && (next.id !== current.id || next.r < current.r)) return;
    current = next;
    draw();
  } catch (e) { hint.textContent = 'Не удалось прочитать состояние'; }
}
function failure(error) {
  const messages = {
    TIMEOUT: 'Ответ задержался. Нажмите «Обновить», чтобы проверить результат.',
    BUSY: 'Предыдущий запрос ещё выполняется.',
    RATE_LIMITED: 'Слишком часто. Подождите и попробуйте снова.',
    NOT_ALLOWED: 'Действие недоступно в этой карточке.',
    INVALID_ANSWER: 'Ответ не удалось прочитать. Обновите карточку.',
    FAILED: 'Не удалось связаться с ботом. Проверьте соединение.'
  };
  hint.textContent = messages[error.code] || 'Запрос не выполнен. Обновите карточку.';
  busy = false;
  draw();
}
function ask(data) {
  if (busy) return;
  busy = true;
  draw();
  hint.textContent = 'Проверяем…';
  // Вызов синхронно внутри обработчика нажатия, до любых await и таймеров.
  try {
    W.request(data).then(answer => {
      try {
        const result = JSON.parse(answer.result || '{}');
        if (result.state) accept(JSON.stringify(result.state));
        hint.textContent = result.error || 'Данные обновлены';
      } catch (e) { hint.textContent = 'Некорректный ответ'; }
      busy = false;
      draw();
    }, failure);
  } catch (e) { failure(e); }
}
refresh.addEventListener('click', () => ask('refresh'));
received.addEventListener('click', () => {
  if (current) ask('received:' + current.r);
});
W.onEvent('chatDataChanged', () => accept(W.chatData));
accept(W.chatData);
draw();
W.ready();
</script>
</html>

Мы не показываем «Получен» сразу после нажатия. Сначала получаем серверное состояние. Если ответ потерялся, интерфейс предлагает «Обновить»: повторять изменение вслепую не требуется. Полученный ответ и chatDataChanged могут прийти в любом порядке, поэтому оба проходят через accept и сравнение ревизий.

Для светлой и тёмной темы используются переменные Telegram. Кнопки переносятся на новую строку, внутри карточки нет длинного описания товаров. Caption оставляем под виджетом: он служит текстовой версией заказа и отделяет время сообщения от кнопок. На узком экране проверяйте именно весь текст, а не только пустой макет.

Не включайте в HTML токен бота, ключ API, телефон или адрес клиента. Шаблон одинаков для всех заказов; персональные сведения не нужны для отображения трёх состояний. В Mini App детали можно открыть после отдельной проверки доступа.

Проверка владельца и защита от старой кнопки

Кнопка отправляет received:REVISION. В данных нет order_id: сервер находит заказ по сохранённым координатам сообщения. Даже если клиент отправит другое действие, оно применяется только к заказу подтверждённого владельца. Параллельные запросы SQLite сериализует через BEGIN IMMEDIATE.

PHP · orders.php
<?php
declare(strict_types=1);

/** @param array<string, int|string|null> $order
 * @return array{id:int,status:string,r:int}
 */
function cardState(array $order): array
{
    return ['id' => (int) $order['id'], 'status' => (string) $order['status'], 'r' => (int) $order['revision']];
}

function encodeData(mixed $value): string
{
    $json = json_encode($value, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    if (strlen($json) > 1024) { throw new LengthException('Widget data exceeds 1024 bytes'); }
    return $json;
}

/** @param array<string, mixed> $query */
function decide(PDO $db, array $query): string
{
    $id = $query['id'] ?? null;
    $from = $query['from'] ?? null;
    $chat = $query['chat'] ?? null;
    $message = $query['message_id'] ?? null;
    $data = $query['data'] ?? null;
    if (!is_string($id) || $id === '' || strlen($id) > 128
        || !is_array($from) || !is_int($from['id'] ?? null)
        || !is_array($chat) || ($chat['type'] ?? null) !== 'private'
        || !is_int($chat['id'] ?? null) || !is_int($message)
        || !is_string($data) || strlen($data) > 64) {
        return encodeData(['error' => 'Карточка недоступна']);
    }
    return atomic($db, function () use ($db, $id, $from, $chat, $message, $data): string {
        $order = row($db, 'SELECT o.* FROM orders o JOIN cards c ON c.order_id=o.id
            WHERE c.chat_id=? AND c.message_id=? AND c.state=? AND o.owner_id=?',
            [$chat['id'], $message, 'sent', $from['id']]);
        if ($order === null || $chat['id'] !== $from['id']) {
            return encodeData(['error' => 'Карточка недоступна']);
        }
        $old = row($db, 'SELECT * FROM decisions WHERE query_id=?', [$id]);
        if ($old !== null) {
            if ((int) $old['actor_id'] !== $from['id'] || (int) $old['order_id'] !== (int) $order['id']) {
                return encodeData(['error' => 'Карточка недоступна']);
            }
            return (string) $old['response'];
        }
        $error = null;
        if ($data === 'refresh') {
            // Читаем только серверный заказ.
        } elseif (preg_match('/^received:([1-9][0-9]{0,9})$/D', $data, $match) === 1) {
            if ((int) $order['revision'] !== (int) $match[1]) {
                $error = 'Карточка устарела. Проверьте новый статус.';
            } elseif ($order['status'] !== 'ready') {
                $error = 'Подтверждение сейчас недоступно.';
            } else {
                sql($db, "UPDATE orders SET status='received',revision=revision+1 WHERE id=?", [$order['id']]);
                $order['status'] = 'received';
                $order['revision'] = (int) $order['revision'] + 1;
            }
        } else {
            $error = 'Неизвестное действие';
        }
        $answer = encodeData(['state' => cardState($order), 'error' => $error]);
        sql($db, 'INSERT INTO decisions VALUES (?,?,?,?,?)', [$id, $from['id'], $order['id'], $answer, time()]);
        return $answer;
    });
}

Одна и та же query_id получает сохранённый ответ. Второй клик с новой query_id, но старой ревизией, увидит актуальное состояние и сообщение об устаревшей карточке. Повторного перехода ready → received не будет. refresh ничего не меняет. Случайный пользователь и сообщение, которого нет в cards, не получают даже состояние чужого заказа.

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

Не путайте доверенный from.id в принятом Telegram update с любым ID, который пришёл внутри data. Первый становится достоверным после проверки источника webhook; второй остаётся пользовательским вводом. Состояние из браузера не подтверждает право на заказ.

Telegram webhook и быстрый ответ на запрос

Клиент Telegram ожидает ответ на widget_query в течение 15 секунд. Здесь в HTTP-обработчике только короткая транзакция и answerWidgetQuery; отправка новой карточки и её редактирование выполняются отдельно. Таймаут исходящего запроса ограничен пятью секундами. Если очередь перед PHP-FPM сама занимает десять секунд, эти настройки уже не спасут — контролируйте задержку входящих запросов.

PHP · telegram.php
<?php
declare(strict_types=1);
/**
 * @param array<string, mixed> $params
 * @return array<string, mixed>
 */
function telegram(string $method, array $params): array
{
    $curl = curl_init('https://api.telegram.org/bot'.setting('TELEGRAM_TOKEN').'/'.$method);
    curl_setopt_array($curl, [
        CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($params, JSON_THROW_ON_ERROR),
        CURLOPT_CONNECTTIMEOUT => 2, CURLOPT_TIMEOUT => 5,
    ]);
    $body = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if (!is_string($body) || $status >= 500) {
        throw new RuntimeException('Unknown Telegram result');
    }
    return objectJson($body);
}

/** @param array<string, mixed> $result */
function editDone(array $result): bool
{
    return ($result['ok'] ?? false) === true
        || (($result['error_code'] ?? null) === 400
            && is_string($result['description'] ?? null)
            && str_contains($result['description'], 'message is not modified'));
}
PHP · public/webhook.php
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/orders.php';
require dirname(__DIR__).'/telegram.php';
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') { finish(405); }
if (!hash_equals(setting('TELEGRAM_WEBHOOK_SECRET'), requestHeader('HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'))) {
    finish(403);
}
$body = file_get_contents('php://input', length: 65537);
if ($body === false || strlen($body) > 65536) { finish(413); }
try {
    $update = objectJson($body);
} catch (JsonException|InvalidArgumentException) { finish(400); }
$query = $update['widget_query'] ?? null;
if (!is_array($query) || !is_string($query['id'] ?? null)) { finish(200); }
foreach (array_keys($query) as $key) {
    if (!is_string($key)) { finish(400); }
}
try {
    $answer = decide(database(), $query);
} catch (Throwable) {
    error_log('Widget: decision not saved');
    finish(503);
}
// Быстрый ответ. Сам заказ уже сохранён; доставка состояния идёт отдельно.
try {
    $result = telegram('answerWidgetQuery', ['widget_query_id' => $query['id'], 'data' => $answer]);
    if (($result['ok'] ?? false) !== true) { error_log('Widget: answer rejected'); }
} catch (Throwable) {
    error_log('Widget: answer result unknown');
}
finish(200);

При ошибке сохранения возвращаем 503. После сохранения решение остаётся в БД даже при неудачном answerWidgetQuery: повторное применение не нужно. Пользователь может увидеть TIMEOUT и проверить состояние кнопкой «Обновить». Просроченный ответ не отправляем бесконечно; следующая query имеет свой ID и срок.

PHP · setup.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/telegram.php';
if (PHP_SAPI !== 'cli') { exit(1); }
$result = telegram('setWebhook', [
    'url' => setting('TELEGRAM_WEBHOOK_URL'),
    'secret_token' => setting('TELEGRAM_WEBHOOK_SECRET'),
    'allowed_updates' => ['widget_query'],
]);
if (($result['ok'] ?? false) !== true) {
    throw new RuntimeException('Webhook setup failed');
}
echo "Webhook configured\n";
Shell · первая настройка
php init.php
php setup.php

Для отдельного учебного бота подписываемся только на widget_query. Если добавляете обработчик существующему боту, расширьте его текущий allowed_updates, сохранив message, callback_query и другие нужные типы. Этот пример не обслуживает shared_widget_query, группы и inline-контекст. Команда /start здесь лишь открывает личный диалог; обработчик меню не входит в сценарий.

Если нажатия не доходят, начните с Проверка входящих webhook

Отправка карточки и обновление уже отправленного сообщения

Для воспроизводимого примера создадим заказ из CLI. Реальный магазин выполняет те же записи после создания заказа и проверки привязки владельца. order.php не должен быть доступен через веб-сервер.

PHP · order.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
if (PHP_SAPI !== 'cli') { exit(1); }
$command = $argv[1] ?? '';
$id = filter_var($argv[2] ?? '', FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
if (!is_int($id)) { throw new InvalidArgumentException('Positive order ID required'); }
$db = database();
if ($command === 'create') {
    $owner = filter_var($argv[3] ?? '', FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
    if (!is_int($owner)) { throw new InvalidArgumentException('Telegram user ID required'); }
    atomic($db, function () use ($db, $id, $owner): void {
        sql($db, 'INSERT INTO orders(id,owner_id) VALUES (?,?)', [$id, $owner]);
        sql($db, 'INSERT INTO cards(order_id,chat_id) VALUES (?,?)', [$id, $owner]);
    });
} elseif ($command === 'ready') {
    $changed = sql($db, "UPDATE orders SET status='ready',revision=revision+1 WHERE id=? AND status='new'", [$id]);
    if ($changed->rowCount() !== 1) { throw new RuntimeException('Order missing or transition forbidden'); }
} else {
    throw new InvalidArgumentException('Use create ORDER_ID USER_ID or ready ORDER_ID');
}
echo "Saved\n";

publish.php последовательно выбирает карточки, которые ещё не отправлены или отстали от revision заказа. Сначала он обновляет chat_data, затем текстовый caption. published_revision изменяется только после обеих успешных операций. Если заказ поменялся во время API-запроса, новая ревизия останется неопубликованной и попадёт в следующий проход.

PHP · publish.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/orders.php';
require __DIR__.'/telegram.php';
if (PHP_SAPI !== 'cli') { exit(1); }
$lock = fopen(setting('APP_DB').'.publisher.lock', 'c');
if ($lock === false || !flock($lock, LOCK_EX | LOCK_NB)) { exit(0); }
$html = file_get_contents(__DIR__.'/widget.html');
if ($html === false) { throw new RuntimeException('Missing widget.html'); }
$compressed = gzcompress($html, 9);
if (strlen($html) > 32768 || $compressed === false || strlen($compressed) > 4000) {
    throw new LengthException('Widget too large; leave a margin below 4096');
}
$db = database();
$cursor = 0;
for ($i = 0; $i < 20; $i++) {
    $item = row($db, "SELECT o.*, c.chat_id,c.message_id,c.state FROM orders o
        JOIN cards c ON c.order_id=o.id WHERE o.id>? AND c.retry_at<=?
        AND (c.state='pending' OR (c.state='sent' AND c.published_revision<o.revision))
        ORDER BY o.id LIMIT 1", [$cursor, time()]);
    if ($item === null) { break; }
    $cursor = (int) $item['id'];
    $isNew = $item['state'] === 'pending';
    $state = encodeData(cardState($item));
    $labels = ['new' => 'Принят', 'ready' => 'Готов к выдаче', 'received' => 'Получен'];
    $orderStatus = $item['status'];
    $caption = 'Заказ №'.$item['id'].': '.(is_string($orderStatus) ? ($labels[$orderStatus] ?? 'Уточните статус') : 'Уточните статус');
    $params = ['chat_id' => $item['chat_id']];
    if ($isNew) {
        sql($db, "UPDATE cards SET state='sending' WHERE order_id=?", [$item['id']]);
        $params += ['html' => $html, 'chat_data' => $state, 'caption' => $caption,
            'allow_queries' => true, 'is_shared' => false, 'protect_content' => true];
    } else {
        $params += ['message_id' => $item['message_id'], 'chat_data' => $state];
    }
    try {
        $result = telegram($isNew ? 'sendWidget' : 'editMessageWidgetData', $params);
        if (!$isNew && editDone($result)) {
            $result = telegram('editMessageCaption', [
                'chat_id' => $item['chat_id'], 'message_id' => $item['message_id'], 'caption' => $caption,
            ]);
        }
        $message = $result['result'] ?? null;
        $sent = $isNew && ($result['ok'] ?? false) === true
            && is_array($message) && is_int($message['message_id'] ?? null);
        if ($sent || (!$isNew && editDone($result))) {
            sql($db, "UPDATE cards SET state='sent', message_id=?, published_revision=? WHERE order_id=?", [
                $sent ? $message['message_id'] : $item['message_id'], $item['revision'], $item['id'],
            ]);
        } else {
            $code = $result['error_code'] ?? null;
            $parameters = $result['parameters'] ?? null;
            $retry = is_array($parameters) && is_int($parameters['retry_after'] ?? null)
                ? max(1, $parameters['retry_after']) + 1 : 60;
            $next = $code === 429 ? ($isNew ? 'pending' : 'sent') : 'failed';
            if (!is_int($code) || $code >= 500) { $next = $isNew ? 'unknown' : 'sent'; }
            sql($db, 'UPDATE cards SET state=?,retry_at=? WHERE order_id=?', [$next, time() + $retry, $item['id']]);
            error_log('Widget publish failed for order '.$item['id']);
            break;
        }
    } catch (Throwable) {
        sql($db, 'UPDATE cards SET state=?,retry_at=? WHERE order_id=?', [
            $isNew ? 'unknown' : 'sent', time() + 60, $item['id'],
        ]);
        error_log('Widget publish result unknown for order '.$item['id']);
        break;
    }
    usleep(1500000);
}

Один flock не даёт двум издателям перезаписать карточку конкурирующими старыми снимками. При таймауте редактирования следующий проход снова читает актуальную БД, а не старый отложенный JSON. Ответ message is not modified считается успешным для повторного редактирования. При 429 учитывается retry_after; другие явные отказы переводят карточку в failed.

Первичная отправка отличается от редактирования: после неизвестного результата sendWidget нельзя автоматически отправлять ещё раз. unknown и зависшее sending требуют проверки чата и журнала. При подтверждённой отправке сохраните реальные координаты сообщения; если принято решение создать новую карточку, явно учтите возможный дубль. Пример намеренно не скрывает это окно сбоя.

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

Shell · полный тестовый путь
php order.php create 1042 123456789
php publish.php
php order.php ready 1042
php publish.php

Замените 123456789 своим Telegram user ID и заранее откройте диалог с ботом. После первого publish появится «Принят». После ready и второго publish — «Готов к выдаче» и кнопка получения. Нажмите её, затем запустите publish.php ещё раз: сообщение и caption должны перейти в «Получен». Повтор ready для закрытого заказа завершится ошибкой.

В рабочем варианте запускайте publish.php раз в минуту с тем же APP_DB и окружением. Одновременно работает один процесс; один проход ограничен 20 карточками. Для более быстрой синхронизации вызывайте этот же сериализованный процесс после событий магазина или сделайте постоянный worker. Следите за разницей revision и published_revision; не обещайте мгновенное обновление при минутном расписании.

Размер, старые клиенты и выбор Mini App

До отправки publish.php проверяет размер HTML и сжатого файла с небольшим запасом. Серверный предел сжатого HTML — 4096 байт; большой JSON заказа туда не помещайте. chat_data и ответ query имеют отдельные пределы по 1024 байта. encodeData проверяет байты UTF-8, поэтому кириллица не обходится с количеством символов как с количеством байтов.

Не уменьшайте размер ценой нечитаемого состояния: вместо полной корзины храните id, status и r, а подробности открывайте отдельно. Высоту проверяйте на длинном переводе и увеличенном тексте. Полноценную форму с адресом, вводом и прокруткой переносите в Mini App.

Caption должен оставаться понятным без исполнения HTML. Поэтому издатель обновляет его вместе с карточкой. Это полезно клиентам без поддержки Widgets и для текстового представления сообщения. На старом клиенте интерактивных кнопок может не быть: в рабочем боте оставьте обычную команду просмотра заказа или ссылку на защищённый кабинет.

Браузерная проверка оценивает раскладку и JavaScript, но не доказывает работу в Telegram. Отдельно пройдите сценарий на актуальных iOS, Android и Desktop клиентах, проверьте светлую и тёмную темы. Если Telegram не принимает HTML, сначала проверьте объём, поддерживаемые элементы и отсутствие внешних ресурсов, а не права пользователя на заказ.

Если бот подключён через BotGate

Исходящие методы доступны через универсальный вызов SDK: имя sendWidget или editMessageWidgetData передаётся строкой. Отдельного метода-обёртки в библиотеке не требуется. Приведённый ниже фрагмент показывает только замену транспорта; он не является вторым полным обработчиком и не должен запускаться параллельно с publish.php.

PHP · пример вызова через SDK
<?php
declare(strict_types=1);
require __DIR__.'/vendor/autoload.php';
require __DIR__.'/common.php';
$bot = BotGate\Client::fromConfig(new BotGate\Config(
    apiKey: setting('BOTGATE_API_KEY'), timeout: 5, maxRetries: 0,
))->bot(setting('BOTGATE_BOT_ID'));
$answer = $bot->call('editMessageWidgetData', [
    'chat_id' => 123456789,
    'message_id' => 456,
    'chat_data' => '{"id":1042,"status":"ready","r":2}',
]);

Для входящих событий используйте настроенную доставку BotGate и проверку X-BotGate-Signature по его контракту. Проверка X-Telegram-Bot-Api-Secret-Token из основного примера относится к прямому webhook Telegram и не заменяет проверку BotGate. Не запускайте setup.php для уже подключённого таким образом бота: это может переназначить его webhook.

Проверьте, что в выбранной схеме доставки проходит сырой widget_query и сохраняются его поля. При поддержке нового типа не полагайтесь на старый enum типов SDK; работайте с проверенным сырым update. Также измерьте задержку до answerWidgetQuery: очередь доставки не должна съедать 15-секундное окно. Смена транспорта не расширяет доступность Widgets в production.

Подпись и формат доставки: Контракт webhook BotGate

Какие сценарии проверить до запуска магазина

  • Создание заказа, отправка карточки, переход в ready, подтверждение получения, публикация нового состояния и обновление caption.

  • Двойное нажатие: новый query ID со старой ревизией не меняет заказ второй раз. Повтор исходной query ID возвращает сохранённый ответ.

  • Другой from.id, чужой message_id и групповой контекст не раскрывают данные и не меняют статус.

  • Подмена data на неизвестную команду или неверную ревизию возвращает понятную ошибку. Исходное состояние остаётся в БД.

  • Ошибка подписи webhook получает 403. Ошибка сохранения решения получает 503.

  • Потеря answerWidgetQuery после сохранения: интерфейс не объявляет успех без ответа, а последующий refresh показывает реальное состояние.

  • Поздний chatDataChanged с меньшей r не откатывает свежую карточку; ответ на старый запрос также не откатывает её.

  • Повторное редактирование без изменения данных не застревает на message is not modified. Ошибка caption оставляет ревизию неопубликованной.

  • Неизвестный результат первой отправки остаётся unknown. Следующий publish не создаёт новую карточку вслепую.

  • На телефоне кнопки помещаются в пузырь сообщения, подпись читается, а тема Telegram не делает текст и фон одинаковыми.

SQL · состояние публикации
SELECT o.id,o.status,o.revision,c.state,c.message_id,c.published_revision
FROM orders o JOIN cards c ON c.order_id=o.id
WHERE c.state<>'sent' OR c.published_revision<o.revision;
SELECT query_id,actor_id,order_id,created_at FROM decisions
ORDER BY created_at DESC LIMIT 20;

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