Provado em aparelho real em 10/11/2026: listar grupos. Beta: pode mudar: criar, participantes, nome, descrição, foto, travas, link, pedidos de entrada e canais.
Esta página mostra o que a API faz com grupos, do mais comum (criar um grupo para um pedido) ao mais raro (aprovar pedidos de entrada). A base é https://proxybox.com.br/api/whatsapp/v1, a chave vai em apikey, e as regras de erro e de ritmo estão em erros e limites.
Como o grupo é identificado?
Por um id que termina em @g.us. Para enviar uma mensagem ao grupo, use esse id no campo to de qualquer rota de envio.
Cada grupo tem um id que termina em @g.us. Use o id exatamente como a lista de grupos devolve. Enviar mensagem para um grupo é igual a enviar para um telefone: o campo to recebe o id do grupo, em qualquer rota de envio.
Como vejo os grupos em que o número está?
Com GET /groups, que lista até 500 grupos.
curl "https://proxybox.com.br/api/whatsapp/v1/groups" -H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "groups": [ { "id": "[email protected]", "name": "Pedidos da semana", "size": 12, "owner": "5547999999999", "announce": false, "locked": false } ] } }
A lista traz até 500 grupos. Para os detalhes de um deles, inclusive quem são os participantes e quem é administrador, use GET /groups/{id}.
Como crio um grupo?
Com POST /groups, um title de até 25 caracteres e a lista de participants, com ao menos 1 telefone.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"title":"Pedido 4512","participants":["5547999999999","5511988887777"]}'
O title aceita até 25 caracteres e participants precisa ter ao menos 1 telefone (sem participante a API recusa com 422 invalid_request). A resposta traz o id do novo grupo em data.id. Criar grupo é uma ação de administração: o teto é de 10 grupos por dia por instância.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisComo adiciono, removo e promovo participantes?
Com POST /groups/{id}/participants/add, remove, promote e demote, até 50 telefones por chamada.
Quatro rotas, o mesmo corpo (participants, lista de até 50 telefones):
POST /groups/{id}/participants/addPOST /groups/{id}/participants/removePOST /groups/{id}/participants/promote(vira administrador)POST /groups/{id}/participants/demote(deixa de ser administrador)
A resposta diz, pessoa por pessoa, se deu certo: {"ok":true,"data":{"results":[{"participant":"5511988887777","ok":false,"message":"…"}]}}. Uma pessoa recusada não derruba as outras. Adicionar tem teto de 50 participantes por dia. Adicione só quem pediu para entrar: quem é colocado num grupo sem aviso pode denunciar, e denúncia pesa contra o número.
Como mudo nome, descrição, foto e regras?
Com as rotas PUT /groups/{id}/name, topic, photo, locked e announce.
| Rota | Corpo | O que muda |
|---|---|---|
PUT /groups/{id}/name |
name (até 25 caracteres) |
Nome do grupo |
PUT /groups/{id}/topic |
topic (até 512 caracteres; vazio apaga) |
Descrição |
PUT /groups/{id}/photo |
media (imagem JPEG ou PNG). Vazio remove a foto |
Foto do grupo |
PUT /groups/{id}/locked |
value (true ou false) |
Só administradores mudam nome, foto e descrição |
PUT /groups/{id}/announce |
value |
Só administradores enviam mensagens |
O media da foto segue as regras de enviar mídia (url ou base64).
Como uso o link de convite, entro e saio de grupos?
Com GET /groups/{id}/invite-link, GET /groups/preview, POST /groups/join e POST /groups/{id}/leave.
GET /groups/{id}/invite-linkdevolve o link. Com?reset=true, o link antigo deixa de valer e nasce um novo.GET /groups/preview?link=…mostra nome, descrição e tamanho de um grupo antes de entrar.POST /groups/joincomlinkfaz o número entrar. Teto de 20 por dia.POST /groups/{id}/leavesai do grupo.
Como aprovo pedidos de entrada?
Com GET /groups/{id}/requests para listar e POST /groups/{id}/requests/approve ou reject para decidir.
Em grupos com aprovação, GET /groups/{id}/requests lista quem pediu para entrar, e POST /groups/{id}/requests/approve ou /reject (com participants) decide. É um bom caminho para quem recebe o link num formulário e quer conferir antes.
Quais são os limites dos grupos?
Criar: 10 por dia. Adicionar participantes: 50 por dia. Entrar por link: 20 por dia. Demais ações de administração: 60 por hora.
| Ação | Teto por instância |
|---|---|
| Criar grupo | 10 por dia |
| Adicionar participantes | 50 por dia |
| Entrar por link | 20 por dia |
| Demais ações de administração | 60 por hora |
| Listar e consultar | 120 por minuto |
Passou do teto, a API responde 429 com retry_after. Se o número não for administrador, responde 403. Se o grupo não existir, 404. Os tetos existem porque criar grupos e puxar gente para dentro em ritmo alto é comportamento que o WhatsApp olha com atenção, e não para atrapalhar uso normal.
Como recebo mensagens de grupo?
Pelos avisos group.message.received, group.message.sent e group.updated.
Os avisos automáticos trazem eventos próprios: group.message.received, group.message.sent e group.updated (entrou, saiu, foi promovido, mudou o nome). Em mensagens de grupo, o aviso traz group com id e name, e o campo from é o participante que escreveu. Detalhes em aviso automático.
O que a API faz com canais?
Consulta, segue e deixa de seguir canais e lê as mensagens deles. Não publica em canal.
Os canais (o recurso de transmissão do WhatsApp) têm cinco rotas, todas de consulta ou de seguir:
GET /channelslista os canais que a instância segue.GET /channels/infomostra os dados de um canal (pelonewsletter_id, que termina em@newsletter, ou pelo código de convite eminvite).POST /channels/followePOST /channels/unfollowseguem e deixam de seguir.GET /channels/messageslê as últimas mensagens de um canal.
Publicar em canal não faz parte da API.
Qual é um exemplo em Python?
Criar um grupo e mandar a primeira mensagem para ele.
import os, requests
base = "https://proxybox.com.br/api/whatsapp/v1"
h = {"apikey": os.environ["WA_KEY"]}
novo = requests.post(f"{base}/groups", headers=h,
json={"title": "Pedido 4512", "participants": ["5547999999999"]}, timeout=30).json()
grupo = novo["data"]["id"]
requests.post(f"{base}/messages/text", headers=h,
json={"to": grupo, "text": "Grupo criado. Aqui vão as novidades do seu pedido."}, timeout=30)
Veja também
- Verificar número com WhatsApp pela API
- Webhook da API de WhatsApp: eventos e assinatura
- Ler conversas e baixar mídia no WhatsApp via API
- Erros e limites da API de WhatsApp
Índice completo: todos os guias. Sobre o produto: planos e recursos da API de WhatsApp.
Autoria: equipe técnica da ProxyBox. Revisado em 11/11/2026 contra a versão 1.1 da API.