Перейти к содержанию
30 минут чтения
Тема: Практика Telegram Bot API · request_chat · Интеграции · PHP

Как дать пользователю выбрать группу или канал для уведомлений

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

Что даёт выбор чата и чего он не подтверждает

Кнопка request_chat открывает нативный список подходящих чатов. После выбора бот получает служебное message.chat_shared с request_id и chat_id. Это удобнее, чем просить скопировать отрицательный ID или добавить случайного бота для определения номера группы.

Команда /group, кнопка Выбрать группу, выбор своего чата, проверки прав и пробная отправка; только затем сообщение Чат подключён.
Команда /group, кнопка Выбрать группу, выбор своего чата, проверки прав и пробная отправка; только затем сообщение Чат подключён.
Схема сценария /group из статьи. «Выбрать группу» — кнопка reply-клавиатуры с request_chat. Название группы условное; нативное окно Telegram не воспроизведено.

Полученный идентификатор ещё не является рабочей интеграцией. Пользователь мог нажать старую кнопку; бот мог потерять права между выбором и отправкой; очередь могла обрабатывать уже отменённый запрос. Поэтому связываем request_id с пользователем и сроком действия, затем отдельно проверяем чат и делаем пробную отправку.

  • Кнопка находится в обычной reply-клавиатуре, не в inline_keyboard, и используется в личном чате с ботом.

  • Выбор группы и канала — два разных запроса с chat_is_channel=false/true.

  • Доступ к уведомлениям не подтверждается названием или username чата. Храним числовой chat_id в 64-битном поле.

  • В примере у каждого пользователя одна активная интеграция. Успешный новый выбор заменяет предыдущий адресат; неуспешный оставляет прежний.

Для компактного безопасного сценария подключение разрешено только владельцу чата. Бот должен быть заранее добавлен администратором. Это сознательное ограничение примера, а не общее требование Telegram: ниже объясним, как расширить сценарий для администраторов, не ослабляя серверную проверку.

Подготовим бота, базу и идентификатор

