TL;DR: Três endpoints do Whapi.Cloud cobrem o ciclo completo de solicitações de entrada em grupos: GET para listar solicitações pendentes, POST para aceitar uma e DELETE para rejeitar uma. Configure um webhook groups.put, filtre por action: "request" e encaminhe para aceitar ou rejeitar com base na sua regra. O handler Python Flask tem menos de 50 linhas. Para Make ou n8n, é um gatilho Webhook mais um módulo HTTP. Comece com um sandbox gratuito para testar cada chamada antes de fazer o deploy.
Por Que a Moderação Manual de Grupos Falha em Escala
Todo grupo fechado do WhatsApp eventualmente falha sob moderação manual. Com 20 solicitações de entrada por semana, a tarefa é uma interrupção rotineira; com 100, as solicitações se acumulam sem resposta e a integridade do grupo se deteriora.
Turmas de cursos online, comunidades beta de SaaS e canais de assinatura paga enfrentam o mesmo limite: um administrador que precisa abrir o aplicativo, ler cada solicitação e tocar em aprovar ou rejeitar. O trabalho não escala.
O Whapi.Cloud cobre o ciclo completo de moderação: detecta uma solicitação de entrada no instante em que chega, recupera a lista completa de solicitações pendentes sob demanda, aceita um solicitante específico e rejeita outros, tudo por meio de três endpoints REST. Este guia mostra exatamente como conectá-los, tanto para desenvolvedores Python quanto para equipes usando Make ou n8n.
A referência completa da API de Grupos e o guia de automação de grupos cobrem toda a superfície da API; este artigo se concentra especificamente na moderação de solicitações de entrada.
Pré-requisitos Antes de Começar
Antes de escrever qualquer código, confirme que você tem todos os quatro itens a seguir. A ausência de qualquer um fará as chamadas à API falharem silenciosamente ou retornarem um 403.
-
Conta Whapi.Cloud com número conectado: cadastre-se em panel.whapi.cloud/register, escaneie o QR code e copie seu token de canal do painel.
-
Papel de administrador do grupo: o número conectado precisa ser administrador do grupo-alvo. Contas sem papel de administrador recebem 403 em todos os endpoints de moderação.
-
Configuração de grupo fechado/privado: solicitações de entrada só existem quando o grupo está configurado como "Privado"; apenas administradores podem aprovar novos membros. Grupos abertos não têm fila de solicitações pendentes.
-
Python 3.8+ com
requestseFlask(para a trilha do desenvolvedor), ou uma conta ativa no Make ou n8n (para a trilha no-code).
Como Funcionam as Solicitações de Entrada em Grupos do WhatsApp
Quando um grupo do WhatsApp é configurado como privado, qualquer pessoa que tente entrar via link de convite entra em uma fila pendente em vez de entrar imediatamente. GET /groups/{GroupID}/applications expõe essa fila por meio da API.
Cada solicitante permanece na fila até ser explicitamente aceito ou rejeitado. Não há expiração automática. Para comunidades de alto volume, a fila pode chegar a centenas de entradas se não for gerenciada. A moderação automatizada é a única forma confiável de manter o ritmo.
Configurando o Gatilho Webhook para Solicitações de Entrada
Um webhook de solicitação de entrada dispara no instante em que alguém solicita entrar no seu grupo. Você não precisa fazer polling no endpoint da lista; o Whapi.Cloud envia o evento para sua URL em tempo real no momento em que o WhatsApp o entrega.
Para habilitar isso, vá às configurações do seu canal no Whapi.Cloud e ative o evento de webhook groups.put. Configure a URL do webhook para o endpoint do seu servidor (ou a URL de Webhook do Make/n8n). Uma vez habilitado, toda mudança de participação no grupo — entradas, saídas, promoções e solicitações de entrada — enviará um POST para essa URL.
O payload de uma solicitação de entrada tem este formato. Para descrições completas dos campos, consulte a referência do formato de webhooks recebidos:
{
"groups_participants": [
{
"group_id": "[email protected]",
"participants": [
"61371989850"
],
"action": "request"
}
],
"event": {
"type": "groups",
"event": "put"
},
"channel_id": "MANTIS-M72HC"
}O discriminador é o campo action. O mesmo webhook groups.put também dispara para entradas, saídas, promoções de administrador e remoções. Seu handler deve verificar action === "request" antes de chamar qualquer endpoint de moderação. Caso contrário, você tentará aprovar pessoas que já entraram.
Do payload, extraia dois valores: group_id (ex., [email protected]) e cada entrada em participants (o número de telefone ou identificador @lid do solicitante). Ambos são parâmetros obrigatórios para cada chamada à API de moderação.
Obtendo a Lista de Solicitações de Entrada Pendentes
O endpoint GET recupera a fila completa de pendentes sob demanda, independentemente de webhooks. Use-o para preencher aprovações na inicialização, auditar a fila atual ou exibir um painel de revisão.
| Parâmetro | Tipo | Obrigatório | Descrição |
GroupID |
string | Sim | ID completo do grupo incluindo o sufixo @g.us |
count |
number | Não | Número máximo de resultados a retornar |
offset |
number | Não | Deslocamento de resultados para paginação |
count e offset para paginar quando a fila ultrapassar 50 entradas pendentes; cada chamada retorna apenas tantos registros quanto count especifica.
A chamada Python abaixo lista as solicitações pendentes com seu token de canal no cabeçalho de autorização. Consulte a documentação de membros de grupos do Whapi.Cloud para descrições completas dos campos de resposta.
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)A resposta inclui o número de telefone ou identificador @lid de cada solicitante. Use count e offset para paginar filas com mais de 50 entradas.
Aceitando uma Solicitação de Entrada via API
POST /groups/{GroupID}/applications aceita exatamente um solicitante por chamada. Passe o número de telefone ou identificador @lid do payload do webhook como parâmetro application. Para aprovar múltiplos solicitantes, chame em um loop.
| Parâmetro | Localização | Obrigatório | Descrição |
GroupID |
path | Sim | ID completo do grupo (ex., [email protected]) |
application |
body (JSON) | Sim | Chat ID do solicitante (número de telefone ou @lid do payload do webhook) |
Authorization |
header | Sim | Bearer {channel_token} |
application aceita tanto um número de telefone quanto um identificador @lid; ambos são Chat IDs válidos para os endpoints de aceitar e rejeitar.
Trilha Python: Aceitando uma Solicitação
A função abaixo aceita um único solicitante. Chame-a para cada entrada no array participants do payload do webhook. Verifique o código de status da resposta: 200 significa sucesso, um 4xx significa que o ID do solicitante está incorreto ou você não tem direitos de administrador.
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 respTrilha No-Code: Aceitando no Make
No Make: o módulo Webhook dispara, o módulo HTTP chama o endpoint do Whapi.Cloud. Configure o módulo HTTP depois que seu gatilho Webhook filtrar o evento de solicitação de entrada. Consulte o guia de integração com Make.com para a configuração completa do cenário:
-
URL:
https://gate.whapi.cloud/groups/{{groups_participants[].group_id}}/applications -
Método: POST
-
Cabeçalhos: Adicione um cabeçalho com Nome
Authorization, ValorBearer {{your_channel_token}} -
Tipo de corpo: Raw, Tipo de conteúdo: JSON
-
Conteúdo do corpo:
{"application": "{{groups_participants[].participants[]}}"}
Trilha No-Code: Aceitando no n8n
No n8n: o nó Webhook captura o evento, o nó HTTP Request chama aceitar ou rejeitar. Após o nó Webhook e um nó IF que filtre por body.groups_participants[0].action === "request", configure o nó HTTP Request:
-
URL:
https://gate.whapi.cloud/groups/{{$json.body.groups_participants[0].group_id}}/applications -
Método: POST
-
Autenticação: Header Auth. Nome:
Authorization, Valor:Bearer {{your_channel_token}} -
Parâmetros do corpo: Enviar corpo como JSON. Chave:
application, Valor:{{$json.body.groups_participants[0].participants[0]}}
Rejeitando Solicitações de Entrada via API
O endpoint DELETE rejeita um solicitante por chamada, com os mesmos parâmetros do endpoint de aceitar. Troque o método HTTP para DELETE; todo o resto permanece idêntico. Para rejeições em massa, itere sobre a lista de participantes.
application no body; apenas o método HTTP muda de POST para DELETE.
Trilha Python: Rejeitando uma Solicitação
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 respTrilha No-Code: Rejeitando no Make
Mesma configuração do módulo HTTP que no fluxo de aceitar acima. Mude apenas um campo:
-
Método: DELETE (todos os outros campos — URL, cabeçalhos, corpo — permanecem iguais ao módulo de aceitar)
Trilha No-Code: Rejeitando no n8n
-
Método: DELETE (URL, autenticação e parâmetros do corpo permanecem idênticos ao nó de aceitar)
-
No n8n, conecte os ramos "true" (aprovar) e "false" (rejeitar) do seu nó IF a nós HTTP Request separados com os respectivos métodos.
Construindo o Fluxo Completo de Automação de Moderação
O handler Python completo é uma única rota Flask que filtra o webhook, aplica sua regra e chama POST ou DELETE. Cabe em menos de 50 linhas e cobre todos os três endpoints.
Substitua a função should_approve() pela sua própria lógica: verificar em uma lista de permissões, validar um domínio de e-mail, buscar o número de telefone no seu CRM ou consultar seu próprio banco de dados. O tutorial de bot Python para WhatsApp cobre padrões Flask adicionais se você quiser estender este handler.
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)Sobre tratamento de erros: uma resposta 403 significa que o número conectado não é administrador do grupo. Um 404 significa que o ID do grupo está incorreto ou o solicitante já saiu da fila. Registre ambos: eles identificam erros de configuração, não falhas transitórias.
Para a trilha no-code, o fluxo completo no Make ou n8n segue esta sequência:
-
Gatilho Webhook: o módulo Custom Webhook (Make) ou o nó Webhook (n8n) recebe o payload
groups.putdo Whapi.Cloud. -
Filtro: o Router (Make) ou o nó IF (n8n) verifica que
groups_participants[].actionseja igual arequest. Eventos que não correspondem são descartados. -
Decisão: adicione sua própria condição: busque o número do participante em uma lista de permissões no Google Sheets, verifique uma requisição HTTP a um banco de dados ou use um filtro de texto simples.
-
Módulo HTTP (caminho de aceitar): POST para
https://gate.whapi.cloud/groups/{group_id}/applicationscom{"application": "{participant}"}no corpo JSON. -
Módulo HTTP (caminho de rejeitar): mesma URL, mesmo corpo; o método muda para DELETE.
O Whapi.Cloud entrega um payload JSON limpo com um único campo discriminador. Make e n8n o mapeiam diretamente sem middleware ou transformador personalizado. A moderação automatizada elimina a fila de administração manual e aplica regras de acesso consistentes em todos os grupos administrados pelo número conectado.
Uma Nota sobre Identificadores @lid nas Solicitações de Entrada
Alguns solicitantes aparecem como identificadores @lid, como 1524746986546@lid, em vez de números de telefone, devido às mudanças de privacidade do WhatsApp em 2025. Passe valores @lid diretamente como parâmetro application; eles funcionam de forma idêntica a números de telefone nos endpoints de aceitar e rejeitar.
O Whapi.Cloud resolve automaticamente @lid para números de telefone quando o WhatsApp fornece o mapeamento. Quando a resolução não está disponível, o valor @lid é retornado como está e ainda pode ser passado diretamente como parâmetro application para o endpoint de aceitar ou rejeitar. Para uma explicação completa, consulte os artigos da base de conhecimento do Whapi.Cloud sobre o que é @lid em grupos do WhatsApp e o FAQ sobre @lid.
Resumo de Endpoints: O Ciclo Completo de Moderação
Três endpoints — GET para listar, POST para aceitar, DELETE para rejeitar — cobrem o ciclo completo de moderação. Aqui está a tabela de referência completa antes de partir para os testes:
| Operação | Método | Endpoint | Corpo obrigatório | Notas |
| Listar solicitações pendentes | GET | /groups/{GroupID}/applications |
Nenhum | Retorna a fila completa; suporta paginação |
| Aceitar uma solicitação | POST | /groups/{GroupID}/applications |
{"application": "phone_or_lid"} |
Um solicitante por chamada; use loop para múltiplos |
| Rejeitar uma solicitação | DELETE | /groups/{GroupID}/applications |
{"application": "phone_or_lid"} |
Um solicitante por chamada; use loop para múltiplos |
As três chamadas usam o mesmo cabeçalho de autorização: Bearer {channel_token}. A URL base é https://gate.whapi.cloud. Qualquer limitação de velocidade que você adicionar é por detecção de spam do lado do WhatsApp, não por restrições da API do Whapi.Cloud; planos de produção não têm limites rígidos de rate limit no nível da API.
Comece a Testar no Sandbox Gratuito
Inicie um sandbox gratuito do Whapi.Cloud para testar a API de solicitações de entrada sem pagamento. O sandbox é permanentemente gratuito: 5 conversas ativas por mês, sem limite de tempo. Escaneie um QR code, conecte um número e execute cada endpoint deste guia em um grupo real do WhatsApp antes de fazer o deploy em produção.
