Pular para o conteúdo
apiwpp
RecursoEm breve

Grupos do WhatsApp pela API (administração em breve no PRO)

Liste os grupos do número, receba mensagens e eventos de grupo no webhook. Criar grupos e gerenciar participantes pela API chega em breve no plano PRO.

Atualizado em

Grupos são parte do dia a dia de quem usa WhatsApp no trabalho: a turma de um curso, a comunidade de clientes de uma loja, a equipe de entregadores de uma região. Quem integra o WhatsApp a um sistema quer duas coisas desses grupos: acompanhar o que acontece neles e, em algum momento, administrá-los sem abrir o celular.

Na apiwpp, a primeira parte já funciona. A segunda, a administração de grupos pela API, está em desenvolvimento e vai fazer parte do plano PRO. Esta página separa com clareza o que você pode usar hoje e o que ainda está por vir.

O que já funciona hoje

Nos planos LITE e PRO, um número conectado à apiwpp já participa dos grupos como qualquer aparelho conectado:

curl "https://api.apiwpp.com/connections/$CONNECTION_ID/groups" \
  -H "Authorization: Bearer $API_KEY"
{
  "groups": [
    { "jid": "[email protected]", "subject": "Turma de sábado", "size": 18 }
  ]
}

A conexão precisa estar open para a listagem; em outro status, a resposta é 400.

Os eventos de grupo

Os três eventos de grupo chegam no mesmo envelope dos outros webhooks, com o groupId (o JID do grupo) em data:

EventoQuando chegaCampos em data
group.joinedO número entrou ou foi adicionado a um grupogroupId, e groupName e participantCount quando conhecidos
group.leftO número foi removido de um grupogroupId, reason
group.updatedUm grupo de que o número participa mudougroupId e, quando o nome mudou, o novo groupName

Quando a conexão abre, a apiwpp também pode enviar um group.joined para cada grupo em que o número já está. Isso ajuda o seu sistema a montar a lista inicial, mas trate o evento de forma idempotente pelo groupId: o mesmo grupo pode chegar mais de uma vez.

Hoje esses eventos falam da participação do próprio número. Entradas e saídas de outros participantes ainda não geram evento.

O que está previsto na administração de grupos

A administração de grupos está desenhada e entra no plano PRO quando for lançada. O que está previsto:

As rotas, os escopos e o formato dos eventos novos serão publicados na documentação no lançamento, e podem mudar até lá. Os eventos que você já recebe continuam iguais: o contrato de webhooks só ganha tipos novos, e o seu código deve ignorar os tipos que não conhece.

Cuidados de ritmo ao adicionar participantes

Adicionar pessoas a um grupo é uma das formas mais comuns de abuso no WhatsApp, e um dos motivos mais frequentes de denúncia. Um número que coloca dezenas de desconhecidos em grupos em poucos minutos tem boas chances de ser restringido.

Por isso, o desenho da apiwpp trata cada pessoa adicionada como um destinatário novo: ela entra no mesmo teto de 100 destinatários novos por 24 horas que vale para os envios, e as operações de grupo terão um limite de ritmo próprio por conexão. Na prática:

Nada disso garante que um número nunca seja restringido pelo WhatsApp, mas reduz bastante o risco.

Usos comuns

Os três já funcionam hoje com grupos criados no celular: o sistema lista os grupos, envia para o JID de cada um e recebe as mensagens. A administração pela API vai permitir criar e manter esses grupos sem passar pelo aparelho.

Plano PRO e teste grátis

A administração de grupos será um recurso do plano PRO. Hoje o PRO inclui editar e apagar mensagens enviadas, marcar como lidas, presença e o IP dedicado como adicional; os valores por número estão em preços. O teste grátis de 7 dias inclui os recursos do PRO (exceto IP dedicado), com 1 número e sem cartão.

Perguntas frequentes

Já consigo criar grupos pela API?

Ainda não. Criar grupos e gerenciar participantes estão em desenvolvimento para o plano PRO. Hoje a API lista os grupos de que o número participa, entrega as mensagens de grupo e avisa quando o número entra, sai ou quando um grupo muda.

Recebo as mensagens enviadas nos grupos?

Sim. O evento message.incoming chega para mensagens de conversas individuais e de grupos, nos planos LITE e PRO.

Consigo saber quando alguém entra ou sai de um grupo?

Hoje, só quando é o próprio número: group.joined e group.left. Um evento para as mudanças de qualquer participante está previsto junto com a administração de grupos.

Adicionar participantes vai contar nos limites do número?

Pelo desenho atual, sim. Cada pessoa adicionada conta como destinatário novo, dentro do mesmo teto diário dos envios, porque adicionar desconhecidos a grupos é um dos principais motivos de denúncia.

Todos: Recursos →

Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.

Cada número conectado tem uma fila que envia no ritmo de uma pessoa: limites por minuto, hora e dia, intervalo aleatório entre envios e um teto de destinatários novos por dia. Mensagens ilimitadas dentro desses limites.

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.