Для примера нужны 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
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 chat_requests (
    id INTEGER PRIMARY KEY, user_id INTEGER NOT NULL, kind TEXT NOT NULL,
    expires_at INTEGER NOT NULL, state TEXT NOT NULL DEFAULT 'pending', selected_chat INTEGER
);
CREATE TABLE integrations (
    user_id INTEGER PRIMARY KEY, chat_id INTEGER NOT NULL, kind TEXT NOT NULL,
    active INTEGER NOT NULL, confirmed_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";

BOT_ID получите через getMe тем же токеном, которым отправляете сообщения; это числовой ID самого бота. Не используйте username или ID владельца. В канале дайте боту право публикации, в группе — минимальные административные права, достаточные для отправки и надёжной проверки участников.

Добавление администратором здесь нужно не только для отправки: getChatMember гарантирован для проверки других пользователей, когда сам бот — администратор. Если сервису принципиально нельзя выдавать административные права, потребуется другой сценарий подтверждения доступа; один chat_shared проблему не решает.

chat_requests хранит одноразовый запрос выбора, а integrations — только подтверждённое подключение. В большом сервисе добавьте к обеим таблицам ID организации или проекта из авторизованной серверной сессии. Telegram ID сам по себе не доказывает право управлять чужим проектом сайта. Для связи аккаунтов используйте привязку сайта и Telegram.

Покажем кнопку и проверим выбранный чат

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

function checkDestination(int $owner, int $chat, string $kind): void
{
    $details = apiObject('getChat', ['chat_id' => $chat]);
    $type = $details['type'] ?? '';
    if ($kind === 'channel' ? $type !== 'channel' : !in_array($type, ['group', 'supergroup'], true)) {
        throw new DomainException('Тип чата изменился');
    }
    if (($details['is_forum'] ?? false) === true) {
        throw new DomainException('Для форума выберите также тему в отдельном сценарии');
    }
    // Requiring the bot to be admin makes getChatMember checks reliable for other users.
    $bot = apiObject('getChatMember', ['chat_id' => $chat, 'user_id' => (int) setting('BOT_ID')]);
    if (!isAdmin($bot) || ($kind === 'channel' && ($bot['can_post_messages'] ?? false) !== true)) {
        throw new DomainException('Добавьте бота администратором с правом отправки');
    }
    $member = apiObject('getChatMember', ['chat_id' => $chat, 'user_id' => $owner]);
    if (($member['status'] ?? '') !== 'creator') {
        throw new DomainException('Подключать чат в этом примере может только его владелец');
    }
}

function requestDestination(PDO $db, int $user, string $kind, int $update): void
{
    $id = random_int(1, 2147483647);
    sql($db, "UPDATE chat_requests SET state='cancelled' WHERE user_id=? AND state='pending'", [$user]);
    sql($db, 'INSERT INTO chat_requests(id,user_id,kind,expires_at) VALUES(?,?,?,?)', [$id, $user, $kind, time()+600]);
    telegramOnce($db, 'choose:'.$update, 'sendMessage', [
        'chat_id' => $user, 'text' => 'Выберите свой чат. Бот должен быть добавлен администратором. Запрос действует 10 минут.',
        'reply_markup' => ['keyboard' => [[['text' => 'Выбрать '.($kind === 'channel' ? 'канал' : 'группу'),
            'request_chat' => ['request_id' => $id, 'chat_is_channel' => $kind === 'channel',
                'chat_is_created' => true, 'bot_is_member' => true, 'chat_is_forum' => false, 'request_title' => true]]]],
            'resize_keyboard' => true, 'one_time_keyboard' => true],
    ]);
}

function connectDestination(PDO $db, int $user, int $request, int $chat, int $update): void
{
    $pending = row(sql($db, "SELECT * FROM chat_requests WHERE id=? AND user_id=? AND state='pending' AND expires_at>?",
        [$request, $user, time()]));
    if ($pending === null) {
        telegramOnce($db, 'stale:'.$update, 'sendMessage', ['chat_id' => $user, 'text' => 'Запрос устарел. Используйте /group или /channel.']);
        return;
    }
    sql($db, "UPDATE chat_requests SET state='checking',selected_chat=? WHERE id=?", [$chat, $request]);
    try {
        checkDestination($user, $chat, (string) $pending['kind']);
        $test = telegramOnce($db, 'test:'.$request, 'sendMessage', ['chat_id' => $chat,
            'text' => 'Проверка подключения уведомлений. Этот чат выбран его владельцем.']);
        $ok = $test['state'] === 'ok';
        atomic($db, function () use ($db, $ok, $user, $chat, $pending, $request): void {
            if ($ok) {
                sql($db, 'INSERT INTO integrations VALUES(?,?,?,1,?) ON CONFLICT(user_id) DO UPDATE SET
                    chat_id=excluded.chat_id,kind=excluded.kind,active=1,confirmed_at=excluded.confirmed_at',
                    [$user, $chat, (string) $pending['kind'], time()]);
            }
            sql($db, 'UPDATE chat_requests SET state=? WHERE id=?', [$ok ? 'confirmed' : 'unconfirmed', $request]);
        });
        $text = $ok ? 'Чат подключён. Отключить: /disconnect' : 'Пробная отправка не подтверждена. Интеграция не включена.';
    } catch (Throwable) {
        sql($db, "UPDATE chat_requests SET state='failed' WHERE id=?", [$request]);
        $text = 'Не удалось проверить доступ. Проверьте владельца чата и права бота, затем начните выбор заново.';
    }
    telegramOnce($db, 'connection-result:'.$request, 'sendMessage', ['chat_id' => $user, 'text' => $text,
        'reply_markup' => ['remove_keyboard' => true]]);
}

/** @param array<string,mixed> $update */
function handleUpdate(PDO $db, array $update): void
{
    $m = $update['message'] ?? null;
    if (!is_array($m) || !is_array($m['chat'] ?? null) || !is_array($m['from'] ?? null)
        || ($m['chat']['type'] ?? '') !== 'private' || !is_int($m['from']['id'] ?? null)
        || ($m['chat']['id'] ?? null) !== $m['from']['id'] || !is_int($update['update_id'] ?? null)) {
        return;
    }
    $user = $m['from']['id']; $id = $update['update_id']; $text = $m['text'] ?? '';
    if ($text === '/disconnect') {
        atomic($db, function () use ($db, $user): void {
            sql($db, 'UPDATE integrations SET active=0 WHERE user_id=?', [$user]);
            sql($db, "UPDATE chat_requests SET state='cancelled' WHERE user_id=? AND state='pending'", [$user]);
        });
        telegramOnce($db, 'disconnect:'.$id, 'sendMessage', ['chat_id' => $user, 'text' => 'Уведомления отключены.',
            'reply_markup' => ['remove_keyboard' => true]]);
    } elseif ($text === '/group' || $text === '/channel') {
        requestDestination($db, $user, $text === '/channel' ? 'channel' : 'group', $id);
    } elseif (is_array($m['chat_shared'] ?? null) && is_int($m['chat_shared']['request_id'] ?? null)
        && is_int($m['chat_shared']['chat_id'] ?? null)) {
        connectDestination($db, $user, $m['chat_shared']['request_id'], $m['chat_shared']['chat_id'], $id);
    }
}

Пользователь пишет /group или /channel. Сервер генерирует request_id в диапазоне знакового 32-битного числа, связывает его с текущим пользователем и даёт десять минут на выбор. Предыдущий незавершённый запрос этого пользователя отменяется. Поэтому старая клавиатура не сможет незаметно заменить новое подключение.

chat_is_created=true фильтрует чаты владельца, bot_is_member=true — чаты, где бот уже присутствует. Эти условия улучшают список в Telegram, но не заменяют checkDestination. На сервере повторно проверяются реальный тип чата, статус бота и статус пользователя creator. Ошибка или недоступность проверки не трактуется как разрешение.

Forum-группы исключены: для уведомления в конкретную тему нужен ещё message_thread_id. Произвольная отправка в общий раздел такого чата может быть неудобной или невозможной из-за настроек темы. Для форумов добавьте отдельный шаг выбора темы по руководству об отправке в топики.

После проверок sendMessage отправляет нейтральное сообщение без персональных данных. Только подтверждённый ok включает интеграцию. Если ответ потерян, пробное сообщение могло появиться, но интеграция остаётся unconfirmed. Пользователь повторяет подключение осознанно; приложение не объявляет успех по одному факту выбора чата.

Подключим 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'],
]);
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 подтверждает приём, а не успешную отправку или изменение прав. Не запускайте эти примеры на клиентском боте до проверки в отдельном тестовом окружении.

