TL;DR: Три endpoint'а Whapi.Cloud покрывают полный цикл обработки заявок на вступление в группы: GET для получения списка ожидающих заявок, POST для принятия одной заявки и DELETE для её отклонения. Настройте вебхук groups.put, фильтруйте по action: "request" и направляйте запросы к принятию или отклонению в соответствии с вашим правилом. Обработчик Python Flask занимает менее 50 строк. Для Make или n8n — это триггер Webhook плюс один HTTP-модуль. Начните с бесплатного sandbox для тестирования каждого вызова перед развёртыванием.
Почему Ручная Модерация Групп Не Работает при Масштабировании
Любая закрытая группа WhatsApp рано или поздно даёт сбой при ручной модерации. При 20 заявках в неделю задача становится рутинным прерыванием; при 100 — заявки накапливаются без ответа, и целостность группы разрушается.
Учебные когорты онлайн-курсов, beta-сообщества SaaS и платные членские каналы сталкиваются с одним и тем же ограничением: администратор должен открыть приложение, прочитать каждую заявку и нажать «принять» или «отклонить». Такой подход не масштабируется.
Whapi.Cloud охватывает полный цикл модерации: обнаруживает заявку на вступление в момент её поступления, по запросу возвращает полный список ожидающих заявок, принимает конкретного заявителя и отклоняет других — всё через три REST endpoint'а. Это руководство показывает, как именно их связать, как для разработчиков на Python, так и для команд, использующих Make или n8n.
Полная справка по API Групп и руководство по автоматизации групп охватывают всю поверхность API; эта статья сосредоточена именно на модерации заявок на вступление.
Необходимые Условия Перед Началом
Перед написанием кода убедитесь, что у вас есть все четыре компонента из списка ниже. Отсутствие любого из них приведёт к тому, что вызовы API будут молча завершаться ошибкой или возвращать 403.
-
Аккаунт Whapi.Cloud с подключённым номером: зарегистрируйтесь на panel.whapi.cloud/register, отсканируйте QR-код и скопируйте токен канала из панели управления.
-
Роль администратора группы: подключённый номер должен быть администратором целевой группы. Аккаунты без роли администратора получают 403 на всех endpoint'ах модерации.
-
Закрытая/приватная группа: заявки на вступление существуют только когда группа настроена как «Приватная»; только администраторы могут одобрять новых участников. В открытых группах нет очереди ожидающих заявок.
-
Python 3.8+ с
requestsиFlask(для пути разработчика) или активный аккаунт Make или n8n (для пути с low-code).
Как Работают Заявки на Вступление в Группы WhatsApp
Когда группа WhatsApp настроена как приватная, любой, кто пытается вступить по ссылке-приглашению, попадает в очередь ожидания вместо немедленного вступления. GET /groups/{GroupID}/applications предоставляет эту очередь через API.
Каждый заявитель остаётся в очереди до явного принятия или отклонения. Автоматического истечения срока нет. Для сообществ с высоким трафиком очередь может достигать сотен записей, если не управлять ею. Автоматическая модерация — единственный надёжный способ справляться с нагрузкой.
Настройка Вебхук-триггера для Заявок на Вступление
Вебхук заявки на вступление срабатывает в тот момент, когда кто-то запрашивает вход в вашу группу. Нет необходимости опрашивать endpoint списка — Whapi.Cloud отправляет событие на ваш URL в реальном времени сразу после того, как WhatsApp его доставляет.
Для включения зайдите в настройки канала Whapi.Cloud и активируйте вебхук-событие groups.put. Укажите URL вебхука — endpoint вашего сервера (или URL Webhook в Make/n8n). После включения каждое изменение участников группы — вступления, выходы, повышения и заявки на вступление — будет отправлять POST на этот URL.
Payload заявки на вступление выглядит так. Полные описания полей см. в справке по формату входящих вебхуков:
{
"groups_participants": [
{
"group_id": "[email protected]",
"participants": [
"61371989850"
],
"action": "request"
}
],
"event": {
"type": "groups",
"event": "put"
},
"channel_id": "MANTIS-M72HC"
}Дискриминатором служит поле action. Тот же вебхук groups.put срабатывает также при вступлениях, выходах, повышениях администраторов и удалениях. Ваш обработчик должен проверять action === "request" перед вызовом любого endpoint'а модерации — иначе вы попытаетесь одобрить тех, кто уже вступил.
Из payload извлеките два значения: group_id (например, [email protected]) и каждый элемент в participants (номер телефона или идентификатор @lid заявителя). Оба являются обязательными параметрами для каждого вызова API модерации.
Получение Списка Ожидающих Заявок на Вступление
GET endpoint возвращает полную очередь ожидающих по запросу, независимо от вебхуков. Используйте его для восполнения одобрений при запуске, аудита текущей очереди или отображения панели проверки.
| Параметр | Тип | Обязателен | Описание |
GroupID |
string | Да | Полный ID группы включая суффикс @g.us |
count |
number | Нет | Максимальное количество возвращаемых результатов |
offset |
number | Нет | Смещение результатов для пагинации |
count и offset для пагинации, когда очередь превышает 50 ожидающих записей; каждый вызов возвращает ровно столько записей, сколько указано в count.
Приведённый ниже вызов Python выводит список ожидающих заявок с токеном канала в заголовке авторизации. Полные описания полей ответа см. в документации Whapi.Cloud по участникам групп.
import requests
WHAPI_TOKEN = "your_channel_token_here"
WHAPI_BASE = "https://gate.whapi.cloud"
def get_pending_applications(group_id):
"""Lists pending join requests for a group. Inputs: group_id (str). Returns: list of applicants."""
url = f"{WHAPI_BASE}/groups/{group_id}/applications"
headers = {"Authorization": f"Bearer {WHAPI_TOKEN}"}
resp = requests.get(url, headers=headers)
resp.raise_for_status()
return resp.json()
# Example usage
pending = get_pending_applications("[email protected]")
print(pending)Ответ включает номер телефона или идентификатор @lid каждого заявителя. Используйте count и offset для постраничного просмотра очередей с более чем 50 записями.
Принятие Заявки на Вступление через API
POST /groups/{GroupID}/applications принимает ровно одного заявителя за вызов. Передайте номер телефона или идентификатор @lid из payload вебхука как параметр application. Для одобрения нескольких заявителей вызывайте endpoint в цикле.
| Параметр | Расположение | Обязателен | Описание |
GroupID |
path | Да | Полный ID группы (например, [email protected]) |
application |
body (JSON) | Да | Chat ID заявителя (номер телефона или @lid из payload вебхука) |
Authorization |
header | Да | Bearer {channel_token} |
application принимает как номер телефона, так и идентификатор @lid — оба являются действительными Chat ID для endpoint'ов принятия и отклонения.
Путь Python: Принятие Заявки
Функция ниже принимает одного заявителя. Вызывайте её для каждой записи в массиве participants из payload вебхука. Проверяйте код статуса ответа: 200 означает успех, 4xx — что ID заявителя неверный или у вас нет прав администратора.
def approve_application(group_id, participant):
"""Accepts one join request. Inputs: group_id (str), participant phone (str). Returns: response."""
url = f"{WHAPI_BASE}/groups/{group_id}/applications"
headers = {"Authorization": f"Bearer {WHAPI_TOKEN}"}
body = {"application": participant}
resp = requests.post(url, json=body, headers=headers)
if resp.status_code not in (200, 201):
print(f"Approve failed [{resp.status_code}]: {resp.text}")
return respПуть Low-Code: Принятие в Make
В Make: модуль Webhook срабатывает, HTTP-модуль вызывает endpoint Whapi.Cloud. Настройте HTTP-модуль после того, как ваш триггер Webhook отфильтрует событие заявки на вступление. Полная настройка сценария описана в руководстве по интеграции с Make.com:
-
URL:
https://gate.whapi.cloud/groups/{{groups_participants[].group_id}}/applications -
Метод: POST
-
Заголовки: Добавьте заголовок с именем
Authorization, значениемBearer {{your_channel_token}} -
Тип тела: Raw, Content type: JSON
-
Содержимое тела:
{"application": "{{groups_participants[].participants[]}}"}
Путь Low-Code: Принятие в n8n
В n8n: нод Webhook перехватывает событие, нод HTTP Request вызывает принятие или отклонение. После нода Webhook и нода IF, фильтрующего по body.groups_participants[0].action === "request", настройте нод HTTP Request:
-
URL:
https://gate.whapi.cloud/groups/{{$json.body.groups_participants[0].group_id}}/applications -
Метод: POST
-
Аутентификация: Header Auth. Имя:
Authorization, Значение:Bearer {{your_channel_token}} -
Параметры тела: Send Body as JSON. Ключ:
application, Значение:{{$json.body.groups_participants[0].participants[0]}}
Отклонение Заявок на Вступление через API
DELETE endpoint отклоняет одного заявителя за вызов с теми же параметрами, что и endpoint принятия. Достаточно сменить HTTP-метод на DELETE — всё остальное идентично. Для массового отклонения — итерируйте по списку участников.
application в теле; меняется только HTTP-метод с POST на DELETE.
Путь Python: Отклонение Заявки
def reject_application(group_id, participant):
"""Rejects one join request. Inputs: group_id (str), participant phone (str). Returns: response."""
url = f"{WHAPI_BASE}/groups/{group_id}/applications"
headers = {"Authorization": f"Bearer {WHAPI_TOKEN}"}
body = {"application": participant}
resp = requests.delete(url, json=body, headers=headers)
if resp.status_code not in (200, 201):
print(f"Reject failed [{resp.status_code}]: {resp.text}")
return respПуть Low-Code: Отклонение в Make
Конфигурация HTTP-модуля та же, что и в потоке принятия выше. Измените только одно поле:
-
Метод: DELETE (все остальные поля — URL, заголовки, тело — остаются такими же, как в модуле принятия)
Путь Low-Code: Отклонение в n8n
-
Метод: DELETE (URL, аутентификация и параметры тела остаются идентичными ноду принятия)
-
В n8n подключите ветки «true» (одобрить) и «false» (отклонить) вашего нода IF к отдельным нодам HTTP Request с соответствующими методами.
Создание Полного Потока Автоматизации Модерации
Полный обработчик Python — это единственный Flask-маршрут, который фильтрует вебхук, применяет ваше правило и вызывает POST или DELETE. Умещается в менее чем 50 строк и охватывает все три endpoint'а.
Замените функцию should_approve() собственной логикой: проверкой по списку разрешённых, валидацией домена email, поиском номера телефона в вашей CRM или запросом к собственной базе данных. В туториале по Python-боту для WhatsApp разобраны дополнительные паттерны Flask, если хотите расширить этот обработчик.
import requests
from flask import Flask, request, jsonify
app = Flask(__name__)
WHAPI_TOKEN = "your_channel_token_here"
WHAPI_BASE = "https://gate.whapi.cloud"
def get_pending_applications(group_id):
"""Lists pending join requests. Inputs: group_id (str). Returns: API response JSON."""
url = f"{WHAPI_BASE}/groups/{group_id}/applications"
headers = {"Authorization": f"Bearer {WHAPI_TOKEN}"}
resp = requests.get(url, headers=headers)
resp.raise_for_status()
return resp.json()
def approve_application(group_id, participant):
"""Accepts one join request. Inputs: group_id (str), participant phone (str). Returns: response."""
url = f"{WHAPI_BASE}/groups/{group_id}/applications"
headers = {"Authorization": f"Bearer {WHAPI_TOKEN}"}
resp = requests.post(url, json={"application": participant}, headers=headers)
if resp.status_code not in (200, 201):
print(f"Approve failed [{resp.status_code}]: {resp.text}")
return resp
def reject_application(group_id, participant):
"""Rejects one join request. Inputs: group_id (str), participant phone (str). Returns: response."""
url = f"{WHAPI_BASE}/groups/{group_id}/applications"
headers = {"Authorization": f"Bearer {WHAPI_TOKEN}"}
resp = requests.delete(url, json={"application": participant}, headers=headers)
if resp.status_code not in (200, 201):
print(f"Reject failed [{resp.status_code}]: {resp.text}")
return resp
def should_approve(phone_number):
"""
Your custom approval rule. Return True to accept, False to reject.
Replace this with your own logic: allowlist check, CRM lookup, domain validation, etc.
"""
# Example: approve any number (replace with real condition)
return True
@app.route("/webhook", methods=["POST"])
def handle_webhook():
"""Receives Whapi.Cloud webhook events and routes join requests to approve or reject."""
data = request.get_json(force=True)
for group_event in data.get("groups_participants", []):
# Only process join request events — skip joins, leaves, and promotions
if group_event.get("action") != "request":
continue
group_id = group_event["group_id"]
for participant in group_event.get("participants", []):
if should_approve(participant):
approve_application(group_id, participant)
else:
reject_application(group_id, participant)
return jsonify({"status": "ok"})
if __name__ == "__main__":
app.run(port=5000)Об обработке ошибок: ответ 403 означает, что подключённый номер не является администратором группы. 404 — что ID группы неверный или заявитель уже покинул очередь. Логируйте оба: они указывают на ошибки конфигурации, а не на временные сбои.
Для пути low-code полный поток в Make или n8n следует такой последовательности:
-
Webhook-триггер: модуль Custom Webhook (Make) или нод Webhook (n8n) получает payload
groups.putот Whapi.Cloud. -
Фильтр: Router (Make) или нод IF (n8n) проверяет, что
groups_participants[].actionравноrequest. Несовпадающие события отбрасываются. -
Решение: добавьте собственное условие — найдите номер участника в списке разрешённых в Google Sheets, выполните HTTP-запрос к базе данных или используйте простой текстовый фильтр.
-
HTTP-модуль (путь принятия): POST на
https://gate.whapi.cloud/groups/{group_id}/applicationsс{"application": "{participant}"}в JSON-теле. -
HTTP-модуль (путь отклонения): тот же URL, то же тело; метод меняется на DELETE.
Whapi.Cloud доставляет чистый JSON payload с единственным полем-дискриминатором. Make и n8n маппируют его напрямую без промежуточного ПО или пользовательского трансформера. Автоматическая модерация устраняет ручную очередь администрирования и применяет единообразные правила доступа ко всем группам, которыми управляет подключённый номер.
Замечание об Идентификаторах @lid в Заявках на Вступление
Некоторые заявители появляются как идентификаторы @lid, например 1524746986546@lid, а не как номера телефонов — из-за изменений приватности WhatsApp в 2025 году. Передавайте значения @lid напрямую как параметр application; они работают идентично номерам телефонов в endpoint'ах принятия и отклонения.
Whapi.Cloud автоматически преобразует @lid в номера телефонов, когда WhatsApp предоставляет маппинг. Если преобразование недоступно, значение @lid возвращается как есть и всё равно может быть передано напрямую в endpoint принятия или отклонения в качестве параметра application. Подробное объяснение см. в статьях базы знаний Whapi.Cloud о том, что такое @lid в группах WhatsApp, и в FAQ по @lid.
Сводка Endpoint'ов: Полный Цикл Модерации
Три endpoint'а — GET для списка, POST для принятия, DELETE для отклонения — покрывают полный цикл модерации. Вот полная справочная таблица перед переходом к тестированию:
| Операция | Метод | Endpoint | Обязательное тело | Примечания |
| Список ожидающих заявок | GET | /groups/{GroupID}/applications |
Нет | Возвращает полную очередь; поддерживает пагинацию |
| Принять одну заявку | POST | /groups/{GroupID}/applications |
{"application": "phone_or_lid"} |
Один заявитель за вызов; для нескольких — цикл |
| Отклонить одну заявку | DELETE | /groups/{GroupID}/applications |
{"application": "phone_or_lid"} |
Один заявитель за вызов; для нескольких — цикл |
Все три вызова используют одинаковый заголовок авторизации: Bearer {channel_token}. Базовый URL: https://gate.whapi.cloud. Любые ограничения по частоте запросов, которые вы добавляете, связаны с защитой от спама на стороне WhatsApp, а не с ограничениями API Whapi.Cloud; продакшн-планы не имеют жёстких rate limit'ов на уровне API.
Начните Тестирование в Бесплатном Sandbox
Запустите бесплатный sandbox Whapi.Cloud, чтобы протестировать API заявок на вступление без оплаты. Sandbox бесплатен постоянно: 5 активных диалогов в месяц, без ограничений по времени. Отсканируйте QR-код, подключите номер и проверьте каждый endpoint этого руководства на реальной группе WhatsApp перед развёртыванием в продакшн.
