Перейти к содержанию
33 минут чтения
Тема: Практика Telegram Bot API · Модерация · Права участников · PHP

Как сделать Telegram-бота для модерации группы

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

Определим правила до включения санкций

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

  • Обрабатываем одну заранее настроенную супергруппу. restrictChatMember предназначен именно для супергрупп.

  • Первое и второе нарушение — удаление и предупреждение; с третьего за последние 24 часа — ограничение на один час.

  • В счётчик входят только неотменённые решения с подтверждённым удалением сообщения.

  • Сообщения администраторов, других ботов и сообщения от имени канала/анонимного администратора автоматически не наказываются.

  • Существующее персональное ограничение участника бот не заменяет своим.

Опубликуйте правило группы и путь обращения к модератору. Для первой проверки используйте отдельную тестовую супергруппу. В рабочей группе полезен предварительный режим наблюдения: вместо deleteMessage и restrictChatMember записывать предполагаемые решения, затем разобрать ложные срабатывания перед включением действий.

Выдадим боту необходимые права

Для примера нужны PHP 8.3+ на 64-битной системе, cURL, PDO SQLite и mbstring. Один бот использует одну SQLite-базу на локальном диске. Публичный корень сайта — только public/; common.php, telegram.php, runtime.php, bot.php, worker.php, init.php и schema.sql находятся уровнем выше. Создайте закрытую папку private с правом записи для приложения. Обычный PHP не читает .env автоматически: задайте переменные окружения и для PHP-FPM, и для CLI.

Окружение процесса · пример
BOT_TOKEN=TOKEN_FROM_BOTFATHER
BOT_DB_PATH=/srv/demo/private/bot.sqlite
WEBHOOK_SECRET=RANDOM_SECRET_FROM_PASSWORD_MANAGER
WEBHOOK_URL=https://example.com/webhook.php
BOT_ID=NUMERIC_ID_FROM_GETME
MOD_CHAT_ID=-1001234567890

Дополнительно установите расширение intl для нормализации международных доменов. BOT_ID получите через getMe. MOD_CHAT_ID — ID тестовой супергруппы; настройка защищает от случайного включения модерации во всех чатах, куда добавили бота.

Добавьте бота администратором с can_delete_messages и can_restrict_members. Первое право разрешает удаление чужих сообщений, второе — изменение ограничений участника. Право назначать администраторов этому примеру не нужно. Бот-администратор получает сообщения группы, необходимые для модерации; при диагностике также проверьте состав allowed_updates и тип обновления.

SQL · schema.sql
CREATE TABLE inbox (
    seq INTEGER PRIMARY KEY, update_id INTEGER NOT NULL UNIQUE,
    payload TEXT NOT NULL, state TEXT NOT NULL DEFAULT 'pending', received_at INTEGER NOT NULL
);
CREATE TABLE actions (
    action_key TEXT PRIMARY KEY, method TEXT NOT NULL,
    state TEXT NOT NULL, result TEXT, created_at INTEGER NOT NULL
);

