Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Enviar e receber

Grupos e canais de WhatsApp pela API

Criar grupos, adicionar e remover participantes, mudar nome, foto e travas, gerar link de convite e tratar pedidos de entrada pela API de WhatsApp.

6 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
A API cria e administra grupos com POST /groups e as rotas de /groups/{id}: participantes, nome, descrição, foto, travas, link de convite e pedidos de entrada. O número da instância precisa ser administrador. Os tetos são 10 grupos criados por dia, 50 participantes adicionados por dia e 20 entradas por link por dia.

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.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/groups" -H "apikey: SUA_CHAVE"
json
{ "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.

bash
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átis

Como 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/add
  • POST /groups/{id}/participants/remove
  • POST /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).

Com GET /groups/{id}/invite-link, GET /groups/preview, POST /groups/join e POST /groups/{id}/leave.

  • GET /groups/{id}/invite-link devolve 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/join com link faz o número entrar. Teto de 20 por dia.
  • POST /groups/{id}/leave sai 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 /channels lista os canais que a instância segue.
  • GET /channels/info mostra os dados de um canal (pelo newsletter_id, que termina em @newsletter, ou pelo código de convite em invite).
  • POST /channels/follow e POST /channels/unfollow seguem e deixam de seguir.
  • GET /channels/messages lê 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.

python
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

Í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.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp