Руководство August 24, 2026

Заявки на вступление в группу Telegram: надежная очередь модерации

Надежная очередь модерации группы Telegram не должна зависеть только от push-событий. Периодически запрашивайте список ожидающих заявок, используйте id каждой записи как идентификатор участника для модерации и явно отправляйте действие approve или reject. Webhook group.join_request помогает быстрее обновить очередь, но доставляется в режиме best effort. Источником актуального состояния остается запрос списка.

Главное

Официальный Telegram Bot API передает обновления chat_join_request, если бот является администратором и имеет право can_invite_users.
В UnifyPort сначала включите модерацию с group_id и enabled: true, затем запрашивайте очередь с тем же group_id.
При подтверждении или отклонении передавайте id записей из списка в массиве member_ids.
Используйте group.join_request как быстрый сигнал, но всегда сверяйтесь со списком ожидающих заявок.
Сохраняйте ручное решение, если правила приема не являются узкими, однозначными и проверяемыми.

Сначала выберите модель идентификации

Если группе подходит управление от имени бота, в официальном Telegram Bot API уже есть ChatJoinRequest, approveChatJoinRequest и declineChatJoinRequest. Бот должен быть администратором группы с правом can_invite_users. Это прямой вариант для Telegram-группы, которую изначально планируется модерировать ботом.

Если модерация должна выполняться от имени существующего аккаунта Telegram или команде нужен единый подход к интеграции с другими каналами, можно использовать подключенный messaging account UnifyPort. Перед выбором сравните Telegram API ID и API Hash с Bot Token.

Не смешивайте эти модели. Bot Token представляет бота. API ID и API Hash идентифицируют клиентское приложение Telegram. Messaging account UnifyPort представляет подключенный аккаунт, от имени которого API выполняет действия.

Создаем очередь заявок на вступление в Telegram

1. Включите режим подтверждения

Чтобы появилась очередь, новые участники должны вступать только после подтверждения. Передайте идентификатор подключенного аккаунта, целевой group_id и логическое значение enabled:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-approval-mode" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "enabled": true
  }'

Для операции нужны права администратора группы. Отделите эту административную настройку от периодического worker-процесса модерации: worker не должен менять политику группы при каждом запуске. Актуальный контракт приведен в документации Set group join approval mode.

2. Регулярно запрашивайте список как источник истины

Передайте group_id в query-параметре:

curl \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests?group_id=group_example" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Храните локально только необходимые данные: ID заявки, группу, состояние решения, модератора и локальное время. Не предполагайте, что соответствующий webhook обязательно придет до появления записи в ответе API.

Связь полей проста: каждая запись из списка заявок на вступление содержит id. Именно его нужно передать в member_ids при обновлении. Не подставляйте отображаемое имя и не пытайтесь угадать идентификатор Telegram.

3. Сделайте решение явным

Полезно завести не менее четырех локальных состояний:

Состояние	Значение	Следующее действие
`pending`	Заявка есть в исходной системе и не рассмотрена	Показать модератору
`approved`	Модератор одобрил	Отправить `approve`
`rejected`	Модератор отказал	Отправить `reject`
`stale`	При сверке заявка исчезла	Закрыть без повторного действия

Анкета во внешней системе, список разрешенных пользователей или ручная проверка могут быть частью ваших правил. Явно обозначьте их как логику приложения, а не поля Telegram или UnifyPort. Не принимайте пользователя автоматически только по непроверенному имени или описанию профиля.

4. Подтверждайте или отклоняйте заявки пакетно

Передайте один или несколько ID из списка вместе с группой и явным действием:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests/update" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "action": "approve",
    "member_ids": ["member_example", "member_other"]
  }'

Для отказа используйте ту же структуру с "action": "reject". Маршрут требует прав администратора группы. Перед проектированием повторов и размера пакета изучите документацию Approve or reject join requests.

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

5. Пусть `group.join_request` будит worker, а не заменяет сверку

Чтобы интерфейс модерации обновлялся быстро, подпишите webhook endpoint на group.join_request. Событие сообщает о заявке в группу с включенным подтверждением, но его доставка выполняется в режиме best effort. Безопасная последовательность выглядит так:

принять событие;
проверить webhook и вернуть подтверждение;
поставить обновление очереди в задачу;
вызвать endpoint списка;
показать решения на основе возвращенного списка.

Push уменьшает задержку, а сверка восстанавливает достоверное состояние. Для принимающей стороны используйте также руководство HMAC-защита webhook от повторного воспроизведения и повторы доставки.

Не смешивайте заявку и изменение состава группы

Заявка еще не означает, что пользователь стал участником. При получении group.join_request не отмечайте человека как члена группы. Сначала подтвердите заявку, выполните сверку, а последующее изменение состава обработайте по отдельному пути событий.

В журнале аудита «запросил вступление», «модератор одобрил» и «добавлен в группу» — три разных факта. Обработку после подтверждения дополняет руководство по событиям добавления и удаления в Telegram Communities.

Контрольный список для production

Проверьте, что подключенная идентичность имеет права администратора группы.
Храните X-Api-Key только как серверный секрет.
Включайте режим подтверждения отдельной административной операцией.
Периодически запрашивайте очередь даже без webhook.
Используйте в member_ids только id, возвращенные списком.
Записывайте модератора и причину решения в собственный журнал аудита.
После каждого подтверждения или отказа снова запрашивайте список.
Проверяйте подпись webhook до использования события как сигнала обновления.
Не считайте событие заявки доказательством изменения состава группы.

Ограничения и компромиссы

Выбирайте официальный Bot API, если администратор-бот является нужной идентичностью, а процесс ограничен Telegram. Это прямой, официально документированный путь с отдельными методами подтверждения и отказа.

Unofficial interface UnifyPort подходит, когда важнее действовать от имени существующего аккаунта или использовать общий API-подход для нескольких каналов. Права администратора, понятная политика модерации, безопасное хранение API Key и сверка все равно обязательны. Интерфейс не решает, кому должна доверять ваша группа, а доставка событий best effort требует сохранить периодический опрос.

Частые вопросы

Может ли Telegram-бот подтверждать заявки на вступление?

Да. Официальный Bot API предоставляет методы подтверждения и отказа. Бот должен быть администратором группы с правом can_invite_users.

Достаточно ли обрабатывать только webhook `group.join_request`?

Нет. Используйте его как быстрое уведомление, а затем получайте список ожидающих заявок. В документации UnifyPort указано, что push-сигнал является best effort, а надежным источником служит опрос списка.

Какое значение передавать в `member_ids`?

Используйте id каждой записи, возвращенной endpoint списка. Не выводите его из отображаемого имени.

Можно ли подтвердить несколько заявок одним вызовом?

Да. Endpoint обновления принимает одно или несколько значений member_ids и action со значением approve или reject.

Что делать после подтверждения?

Снова запросите список, обновите локальную очередь и обрабатывайте дальнейшие изменения состава отдельно от исходной заявки.

Следующий шаг

Начните с API Reference списка заявок на вступление, затем добавьте вокруг цикла сверки настройку режима подтверждения и endpoint обновления.

Источники

Проверено 24 августа 2026 года:

UnifyPort API

Превратите интеграцию сообщений в стабильный продуктовый pipeline.

Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.

Получить API Key Открыть справочник API