CREATE TABLE cases (
    id INTEGER PRIMARY KEY, chat_id INTEGER NOT NULL, message_id INTEGER NOT NULL,
    user_id INTEGER NOT NULL, domain TEXT NOT NULL, created_at INTEGER NOT NULL,
    voided INTEGER NOT NULL DEFAULT 0, deleted INTEGER NOT NULL DEFAULT 0,
    mute_until INTEGER, UNIQUE(chat_id,message_id)
);
CREATE TABLE moderation_log (
    id INTEGER PRIMARY KEY, case_id INTEGER, actor_id INTEGER,
    event 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('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 · init.php
<?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";

cases фиксирует одно решение на chat_id + message_id. Редактирование сообщения не создаст второе предупреждение за тот же уже обработанный текст. moderation_log хранит этапы удаления, ограничения и отмены; полный текст сообщения для этого не требуется.

Удалим сообщение и учтём предупреждение

PHP · bot.php
<?php
declare(strict_types=1);
require_once __DIR__.'/policy.php';

function moderationLog(PDO $db, ?int $case, ?int $actor, string $event): void
{
    sql($db, 'INSERT INTO moderation_log(case_id,actor_id,event,created_at) VALUES(?,?,?,?)',
        [$case, $actor, $event, time()]);
}

function undoCase(PDO $db, int $chat, int $actor, int $id, int $update): void
{
    $moderator = apiObject('getChatMember', ['chat_id' => $chat, 'user_id' => $actor]);
    if (!isAdmin($moderator) || ($moderator['status'] !== 'creator' && ($moderator['can_restrict_members'] ?? false) !== true)) {
        return;
    }
    $case = row(sql($db, 'SELECT * FROM cases WHERE id=? AND chat_id=? AND voided=0', [$id, $chat]));
    if ($case === null) {
        return;
    }
    if ($case['mute_until'] !== null) {
        $member = apiObject('getChatMember', ['chat_id' => $chat, 'user_id' => (int) $case['user_id']]);
        if (($member['status'] ?? '') !== 'member') {
            $action = row(sql($db, 'SELECT state FROM actions WHERE action_key=?', ['mute:'.$id]));
            if (($action['state'] ?? '') !== 'ok' || !sameMute($member, (int) $case['mute_until'])) {
                moderationLog($db, $id, $actor, 'undo_requires_manual_review');
                telegramOnce($db, 'undo-conflict:'.$update, 'sendMessage', ['chat_id' => $chat,
                    'text' => 'Ограничение отличается от записанного ботом. Проверьте его вручную в управлении участником.']);
                return;
            }
            $lift = telegramOnce($db, 'undo:'.$id.':'.$update, 'restrictChatMember', [
                'chat_id' => $chat, 'user_id' => (int) $case['user_id'],
                'permissions' => permissions(true), 'use_independent_chat_permissions' => true,
            ]);
            if ($lift['state'] !== 'ok') {
                moderationLog($db, $id, $actor, 'undo_'.$lift['state']);
                return;
            }
        }
    }
    sql($db, 'UPDATE cases SET voided=1 WHERE id=?', [$id]);
    moderationLog($db, $id, $actor, 'voided');
    telegramOnce($db, 'undo-done:'.$update, 'sendMessage', ['chat_id' => $chat,
        'text' => 'Решение №'.$id.' отменено. Удалённое сообщение автоматически восстановить нельзя.']);
}

/** @param array<string,mixed> $update */
function handleUpdate(PDO $db, array $update): void
{
    $m = $update['message'] ?? $update['edited_message'] ?? null;
    if (!is_array($m) || !is_array($m['chat'] ?? null) || ($m['chat']['type'] ?? '') !== 'supergroup'
        || ($m['chat']['id'] ?? null) !== (int) setting('MOD_CHAT_ID') || !is_int($m['message_id'] ?? null)
        || isset($m['sender_chat']) || !is_array($m['from'] ?? null) || !is_int($m['from']['id'] ?? null)
        || ($m['from']['is_bot'] ?? false) === true || !is_int($update['update_id'] ?? null)) {
        return;
    }
    $chat = $m['chat']['id']; $user = $m['from']['id'];
    $text = is_string($m['text'] ?? null) ? $m['text'] : '';
    if (preg_match('/^\/undo(?:@[a-zA-Z0-9_]+)? ([1-9][0-9]*)$/D', $text, $match)) {
        undoCase($db, $chat, $user, (int) $match[1], $update['update_id']);
        return;
    }
    $domain = forbiddenHost(linkHosts($m), ['blocked.example']);
    if ($domain === null) {
        return;
    }
    $bot = apiObject('getChatMember', ['chat_id' => $chat, 'user_id' => (int) setting('BOT_ID')]);
    if (!isAdmin($bot) || ($bot['can_delete_messages'] ?? false) !== true || ($bot['can_restrict_members'] ?? false) !== true) {
        moderationLog($db, null, null, 'bot_rights_missing');
        return;
    }
    $member = apiObject('getChatMember', ['chat_id' => $chat, 'user_id' => $user]);
    if (isAdmin($member)) {
        return;
    }
    $inserted = sql($db, 'INSERT INTO cases(chat_id,message_id,user_id,domain,created_at) VALUES(?,?,?,?,?)
        ON CONFLICT(chat_id,message_id) DO NOTHING', [$chat, $m['message_id'], $user, $domain, time()])->rowCount();
    if ($inserted === 0) {
        return;
    }
    $id = (int) $db->lastInsertId();
    $deleted = telegramOnce($db, 'delete:'.$id, 'deleteMessage', ['chat_id' => $chat, 'message_id' => $m['message_id']]);
    moderationLog($db, $id, null, 'delete_'.$deleted['state']);
    if ($deleted['state'] !== 'ok') {
        return;
    }
    sql($db, 'UPDATE cases SET deleted=1 WHERE id=?', [$id]);
    $count = (int) (row(sql($db, 'SELECT COUNT(*) AS n FROM cases WHERE chat_id=? AND user_id=?
        AND voided=0 AND deleted=1 AND created_at>?', [$chat, $user, time()-86400]))['n'] ?? 0);
    $outcome = 'Предупреждение '.$count.' за последние 24 часа.';
    // Do not overwrite an existing restriction applied by another administrator.
    if ($count >= 3 && ($member['status'] ?? '') === 'member') {
        $fresh = apiObject('getChatMember', ['chat_id' => $chat, 'user_id' => $user]);
        if (($fresh['status'] ?? '') === 'member') {
            $until = time()+3600;
            sql($db, 'UPDATE cases SET mute_until=? WHERE id=?', [$until, $id]);
            $mute = telegramOnce($db, 'mute:'.$id, 'restrictChatMember', ['chat_id' => $chat, 'user_id' => $user,
                'permissions' => permissions(false), 'use_independent_chat_permissions' => true, 'until_date' => $until]);
            moderationLog($db, $id, null, 'mute_'.$mute['state']);
            $outcome .= $mute['state'] === 'ok' ? ' Ограничение на час применено.' : ' Ограничение не подтверждено, нужен модератор.';
        }
    }
    telegramOnce($db, 'warning:'.$id, 'sendMessage', ['chat_id' => $chat,
        'text' => 'Удалена запрещённая ссылка. Решение №'.$id.'. '.$outcome.' Для администратора: /undo '.$id]);
}

Перед решением код проверяет текущие права бота и статус автора через getChatMember. Если проверка не удалась, событие уходит в failed без автоматического наказания. Администратор исключается до создания case; sender_chat отсекается раньше, чтобы не пытаться ограничить технического отправителя вместо человека.

Сначала фиксируем case, затем выполняем deleteMessage и сохраняем результат. Только подтверждённое удаление увеличивает счётчик. При неизвестном результате администратор разбирает состояние вручную: бот не заявляет, что сообщение удалено, и не накладывает дополнительную санкцию.

Перед ограничением ещё раз читаем состояние участника. Если он уже restricted, бот не перезаписывает настройки другого администратора и не продлевает их до своего срока. Для нового ограничения until_date равен текущему времени плюс час, use_independent_chat_permissions=true, перечисленные права выставлены явно.

Период меньше 30 секунд или больше 366 дней Telegram трактует как бессрочное ограничение. Поэтому не используйте until_date=time()+5 для «короткого теста» и не передавайте длительность вместо Unix timestamp. В нашем примере час достаточно далёк от этих границ.

Часть проверок и действий разделена внешними HTTP-запросами. Telegram не предоставляет условного изменения «только если права всё ещё такие же». Если администраторы одновременно меняют ограничения вручную, абсолютной защиты от гонки нет: используйте единый порядок управления санкциями и журнал группы.

Подключим API и надёжно примем обновление

PHP · telegram.php
<?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 · runtime.php
<?php
declare(strict_types=1);

/**
 * @param array<string,mixed> $params
 * @return array<string,mixed>
 */
function apiObject(string $method, array $params): array
{
    $answer = telegram($method, $params);
    $object = $answer['result'] ?? null;
    if ($answer['state'] !== 'ok' || !is_array($object)) {
        throw new RuntimeException('Telegram check failed: '.$method);
    }
    $result = [];
    foreach ($object as $key => $value) {
        if (!is_string($key)) {
            throw new RuntimeException('Invalid API object');
        }
        $result[$key] = $value;
    }
    return $result;
}

/**
 * @param array<string,mixed> $params
 * @return array{state:string,result?:mixed}
 */
function telegramOnce(PDO $db, string $key, string $method, array $params): array
{
    $inserted = sql($db, "INSERT INTO actions(action_key,method,state,created_at) VALUES(?,?,'sending',?)
        ON CONFLICT(action_key) DO NOTHING", [$key, $method, time()])->rowCount();
    if ($inserted === 0) {
        $old = row(sql($db, 'SELECT state,result FROM actions WHERE action_key=?', [$key]));
        return ['state' => (string) ($old['state'] ?? 'unknown'),
            'result' => json_decode((string) ($old['result'] ?? 'null'), true)];
    }
    $answer = telegram($method, $params);
    sql($db, 'UPDATE actions SET state=?,result=? WHERE action_key=?',
        [$answer['state'], json_encode($answer['result'] ?? null, JSON_THROW_ON_ERROR), $key]);
    return $answer;
}

/** @param array<string,mixed> $member */
function isAdmin(array $member): bool
{
    return in_array($member['status'] ?? '', ['creator', 'administrator'], true);
}
PHP · public/webhook.php
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/telegram.php';
$update = incomingUpdate();
if (!is_int($update['update_id'] ?? null)) {
    reply(['error' => 'Invalid update'], 422);
}
sql(database(), 'INSERT INTO inbox(update_id,payload,received_at) VALUES(?,?,?)
    ON CONFLICT(update_id) DO NOTHING',
    [$update['update_id'], json_encode($update, JSON_THROW_ON_ERROR), time()]);
reply(['ok' => true]);

Webhook сначала проверяет секретный заголовок Telegram и сохраняет update_id с исходными данными в inbox. Только после записи возвращается 200. Повтор update_id не создаёт вторую задачу. Это прямой webhook Telegram; проверка входящих сообщений BotGate имеет другой контракт.

telegramOnce фиксирует отдельную исходящую операцию по ключу. При повторном вызове возвращается записанный результат. Между внешним API и SQLite нет общей транзакции: при таймауте получается unknown, а при аварии процесса может остаться sending. Такие операции автоматически не повторяем. Эта небольшая реализация выбирает защиту от повторного действия ценой ручного восстановления неподтверждённых операций.

Ответ rejected также не повторяется автоматически, включая 429. В рабочей очереди можно добавить ограниченные повторы только подтверждённого отказа с учётом retry_after; не возвращайте все sending и unknown в pending. Подробности — в руководстве о дублях.

Запустим обработчик и проверим журнал

PHP · worker.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/telegram.php';
require __DIR__.'/runtime.php';
require __DIR__.'/bot.php';
if (PHP_SAPI !== 'cli') {
    exit(1);
}
$lock = fopen(setting('BOT_DB_PATH').'.worker.lock', 'c');
if ($lock === false || !flock($lock, LOCK_EX | LOCK_NB)) {
    exit(0);
}
$db = database();
for ($i = 0; $i < 100; ++$i) {
    $entry = row(sql($db, "SELECT * FROM inbox WHERE state='pending' ORDER BY seq LIMIT 1"));
    if ($entry === null) {
        break;
    }
    sql($db, "UPDATE inbox SET state='processing' WHERE seq=?", [(int) $entry['seq']]);
    try {
        $update = json_decode((string) $entry['payload'], true, 32, JSON_THROW_ON_ERROR);
        if (!is_array($update)) {
            throw new RuntimeException('Invalid stored update');
        }
        handleUpdate($db, $update);
        sql($db, "UPDATE inbox SET state='done',payload='{}' WHERE seq=?", [(int) $entry['seq']]);
    } catch (Throwable) {
        sql($db, "UPDATE inbox SET state='failed' WHERE seq=?", [(int) $entry['seq']]);
        error_log('Update failed: '.(int) $entry['update_id']);
    }
}
flock($lock, LOCK_UN);
PHP · setup-webhook.php
<?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 required');
$result = telegram('setWebhook', [
    'url' => $url, 'secret_token' => setting('WEBHOOK_SECRET'),
    'allowed_updates' => ['message','edited_message'],
]);
if ($result['state'] !== 'ok') throw new RuntimeException('Webhook not confirmed');
echo "Webhook configured\n";
Shell · запуск
php init.php
php setup-webhook.php
php worker.php

Во время разработки запускайте worker.php после тестового сообщения. На сервере настройте его регулярный запуск, например раз в минуту; для ответов без минутной задержки используйте управляемый постоянно работающий процесс. Один проход ограничен 100 обновлениями. Файловая блокировка не даёт двум worker обрабатывать события параллельно; все процессы должны видеть один локальный файл базы и блокировки.

SQL · состояние обработки
SELECT update_id,state,received_at FROM inbox WHERE state <> 'done';
SELECT action_key,method,state,created_at FROM actions ORDER BY created_at DESC LIMIT 20;

После успешной обработки тело update удаляется из inbox, идентификатор остаётся для защиты от повтора. failed и processing требуют разбора; в них ещё могут быть данные переписки. Ограничьте доступ, установите срок хранения и очистку после расследования. Ответ 200 webhook подтверждает приём, а не успешную отправку или изменение прав. Не запускайте эти примеры на клиентском боте до проверки в отдельном тестовом окружении.

Отменим ошибочное решение

Команда · администратор отправляет в той же группе
/undo 123

Число — ID решения из предупреждения, не Telegram ID участника. Проверяется принадлежность case той же группе и актуальное право администратора ограничивать участников. Обычный пользователь не сможет отменить санкцию, повторив видимую команду.

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

Для подтверждённого собственного ограничения restrictChatMember вызывается со всеми разрешениями true. Это снимает персональные ограничения, а общие правила группы продолжают действовать. Если участник уже обычный member, повторно менять его права не требуется. Забаненного, вышедшего или иначе изменённого участника пример отправляет на ручную проверку.

При unknown или sending у операции mute бот также требует ручного разбора. Совпавший срок сам по себе не является доказательством, что именно эта операция была успешно применена. Такая осторожность полезнее безусловного «разрешить всё» по любой команде администратора.

Удалённое сообщение вернуть через обратный вызов deleteMessage нельзя. После отмены попросите автора отправить исправленный текст заново. Журнал решения сохраняется с отметкой отмены; удаление case лишило бы поддержку возможности объяснить, что произошло.

Что смотреть при ошибках

SQL · журнал конкретного решения
SELECT * FROM cases WHERE id = 123;
SELECT actor_id,event,created_at FROM moderation_log WHERE case_id = 123 ORDER BY id;
SELECT action_key,state FROM actions WHERE action_key IN ('delete:123','mute:123');

delete_ok и mute_ok — подтверждённые ответы API. delete_rejected может означать недостаток прав, неподходящий тип сообщения или истечение срока удаления: обычное ограничение deleteMessage — менее 48 часов. delete_unknown требует проверки группы; повторный API-запрос не должен добавлять ещё одно предупреждение.

При bot_rights_missing проверьте права именно того бота, чей токен используется процессом. При undo_requires_manual_review сравните журнал Telegram с case. Не чините проблему массовой очисткой actions: это снимет защиту от повторных действий и может повторно ограничить участников.

Маленький worker не восстанавливает автоматически цепочку после аварии в середине решения. Например, после подтверждённого удаления процесс может остановиться до записи deleted=1. Для промышленной очереди нужны поэтапные состояния и сверка результатов; в этом примере такие случаи видны по незавершённым inbox/actions и обрабатываются модератором.

Проверим правила на тестовой группе

  • Ссылка blocked.example в обычном тексте и в подписи к фото приводит к одному решению.

  • Эмодзи перед ссылкой не сдвигает её разбор. text_link с нейтральной подписью проверяется по настоящему URL.

  • sub.blocked.example запрещён, а blocked.example.evil.test не совпадает с правилом.

  • Повтор update и edited_message уже обработанного сообщения не увеличивают число предупреждений.

  • Администратор и анонимный sender_chat не получают автоматического ограничения.

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

  • Обычный участник отправляет /undo: ничего не меняется. Уполномоченный администратор отменяет собственную санкцию бота.

  • После ручного изменения срока другим администратором /undo требует разбора и не снимает новое ограничение.

  • Снимите права бота: он должен записать проблему, а не имитировать успешное удаление.

Проверку URL и расчёт счётчика можно выполнить без Telegram. Для API-тестов подмените транспорт ответами ok, rejected и unknown. Реальное удаление и ограничение проверяйте только в своей тестовой супергруппе с согласованными тестовыми участниками.

BotGate и документация прав

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

Источники: restrictChatMember, ChatPermissions, deleteMessage, MessageEntity. Если обновления не приходят, начните с диагностики сообщений в группе.