Используем подтверждённый чат для уведомления

PHP · notify.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' || !ctype_digit($argv[1] ?? '') || !preg_match('/^[a-zA-Z0-9_-]{1,64}$/D', $argv[2] ?? '')) {
    exit("Usage: php notify.php OWNER_TELEGRAM_ID EVENT_ID\n");
}
// Share the same lock with worker.php: disconnect and sending must not run in parallel.
$lock = fopen(setting('BOT_DB_PATH').'.worker.lock', 'c');
if ($lock === false || !flock($lock, LOCK_EX)) {
    exit(1);
}
$db = database(); $user = (int) $argv[1];
$target = row(sql($db, 'SELECT * FROM integrations WHERE user_id=? AND active=1', [$user]));
if ($target === null) {
    exit("No active integration\n");
}
try {
    checkDestination($user, (int) $target['chat_id'], (string) $target['kind']);
} catch (Throwable) {
    sql($db, 'UPDATE integrations SET active=0 WHERE user_id=?', [$user]);
    exit("Integration suspended; check access and reconnect\n");
}
$result = telegramOnce($db, 'notice:'.$user.':'.$argv[2], 'sendMessage', [
    'chat_id' => (int) $target['chat_id'], 'text' => 'Тестовое уведомление: новая заявка в вашем сервисе.',
]);
echo $result['state']."\n";
Shell · пробное бизнес-событие
php notify.php 123456789 demo-event-001

