Разделим настройки и возможность написать
Уведомление проходит несколько независимых проверок: есть ли нужное бизнес-событие, включена ли категория, разрешено ли сейчас отправлять по местному времени и может ли бот написать пользователю. Ни открытие Mini App, ни нажатие «Сохранить» не заменяют разрешение Telegram. А разрешение Telegram не говорит, какие категории человек выбрал.
В этом примере обе категории изначально выключены. Статусы заказов также подчиняются часам тишины. Если продукту нужны срочные сообщения, выделите отдельную ясно описанную категорию и её правила; не обходите настройки скрытым флагом urgent. Отключение категории отменяет ещё не отправленные уведомления этой категории, а повторное включение не оживляет старую очередь.
Сохраняем пояс IANA, например Europe/Moscow или Europe/Berlin, а не фиксированное UTC+3.
Время тишины — локальное время суток. Интервал 22:00–08:00 пересекает полночь.
Начало включено, конец исключён: в 22:00 тихо, в 08:00 можно писать.
Одинаковые начало и конец при включённой тишине считаем ошибкой. Отключение всех категорий задаётся отдельными переключателями.
Подготовим проект и очередь
Пример рассчитан на один бот и одну базу SQLite на локальном диске сервера, PHP 8.3+ с расширениями PDO SQLite и cURL. Публичный корень сайта — только папка public/; остальные PHP-файлы, база и Composer-зависимости находятся уровнем выше. Для нескольких ботов добавьте идентификатор бота во все ключи уникальности. Не размещайте SQLite на общей сетевой папке нескольких серверов.
BOT_TOKEN=TOKEN_FROM_BOTFATHER BOT_DB_PATH=/srv/notifications/private/bot.sqlite WEBHOOK_SECRET=RANDOM_SECRET_FROM_PASSWORD_MANAGER WEBHOOK_URL=https://example.com/webhook.php
Это настоящие переменные окружения процесса: настройте их и для PHP-FPM, и для CLI. Обычный PHP не читает .env автоматически. Создайте закрытую папку private/, дайте пользователю приложения право записи в неё и запретите доступ из веба. Токен и секрет webhook не должны попадать в браузер, репозиторий или логи. В примерах ниже все команды выполняются из корня отдельного учебного приложения.
В BotFather настройте кнопку меню на https://example.com/settings.html. Страницу и API разместите на одном HTTPS-домене. Здесь показана маленькая очередь на SQLite, чтобы пройти путь от настроек до отправки без установки Laravel; для большой рассылки используйте очередь с ограничением скорости.
CREATE TABLE preferences (
user_id INTEGER PRIMARY KEY, orders INTEGER NOT NULL DEFAULT 0,
offers INTEGER NOT NULL DEFAULT 0, timezone TEXT NOT NULL DEFAULT 'UTC',
quiet INTEGER NOT NULL DEFAULT 0, start_min INTEGER NOT NULL DEFAULT 1320,
end_min INTEGER NOT NULL DEFAULT 480, blocked INTEGER NOT NULL DEFAULT 0,
updated_at INTEGER NOT NULL
);
CREATE TABLE notifications (
id INTEGER PRIMARY KEY, event_key TEXT NOT NULL UNIQUE,
user_id INTEGER NOT NULL REFERENCES preferences(user_id),
category TEXT NOT NULL CHECK(category IN ('orders','offers')),
body TEXT NOT NULL, due_at INTEGER NOT NULL, expires_at INTEGER NOT NULL,
state TEXT NOT NULL DEFAULT 'pending', attempts INTEGER NOT NULL DEFAULT 0,
claimed_at INTEGER, message_id INTEGER
);
CREATE INDEX notifications_due ON notifications(state,due_at);
CREATE TABLE updates (id INTEGER PRIMARY KEY);
<?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('BOT_DB_PATH');
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');
$db->exec('PRAGMA busy_timeout=3000');
return $db;
}
/** @param list<int|string|null> $values */
function sql(PDO $db, string $query, array $values = []): PDOStatement
{
$statement = $db->prepare($query);
$statement->execute($values);
return $statement;
}
/** @return array<string, int|string|null>|null */
function row(PDOStatement $statement): ?array
{
$result = $statement->fetch(PDO::FETCH_ASSOC);
if ($result === false) {
return null;
}
if (!is_array($result)) {
throw new RuntimeException('Invalid database row');
}
foreach ($result as $key => $value) {
if (!is_string($key) || !(is_int($value) || is_string($value) || $value === null)) {
throw new RuntimeException('Invalid database field');
}
}
return $result;
}
/**
* @template T
* @param callable(): T $action
* @return T
*/
function atomic(PDO $db, callable $action): mixed
{
$db->exec('BEGIN IMMEDIATE');
try {
$result = $action();
$db->exec('COMMIT');
return $result;
} catch (Throwable $e) {
$db->exec('ROLLBACK');
throw $e;
}
}
/** @return array<string, mixed> */
function jsonBody(): array
{
$raw = file_get_contents('php://input', length: 65537);
if ($raw === false || strlen($raw) > 65536) {
throw new InvalidArgumentException('Request too large');
}
$data = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
if (!is_array($data) || array_is_list($data)) {
throw new InvalidArgumentException('Expected JSON object');
}
$result = [];
foreach ($data as $key => $value) {
if (!is_string($key)) {
throw new InvalidArgumentException('Invalid JSON key');
}
$result[$key] = $value;
}
return $result;
}
/** @param array<string, mixed> $data */
function reply(array $data, int $status = 200): never
{
http_response_code($status);
header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');
echo json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
exit;
}
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
if (PHP_SAPI !== 'cli') {
exit(1);
}
$path = setting('BOT_DB_PATH');
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.sql');
}
$db = new PDO('sqlite:'.$path, options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec('PRAGMA foreign_keys=ON');
$db->exec($schema);
echo "Database created\n";
php init.php
event_key — уникальное бизнес-событие конкретного получателя, например order-740-ready-user-123. Оно не должно меняться при повторе события из CRM. Время готовности и истечения храним в UTC timestamp, а локальную тишину вычисляем по сохранённому часовому поясу.
Проверим пользователя на сервере
Запросы страницы передают исходную строку Telegram.WebApp.initData в заголовке X-Telegram-Init-Data. Сервер проверяет HMAC и срок действия и берёт Telegram ID только из подписанных данных. В этом небольшом примере нет cookie-сессии: каждый POST заново авторизуется, поэтому отдельный CSRF-токен не нужен. Не включайте разрешающий CORS, не переносите авторизацию в query string и не сохраняйте этот заголовок в журналах.
Через десять минут после запуска сервер попросит открыть Mini App заново. Это выбранный срок нашего примера, а не лимит Telegram. Для долгой работы обменяйте проверенный initData на серверную сессию с CSRF-защитой по отдельному руководству. Проверка подписи подтверждает пользователя, но не назначает ему права сотрудника.
<?php
declare(strict_types=1);
function miniUser(string $raw, string $token, int $now): int
{
if ($raw === '' || strlen($raw) > 16384) {
throw new InvalidArgumentException('Open Mini App again');
}
$fields = [];
foreach (explode('&', $raw) as $part) {
$pair = explode('=', $part, 2);
if (count($pair) !== 2) {
throw new InvalidArgumentException('Invalid initData');
}
$key = urldecode($pair[0]);
if (array_key_exists($key, $fields)) {
throw new InvalidArgumentException('Duplicate initData field');
}
$fields[$key] = urldecode($pair[1]);
}
$hash = $fields['hash'] ?? '';
unset($fields['hash']);
ksort($fields, SORT_STRING);
$lines = [];
foreach ($fields as $key => $value) {
$lines[] = $key.'='.$value;
}
$secret = hash_hmac('sha256', $token, 'WebAppData', true);
$expected = hash_hmac('sha256', implode("\n", $lines), $secret);
$date = $fields['auth_date'] ?? '';
if (!preg_match('/^[a-f0-9]{64}$/D', $hash) || !hash_equals($expected, $hash)
|| !ctype_digit($date) || (int) $date < $now - 600 || (int) $date > $now + 30) {
throw new InvalidArgumentException('Expired or invalid initData');
}
$user = json_decode($fields['user'] ?? '', true, 16, JSON_THROW_ON_ERROR);
if (!is_array($user) || !is_int($user['id'] ?? null) || $user['id'] < 1) {
throw new InvalidArgumentException('Missing Telegram user');
}
return $user['id'];
}
function authenticatedUser(): int
{
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
reply(['error' => 'POST required'], 405);
}
$raw = $_SERVER['HTTP_X_TELEGRAM_INIT_DATA'] ?? '';
try {
return miniUser(is_string($raw) ? $raw : '', setting('BOT_TOKEN'), time());
} catch (InvalidArgumentException|JsonException) {
reply(['error' => 'Откройте Mini App заново'], 401);
}
}
В запросе настроек нет доверенного user_id: API получает его только из authenticatedUser. Так пользователь не сможет подставить ID друга и выключить ему уведомления. Флаг разрешения писать из JavaScript также не используется как серверное доказательство — это только обратная связь для интерфейса.
Сохраним категории, пояс и часы тишины
<?php
declare(strict_types=1);
/** @return array<string,int|string|null> */
function preferences(PDO $db, int $user, int $now): array
{
sql($db, 'INSERT INTO preferences(user_id,updated_at) VALUES(?,?) ON CONFLICT(user_id) DO NOTHING', [$user, $now]);
return row(sql($db, 'SELECT * FROM preferences WHERE user_id=?', [$user]))
?? throw new RuntimeException('Preferences missing');
}
/** @param array<string,mixed> $data */
function savePreferences(PDO $db, int $user, array $data, int $now): void
{
foreach (['orders', 'offers', 'quiet'] as $name) {
if (!is_bool($data[$name] ?? null)) {
throw new InvalidArgumentException('Категории должны быть true или false');
}
}
$zone = $data['timezone'] ?? null;
if (!is_string($zone) || !in_array($zone, DateTimeZone::listIdentifiers(DateTimeZone::ALL_WITH_BC), true)) {
throw new InvalidArgumentException('Выберите часовой пояс IANA');
}
$minutes = [];
foreach (['start', 'end'] as $name) {
$value = $data[$name] ?? null;
if (!is_string($value) || !preg_match('/^([01][0-9]|2[0-3]):([0-5][0-9])$/D', $value, $match)) {
throw new InvalidArgumentException('Время должно иметь формат ЧЧ:ММ');
}
$minutes[$name] = (int) $match[1] * 60 + (int) $match[2];
}
if ($data['quiet'] && $minutes['start'] === $minutes['end']) {
throw new InvalidArgumentException('Начало и конец тишины должны различаться');
}
preferences($db, $user, $now);
sql($db, 'UPDATE preferences SET orders=?,offers=?,timezone=?,quiet=?,start_min=?,end_min=?,updated_at=? WHERE user_id=?',
[(int) $data['orders'], (int) $data['offers'], $zone, (int) $data['quiet'], $minutes['start'], $minutes['end'], $now, $user]);
}
/** @param array<string,int|string|null> $pref */
function isQuiet(array $pref, int $utc): bool
{
if ((int) $pref['quiet'] !== 1) {
return false;
}
$local = (new DateTimeImmutable('@'.$utc))->setTimezone(new DateTimeZone((string) $pref['timezone']));
$minute = (int) $local->format('G') * 60 + (int) $local->format('i');
$start = (int) $pref['start_min'];
$end = (int) $pref['end_min'];
return $start < $end ? $minute >= $start && $minute < $end : $minute >= $start || $minute < $end;
}
/** @param array<string,int|string|null> $pref */
function nextAllowed(array $pref, int $utc): int
{
if (!isQuiet($pref, $utc)) {
return $utc;
}
// Iterate real UTC minutes: skipped/repeated local DST times are not invented.
$candidate = intdiv($utc, 60) * 60 + 60;
for ($i = 0; $i < 2880; ++$i, $candidate += 60) {
if (!isQuiet($pref, $candidate)) {
return $candidate;
}
}
throw new RuntimeException('No allowed minute in the next 48 hours');
}
function enqueue(PDO $db, string $event, int $user, string $category, string $body, int $now, int $expires): void
{
if (!in_array($category, ['orders', 'offers'], true) || $expires <= $now || strlen($body) > 3000) {
throw new InvalidArgumentException('Invalid notification');
}
sql($db, 'INSERT INTO notifications(event_key,user_id,category,body,due_at,expires_at) VALUES(?,?,?,?,?,?)
ON CONFLICT(event_key) DO NOTHING', [$event, $user, $category, $body, $now, $expires]);
}
/** @return array<string,int|string|null>|null */
function claimNotification(PDO $db, int $now): ?array
{
return atomic($db, function () use ($db, $now): ?array {
$job = row(sql($db, "SELECT * FROM notifications WHERE state='pending' AND due_at<=? ORDER BY id LIMIT 1", [$now]));
if ($job === null) {
return null;
}
$pref = preferences($db, (int) $job['user_id'], $now);
$state = null;
if ((int) $job['expires_at'] <= $now) {
$state = 'expired';
} elseif ((int) $pref['blocked'] === 1) {
$state = 'blocked';
} elseif ((int) ($pref[(string) $job['category']] ?? 0) !== 1) {
$state = 'skipped';
}
if ($state !== null) {
sql($db, 'UPDATE notifications SET state=? WHERE id=?', [$state, (int) $job['id']]);
return null;
}
$due = nextAllowed($pref, $now);
if ($due > $now) {
sql($db, 'UPDATE notifications SET due_at=? WHERE id=?', [$due, (int) $job['id']]);
return null;
}
sql($db, "UPDATE notifications SET state='sending',claimed_at=?,attempts=attempts+1 WHERE id=?", [$now, (int) $job['id']]);
return $job;
});
}
Сервер проверяет типы переключателей, наличие пояса в базе PHP и формат часов. Значение timezone от устройства — подсказка, которую пользователь может изменить. Не определяйте пояс по языку Telegram: русскоязычный пользователь может жить в Берлине, а телефон временно иметь другой пояс.
nextAllowed перебирает реальные минуты UTC и переводит каждую в локальное время. Это небольшой, понятный вариант для учебной очереди: он корректно обходит пропущенный и повторённый час при сезонном переводе, не конструируя несуществующее локальное время. Максимум — 48 часов поиска. Для массовой отправки вычисление можно оптимизировать и кэшировать по настройкам, но тесты переходов времени нужно сохранить.
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/auth.php';
require dirname(__DIR__).'/preferences.php';
$user = authenticatedUser();
try {
$body = jsonBody();
$db = database();
if (($body['action'] ?? '') === 'save') {
savePreferences($db, $user, $body, time());
} elseif (($body['action'] ?? '') !== 'load') {
throw new InvalidArgumentException('Неизвестная операция');
}
$pref = preferences($db, $user, time());
reply(['settings' => $pref]);
} catch (InvalidArgumentException|JsonException $e) {
reply(['error' => $e instanceof JsonException ? 'Неверный JSON' : $e->getMessage()], 422);
}
Операция load также оформлена POST, чтобы авторизационный заголовок и единая проверка запроса использовались одинаково. Данные возвращаются с Cache-Control: no-store. Сохранение атомарно обновляет одну строку; две открытые вкладки используют правило «последнее сохранение побеждает». Если нужны предупреждения о конфликте редактирования, добавьте версию настроек.
Добавим форму и запрос разрешения
<!doctype html>
<html lang="ru"><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Уведомления</title>
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<style>
body{font:17px system-ui;padding:16px;color:var(--tg-theme-text-color,#111);background:var(--tg-theme-bg-color,#fff)}
label,button{display:block;margin:16px 0}button,select,input[type=time]{padding:12px;font:inherit;max-width:100%;box-sizing:border-box}
button{width:100%;min-height:48px}fieldset{border:0;padding:0;margin:0;min-width:0}
</style>
<h1>Настройки уведомлений</h1>
<form id="form"><fieldset id="fields" disabled>
<label><input id="orders" type="checkbox"> Статусы заказов</label>
<label><input id="offers" type="checkbox"> Предложения магазина</label>
<label>Часовой пояс <select id="timezone"></select></label>
<label><input id="quiet" type="checkbox"> Часы тишины</label>
<label>С <input id="start" type="time" value="22:00" required></label>
<label>До <input id="end" type="time" value="08:00" required></label>
<button>Сохранить</button></fieldset></form>
<button id="access" type="button">Разрешить боту писать</button>
<p id="status" role="status" aria-live="polite"></p>
<script>
const tg = window.Telegram?.WebApp;
const el = id => document.getElementById(id);
const detected = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
const zones = typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('timeZone') : ['Europe/Moscow','Asia/Yekaterinburg','Asia/Novosibirsk','Asia/Vladivostok'];
function addZone(zone) {
if (![...el('timezone').options].some(option => option.value === zone)) el('timezone').add(new Option(zone, zone));
}
['UTC',detected,...zones].forEach(addZone);
async function api(body) {
const response = await fetch('preferences-api.php', {method:'POST',
headers:{'Content-Type':'application/json','X-Telegram-Init-Data':tg?.initData || ''}, body:JSON.stringify(body)});
const data = await response.json();
if (!response.ok) throw new Error(data.error || 'Не удалось сохранить');
return data.settings;
}
const clock = minute => String(Math.floor(minute / 60)).padStart(2,'0') + ':' + String(minute % 60).padStart(2,'0');
async function load() {
try {
const p = await api({action:'load'});
['orders','offers','quiet'].forEach(key => el(key).checked = Number(p[key]) === 1);
addZone(p.timezone); el('timezone').value = p.timezone;
el('start').value = clock(Number(p.start_min)); el('end').value = clock(Number(p.end_min));
el('fields').disabled = false;
el('status').textContent = 'Проверьте пояс. Пояс устройства: ' + detected;
} catch (error) {el('status').textContent = error.message;}
}
el('form').onsubmit = async event => {
event.preventDefault(); el('fields').disabled = true;
try {
await api({action:'save', orders:el('orders').checked, offers:el('offers').checked,
quiet:el('quiet').checked, timezone:el('timezone').value, start:el('start').value, end:el('end').value});
el('status').textContent = 'Настройки сохранены. Разрешение писать запрашивается отдельно.';
} catch (error) {el('status').textContent = error.message;}
finally {el('fields').disabled = false;}
};
el('access').onclick = () => {
if (!tg?.isVersionAtLeast('6.9')) {
el('status').textContent = 'Обновите Telegram или откройте диалог с ботом и нажмите Start.';
return;
}
el('access').disabled = true;
try {
tg.requestWriteAccess(granted => {
el('access').disabled = false;
el('status').textContent = granted ? 'Разрешение получено. Выбранные категории не изменены.' : 'Разрешение не получено. Настройки сохранены.';
});
} catch (error) {el('access').disabled = false; el('status').textContent = error.message;}
};
tg?.ready(); load();
</script></html>
Форма сначала загружает серверные значения и только потом становится доступной. Ошибка загрузки не подменяет настройки пустыми переключателями. После сохранения пользователь видит подтверждение именно сохранения; после requestWriteAccess — результат отдельного запроса доступа.
Для поддерживаемых клиентов кнопка вызывает нативный диалог. При отказе категории сохраняются: человек может передумать позже. На старом клиенте предлагается обновление Telegram или запуск диалога с ботом. Кнопку запроса не вызываем автоматически на каждом открытии страницы и не повторяем диалог после отказа.
Отображённое разрешение не гарантирует доставку навсегда: пользователь может заблокировать бота. Поэтому реальный ответ sendMessage всё равно обрабатывается. Поле allows_write_to_pm из проверенного initData при наличии можно использовать для подсказки интерфейсу, но оно также относится к моменту запуска, а не к любому будущему сообщению.
Поставим сообщение и проверим настройки перед отправкой
<?php
declare(strict_types=1);
/**
* @param array<string, mixed> $params
* @return array{state: string, result?: mixed, code?: int, retry_after?: int}
*/
function telegram(string $method, array $params, bool $multipart = false): array
{
$curl = curl_init('https://api.telegram.org/bot'.setting('BOT_TOKEN').'/'.$method);
curl_setopt_array($curl, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 3, CURLOPT_TIMEOUT => 8,
CURLOPT_POSTFIELDS => $multipart ? $params : json_encode($params, JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => $multipart ? [] : ['Content-Type: application/json'],
]);
$raw = curl_exec($curl);
$status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if (!is_string($raw) || $status >= 500) {
return ['state' => 'unknown'];
}
$data = json_decode($raw, true);
if (!is_array($data)) {
return ['state' => 'unknown'];
}
if (($data['ok'] ?? null) === true) {
return ['state' => 'ok', 'result' => $data['result'] ?? null];
}
if (($data['ok'] ?? null) !== false || !is_int($data['error_code'] ?? null)) {
return ['state' => 'unknown'];
}
$parameters = $data['parameters'] ?? null;
$delay = is_array($parameters) ? ($parameters['retry_after'] ?? null) : null;
return ['state' => 'rejected', 'code' => $data['error_code'],
'retry_after' => is_int($delay) && $delay > 0 ? $delay : 60];
}
/** @return array<string, mixed> */
function incomingUpdate(): array
{
$secret = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST' || !is_string($secret)
|| !hash_equals(setting('WEBHOOK_SECRET'), $secret)) {
reply(['error' => 'Forbidden'], 403);
}
return jsonBody();
}
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/preferences.php';
if (PHP_SAPI !== 'cli' || !ctype_digit($argv[1] ?? '') || !preg_match('/^[a-z0-9-]{1,40}$/D', $argv[2] ?? '')) {
exit("Usage: php enqueue-demo.php USER_ID UNIQUE_EVENT_KEY\n");
}
$db = database();
$user = (int) $argv[1];
if (row(sql($db, 'SELECT user_id FROM preferences WHERE user_id=?', [$user])) === null) {
throw new RuntimeException('Open settings and save preferences first');
}
enqueue($db, $argv[2], $user, 'orders', 'Тестовый заказ готов к выдаче', time(), time() + 86400);
echo "Queued\n";
php enqueue-demo.php 123456789 order-demo-ready-user-123456789
Перед командой откройте Mini App своим тестовым аккаунтом и сохраните настройки. Замените число на его проверенный Telegram ID. В рабочем магазине enqueue вызывается серверным обработчиком изменения заказа и получает владельца из БД. Случайный ID из Mini App или публичного URL не должен выбирать адресата.
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/telegram.php';
require __DIR__.'/preferences.php';
if (PHP_SAPI !== 'cli') {
exit(1);
}
$db = database();
for ($i = 0; $i < 20; ++$i) {
$job = claimNotification($db, time());
if ($job === null) {
continue;
}
$result = telegram('sendMessage', ['chat_id' => (int) $job['user_id'], 'text' => (string) $job['body']]);
atomic($db, function () use ($db, $job, $result): void {
$state = 'unknown';
$due = time();
$messageId = null;
if ($result['state'] === 'ok') {
$state = 'sent';
$value = $result['result'] ?? null;
$messageId = is_array($value) && is_int($value['message_id'] ?? null) ? $value['message_id'] : null;
} elseif ($result['state'] === 'rejected') {
$state = 'failed';
if (($result['code'] ?? 0) === 403) {
$state = 'blocked';
sql($db, 'UPDATE preferences SET blocked=1 WHERE user_id=?', [(int) $job['user_id']]);
} elseif (($result['code'] ?? 0) === 429 && (int) $job['attempts'] < 4) {
$state = 'pending';
$due += $result['retry_after'] ?? 60;
}
}
sql($db, 'UPDATE notifications SET state=?,due_at=?,message_id=? WHERE id=?',
[$state, $due, $messageId, (int) $job['id']]);
});
if (($result['code'] ?? 0) === 429) {
break;
}
sleep(1);
}
php worker.php
Запускайте worker.php планировщиком раз в минуту с тем же окружением. Один запуск обрабатывает до 20 кандидатов; готовые к отправке сообщения разделены паузой. Поэтому время тишины задаёт нижнюю границу, а не обещание доставки ровно в 08:00: очередь и лимиты могут добавить задержку. Партия и скорость намеренно небольшие для примера.
claimNotification читает текущие настройки и фиксирует sending в одной короткой транзакции. Если категория выключена — skipped; срок события вышел — expired; у бота нет доступа — blocked; сейчас тихо — перенос due_at. Если пользователь изменил настройки, пока сообщение уже отправляется в HTTP-запросе, отменить этот запрос задним числом нельзя. Не обещайте мгновенно отозвать уже начатую отправку.
Подтверждённый 429 переносит попытку на retry_after, максимум до пяти попыток. Неопределённый ответ получает unknown без автоматической повторной отправки. Если процесс умер после sending, запись остаётся в этом состоянии для разбирательства; не сбрасывайте все старые sending в pending по таймеру. Подробный журнал доставки нужен до запуска больших рассылок.
Учтём блокировку и повторное разрешение
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/telegram.php';
$update = incomingUpdate();
$message = $update['message'] ?? null;
$from = is_array($message) ? ($message['from'] ?? null) : null;
$chat = is_array($message) ? ($message['chat'] ?? null) : null;
if (is_int($update['update_id'] ?? null) && is_array($message) && is_array($from) && is_array($chat)
&& is_int($from['id'] ?? null) && ($chat['id'] ?? null) === $from['id']
&& ($chat['type'] ?? '') === 'private'
&& (isset($message['write_access_allowed']) || ($message['text'] ?? '') === '/start')) {
// Only new jobs are eligible again. Old blocked/skipped jobs stay terminal.
$db = database();
atomic($db, function () use ($db, $update, $from): void {
if (sql($db, 'INSERT OR IGNORE INTO updates(id) VALUES(?)', [$update['update_id']])->rowCount() === 1) {
sql($db, 'UPDATE preferences SET blocked=0 WHERE user_id=?', [$from['id']]);
}
});
}
reply(['ok' => true]);
Зарегистрируйте прямой webhook Telegram следующим CLI-скриптом. Здесь принимаются только обновления message; если у бота уже есть обработчики других событий, сохраните их в общем обработчике и в allowed_updates, вместо установки второго webhook. Один бот не использует одновременно этот webhook и getUpdates.
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/telegram.php';
if (PHP_SAPI !== 'cli') {
exit(1);
}
$url = setting('WEBHOOK_URL');
if (!str_starts_with($url, 'https://')) {
throw new RuntimeException('HTTPS webhook required');
}
$result = telegram('setWebhook', [
'url' => $url, 'secret_token' => setting('WEBHOOK_SECRET'),
'allowed_updates' => ['message'],
]);
if ($result['state'] !== 'ok') {
throw new RuntimeException('Webhook not confirmed');
}
echo "Webhook configured\n";
php setup-webhook.php
Подтверждённый 403 при отправке закрывает дальнейшие попытки этому получателю флагом blocked. Разрешение восстанавливается по проверенному входящему write_access_allowed либо /start. Таблица updates исключает повторное применение уже обработанного события. В реальном общем webhook добавьте эту ветку к существующим обработчикам и используйте их общий журнал update_id.
Снятие blocked разрешает только новые уведомления; старые blocked и skipped не возвращаются в очередь. Не следует выдавать пользователю накопившуюся за месяц рекламу сразу после разблокировки. Уведомление о заказе имеет срок полезности: после expires_at его тоже не отправляем.
Проверим ночь, смену пояса и повторы
Выключите offers и поставьте событие offers: worker должен отметить skipped и не обращаться к Telegram.
Для 22:00–08:00 проверьте 21:59, 22:00, 07:59 и 08:00 по выбранному поясу. Только две средние точки тихие.
Проверьте дневной интервал 13:00–14:00: он не должен запрещать весь вечер.
Для Europe/Berlin проверьте весенний и осенний перевод часов на фиксированных UTC-моментах, а не изменением системного времени сервера.
Поставьте событие, затем выключите категорию до запуска worker. Оно должно стать skipped.
Повтор enqueue с тем же event_key оставляет одну запись. Изменение текста уже поставленного события при таком повторе намеренно игнорируется.
Откажите в requestWriteAccess: форма остаётся рабочей. Заблокируйте тестового бота: 403 должен остановить последующие попытки.
Настройки можно проверить без отправки: вызывайте isQuiet и nextAllowed с заранее заданными timestamp. Сам sendMessage проверяйте на отдельном тестовом аккаунте, а не на клиентской базе. Успешный ответ метода означает принятие сообщения Telegram, а не прочтение человеком.
Подключение BotGate и источники
При использовании BotGate проверка категорий и местного времени остаётся перед транспортным вызовом в вашем worker. Привязка пользователя к настройкам также остаётся у приложения. Для перехода на сервис используйте документацию, отдельно заменив авторизацию запросов и проверку входящего webhook. Смена транспорта не отменяет часы тишины и запрет пользователя писать боту.
Источники: requestWriteAccess и интерфейс Mini App, write_access_allowed в Message, DateTimeImmutable::setTimezone. Для расположения формы на телефоне пригодится руководство по iPhone и Android.