Користувачі та чати
Групи
Группа (Group) в Telegram — это коллективный чат, который может быть обычной группой (legacy-формат до 200 участников) или супергруппой (Supergroup) вместимостью до 200 000 пользователей. Для разработчика разница между ними принципиальна: у супергрупп идентификатор chat_id всегда начинается с префикса -100 (например, -1001234567890), доступны расширенные права администраторов, закрепление сообщений, медленный режим, история для новых участников и разделение на темы (форумы).
В Bot API в 99% случаев вы будете работать именно с супергруппами, так как обычные группы автоматически мигрируют в супергруппы при росте чата или изменении настроек публичности. Поле message.chat.type в таких чатах возвращает значение supergroup.
Типы групп и как их различить в JSON
При получении обновлений (через Webhook или Long Polling) тип чата передается в объекте Chat. Вот пример JSON-ответа, когда пользователь отправляет сообщение в супергруппу:
{
"ok": true,
"result": [
{
"update_id": 54321098,
"message": {
"message_id": 1024,
"date": 1710000000,
"chat": {
"id": -1001987654321,
"type": "supergroup",
"title": "PHP Backend Developers",
"username": "php_backend_chat",
"is_forum": false
},
"from": {
"id": 987654321,
"is_bot": false,
"first_name": "Сергей",
"username": "sergey_php"
},
"text": "Всем привет! Как правильно банить юзеров через API?"
}
}
]
}При анализе входящего JSON обращайте внимание на следующие поля:
chat.id— уникальный 64-битный идентификатор чата. Для супергрупп он всегда отрицательный и начинается с-100.chat.type— содержит строкуsupergroupилиgroup(для старых legacy-групп).chat.is_forum— возвращаетtrue, если в супергруппе включены топики (разделы). В этом случае сообщения будут содержать дополнительное полеmessage_thread_id.chat.username— публичный юзернейм группы (если он задан). У приватных групп это поле отсутствует.
Добавление бота в группу и первое событие
Бот не может самостоятельно вступить в группу — его должен пригласить пользователь, имеющий на это права. В момент добавления бота Telegram присылает обновление с полем new_chat_members. Это идеальная точка входа, чтобы зафиксировать появление бота в новом чате, сохранить chat_id в базу данных и отправить приветственное сообщение.
Используем функцию telegramApi(), которую мы сделали в главе
Первый запрос: getMe.
Здесь только вызываем её — реализацию не копируем.
<?php
// Предполагаем, что $update получен через Webhook или Long Polling
$update = json_decode(file_get_contents('php://input'), true);
if (!empty($update['message']['new_chat_members'])) {
foreach ($update['message']['new_chat_members'] as $newMember) {
// Проверяем, что добавленный участник — это наш бот
// Для этого можно сравнить username или ID бота, полученный ранее из getMe
if ($newMember['is_bot'] === true && $newMember['username'] === 'MyHelperBot') {
$chatId = $update['message']['chat']['id'];
$chatTitle = $update['message']['chat']['title'];
// Здесь должна быть запись в вашу БД:
// $db->saveChat($chatId, $chatTitle);
telegramApi('sendMessage', [
'chat_id' => $chatId,
'text' => "Привет, чат *" . htmlspecialchars($chatTitle) . "*! 👋\nЯ готов к работе. Сделайте меня администратором, чтобы я мог модерировать сообщения.",
'parse_mode' => 'Markdown'
]);
}
}
}Права администратора: что нужно для модерации
По умолчанию обычный участник группы (включая бота) не может влиять на других пользователей. Чтобы бот мог удалять спам, банить нарушителей или закреплять важные сообщения, владельцу группы необходимо назначить его администратором и выдать соответствующие права (permissions):
can_delete_messages— право удалять чужие сообщения (методdeleteMessage).can_restrict_members— право банить, разбанивать и ограничивать пользователей (методыbanChatMember,restrictChatMember).can_pin_messages— право закреплять сообщения (методpinChatMessage).
Перед выполнением любого действия модерации рекомендуется проверять, обладает ли бот нужными правами в конкретном чате. Для этого используется статус бота.
Используем функцию getBotStatusInChat(), которую мы сделали в главе
chat_id и user_id.
Здесь только вызываем её — реализацию не копируем.
<?php
$chatId = -1001987654321;
$botStatus = getBotStatusInChat($chatId);
if ($botStatus && $botStatus['status'] === 'administrator') {
if (!empty($botStatus['can_restrict_members'])) {
echo "Бот является администратором и может управлять пользователями.\n";
} else {
echo "Бот админ, но у него нет права restrict_members!\n";
}
} else {
echo "Бот не является администратором в этом чате.\n";
}При вызове метода getChatMember для администратора Telegram возвращает подробный объект с правами. Пример JSON-ответа API:
{
"ok": true,
"result": {
"user": {
"id": 123456789,
"is_bot": true,
"first_name": "MyHelperBot",
"username": "MyHelperBot"
},
"status": "administrator",
"can_be_edited": false,
"can_manage_chat": true,
"can_change_info": false,
"can_post_messages": false,
"can_edit_messages": false,
"can_delete_messages": true,
"can_invite_users": true,
"can_restrict_members": true,
"can_pin_messages": true,
"can_manage_topics": false
}
}Важное ограничение: Бот никогда не сможет применить санкции (бан, мут) к создателю группы (owner) или к администраторам, которые находятся выше него в иерархии. При попытке сделать это API вернет ошибку 400 Bad Request: CHAT_ADMIN_REQUIRED или can't restrict member. Всегда обрабатывайте такие ошибки в коде.
Бан, мут и разбан: практические примеры
Для управления ограничениями пользователей в Bot API используются три ключевых метода:
banChatMember— полностью удаляет пользователя из группы. Он не сможет вернуться самостоятельно, пока его не разбанят.restrictChatMember— накладывает частичные ограничения (запрет писать, отправлять медиа, ссылки).unbanChatMember— снимает бан или ограничения.
Используем функцию telegramApi(), которую мы сделали в главе
Первый запрос: getMe.
Здесь только вызываем её — реализацию не копируем.
<?php
$chatId = -1001987654321;
$userId = 987654321;
// 1. Полный бан пользователя на 7 дней (передаем Unix timestamp)
$banDuration = time() + (7 * 24 * 3600);
$banResult = telegramApi('banChatMember', [
'chat_id' => $chatId,
'user_id' => $userId,
'until_date' => $banDuration
]);
if ($banResult && $banResult['ok']) {
echo "Пользователь успешно забанен на неделю.\n";
} else {
echo "Ошибка бана: " . ($banResult['description'] ?? 'Неизвестная ошибка') . "\n";
}
// 2. Мут пользователя (restrict) — запрещаем отправлять любые сообщения на 1 час
$muteDuration = time() + 3600;
$muteResult = telegramApi('restrictChatMember', [
'chat_id' => $chatId,
'user_id' => $userId,
'permissions' => json_encode([
'can_send_messages' => false,
'can_send_media_messages' => false,
'can_send_other_messages' => false,
'can_add_web_page_previews' => false
]),
'until_date' => $muteDuration
]);
// 3. Разбан (unban) — возвращает пользователю возможность войти в группу
$unbanResult = telegramApi('unbanChatMember', [
'chat_id' => $chatId,
'user_id' => $userId,
'only_if_banned' => true // Снимет бан, но не сбросит активный мут, если пользователь внутри чата
]);Сценарий: Приветствие и «Карантин» для новичков
Популярный способ защиты от спам-ботов — перевод каждого нового участника в режим «только чтение» (read-only) до тех пор, пока он не нажмет кнопку верификации под приветственным сообщением.
Используем функцию telegramApi(), которую мы сделали в главе
Первый запрос: getMe.
Здесь только вызываем её — реализацию не копируем.
<?php
$update = json_decode(file_get_contents('php://input'), true);
// Шаг 1: Ловим нового пользователя и отправляем в мут
if (!empty($update['message']['new_chat_members'])) {
foreach ($update['message']['new_chat_members'] as $newMember) {
if ($newMember['is_bot']) continue; // Ботов не трогаем (или сразу баним)
$chatId = $update['message']['chat']['id'];
$userId = $newMember['id'];
$userName = htmlspecialchars($newMember['first_name']);
// Ограничиваем права (запрещаем писать)
telegramApi('restrictChatMember', [
'chat_id' => $chatId,
'user_id' => $userId,
'permissions' => json_encode([
'can_send_messages' => false
])
]);
// Отправляем приветствие с inline-кнопкой
telegramApi(&039;sendMessage', [
'chat_id' => $chatId,
'text' => "Добро пожаловать, {$userName}! 🛡️\nЧтобы получить возможность писать в чат, подтвердите, что вы не бот.",
'reply_markup' => json_encode([
'inline_keyboard' => [[
[
'text' => '✅ Я человек',
'callback_data' => "verify:{$userId}"
]
]]
])
]);
}
}
// Шаг 2: Обрабатываем нажатие на кнопку верификации
if (!empty($update['callback_query'])) {
$callbackQuery = $update['callback_query'];
$data = $callbackQuery['data'];
$clickerId = $callbackQuery['from']['id'];
$chatId = $callbackQuery['message']['chat']['id'];
$messageId = $callbackQuery['message']['message_id'];
if (str_starts_with($data, 'verify:')) {
$targetUserId = (int)str_replace('verify:', '', $data);
// Проверяем, что кнопку нажал именно тот пользователь, который вступил
if ($clickerId !== $targetUserId) {
telegramApi('answerCallbackQuery', [
'callback_query_id' => $callbackQuery['id'],
'text' => '❌ Эта кнопка предназначена не для вас!',
'show_alert' => true
]);
exit;
}
// Возвращаем пользователю стандартные права
telegramApi('restrictChatMember', [
'chat_id' => $chatId,
'user_id' => $targetUserId,
'permissions' => json_encode([
'can_send_messages' => true,
'can_send_media_messages' => true,
'can_send_other_messages' => true,
'can_add_web_page_previews' => true
])
]);
// Уведомляем об успешном прохождении
telegramApi('answerCallbackQuery', [
'callback_query_id' => $callbackQuery['id'],
'text' => 'Доступ разрешен! Приятного общения.'
]);
// Удаляем приветственное сообщение, чтобы не засорять чат
telegramApi('deleteMessage', [
'chat_id' => $chatId,
'message_id' => $messageId
]);
}
}Дальше: Каналы