Что доступно сейчас и когда выбирать виджет
На момент подготовки материала production Telegram поддерживает Widgets только в личном чате с ботом; такие сообщения защищены от пересылки. Возможности групп, inline-отправки и пересылаемых карточек из документации относятся к тестовой среде. Пример ниже рассчитан на production и одного покупателя.
Актуальная доступность и среда выполнения: Telegram Widgets
Widget — компактный интерфейс сообщения. В нашем сценарии ему достаточно номера заказа, статуса и двух действий. Mini App удобнее для каталога, адресов, ввода комментария, нескольких экранов и полноценного оформления заказа. Если нужна только кнопка «Где заказ?», обычное сообщение с inline-клавиатурой проще поддерживать.
Сначала определите, какую работу карточка сокращает. Здесь покупатель не открывает приложение ради одного статуса; магазин не создаёт новое сообщение на каждом изменении. Но обновлённая карточка не заменяет отдельное уведомление «Можно забирать», если человеку действительно нужен сигнал.
Выбор интерфейса подробнее: Когда нужен Mini App, а когда достаточно бота
Как связаны HTML, состояние и нажатие
HTML задаёт внешний вид и обработчики. После отправки его нельзя заменить внутри старого сообщения: новую версию шаблона нужно отправлять новой карточкой. Данные заказа храним отдельно в chat_data. public_data оставляем пустым, is_shared=false: персональная карточка не должна превращаться в общий объект для нескольких покупателей.
Сервер сохраняет заказ, владельца и пару 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 находится снаружи и доступен на запись обоим процессам.
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
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
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, но это лишь удобство интерфейса — сервер всё равно проверяет переход.
<!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
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
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
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
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";
php init.php php setup.php
Для отдельного учебного бота подписываемся только на widget_query. Если добавляете обработчик существующему боту, расширьте его текущий allowed_updates, сохранив message, callback_query и другие нужные типы. Этот пример не обслуживает shared_widget_query, группы и inline-контекст. Команда /start здесь лишь открывает личный диалог; обработчик меню не входит в сценарий.
Если нажатия не доходят, начните с Проверка входящих webhook
Отправка карточки и обновление уже отправленного сообщения
Для воспроизводимого примера создадим заказ из CLI. Реальный магазин выполняет те же записи после создания заказа и проверки привязки владельца. 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
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 не отменяет фактическую выдачу заказа. Не пытайтесь держать транзакцию БД открытой во время сетевого запроса.
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
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 не делает текст и фон одинаковыми.
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;
Такой виджет решает одну небольшую задачу и остаётся связанным с серверным заказом. Расширяя карточку, сначала сохраняйте правила доступа, ревизии и обработку неизвестного результата; новые кнопки добавляйте после определения допустимого перехода состояния.