Замените число на Telegram ID владельца, который завершил подключение. Скрипт предназначен для доверенного CLI или внутреннего обработчика сервиса, а не для публичного URL с произвольным user_id. В реальной заявке адресат определяется принадлежностью проекта, а ключ события — стабильным ID заявки и типа уведомления.

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

Ключ notice содержит владельца и ID события. Повтор команды с тем же ключом не отправит уведомление снова, даже если пользователь успел сменить чат. Если нужно сознательно повторить отправку в другое место, это отдельное действие с собственным ключом и понятным журналом, а не автоматический повтор старого события.

Отключение и изменение прав

Команда /disconnect принимается только в личном диалоге текущего пользователя. Она выключает его интеграцию и отменяет незавершённые запросы выбора. Бот не выходит из группы и не удаляет уже опубликованные сообщения: пользователь может продолжать использовать его для других функций.

notify.php и worker.php используют одну блокировку. Пока выполняется отправка, команда отключения ждёт обработки очередью; уже начатый HTTP-запрос отменить нельзя. Для интерфейса сервиса показывайте подтверждение после фактического обновления active, а не сразу после нажатия кнопки пользователем.

Удаление бота из чата, снятие права публикации или смена владельца обнаруживаются при следующей проверке. При миграции обычной группы в супергруппу появляется новый chat_id. Наш пример при ошибке приостанавливает подключение и требует выбрать чат заново; для автоматического переноса нужно отдельно обработать migrate_to_chat_id и повторно проверить доступ.

Если пользователь выбирает новый чат, а проверка не удалась, старая активная интеграция остаётся. Сообщите это рядом с формой или предложите сначала /disconnect, если требуется немедленно прекратить отправку в прежнее место. Такой порядок предотвращает случайную потерю рабочего канала из-за ошибочного выбора.

Как разрешить подключение администраторам

Для более гибкого продукта вместо chat_is_created можно задать user_administrator_rights и bot_administrator_rights. Набор прав бота должен быть подмножеством требуемых прав пользователя; Telegram может выдать запрошенные права, если это допустимо. Передавайте полный объект ChatAdministratorRights по текущему API, а не случайный набор флагов из старого примера.

Одновременно измените checkDestination: определите, каким администраторам разрешено подключать сервис. Например, право публикации в канале ещё не обязательно означает право привязать корпоративную CRM. В многопользовательском сервисе нужны и права в Telegram, и роль в вашей организации.

Не удаляйте проверку creator в коде, оставив только успешный sendMessage: бот может писать в чат, которым подключающий человек вообще не вправе управлять. Пробная отправка подтверждает возможность доставки, а не полномочия пользователя.

Проверим подключение от начала до конца

  • Добавьте тестового бота администратором в свою тестовую группу и канал. Для канала включите публикацию.

  • Отправьте /group, выберите группу и убедитесь, что тестовое сообщение пришло, а integrations.active стал 1.

  • Передайте chat_shared с request_id другого пользователя: подключения не должно быть.

  • Нажмите старую кнопку после нового /group или по истечении десяти минут: получите сообщение об устаревшем запросе.

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

  • Отправьте одно событие notify.php дважды: в чате должно быть одно уведомление.

  • Выполните /disconnect, затем notify.php с новым событием: отправки не будет.

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

Название чата и фото в chat_shared используются только для интерфейса. Не выполняйте HTML/Markdown-разметку из названия без экранирования. В этом примере название вообще не копируется в исходящее сообщение, чтобы сосредоточиться на проверке подключения.

BotGate и источники

При работе через BotGate параметры reply_markup и служебное chat_shared должны проходить без изменения структуры. Получение идентификатора, владение интеграцией, проверки getChatMember и активность подключения остаются вашей бизнес-логикой. Настройки транспорта и webhook — в документации.

Источники: интерфейс выбора чатов, KeyboardButtonRequestChat, ChatShared, getChatMember.