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:
- Listar os grupos do número.
GET /connections/{id}/groupspergunta ao WhatsApp em quais grupos o número está e devolve o identificador de cada um (o JID, que termina em@g.us), o nome e a quantidade de participantes. A chave precisa do escopoconnections:read. - Receber as mensagens dos grupos. O evento
message.incomingchega para mensagens de conversas individuais e de grupos, com texto, mídia ou localização. - Saber quando algo muda. Os eventos
group.joined,group.leftegroup.updatedavisam quando o número entra num grupo, é removido dele ou quando um grupo de que participa muda, por exemplo de nome. - Enviar para um grupo. O campo
todo envio aceita o JID de um grupo de que o número participa, e a mensagem entra na fila do número como qualquer outra.
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:
| Evento | Quando chega | Campos em data |
|---|---|---|
group.joined | O número entrou ou foi adicionado a um grupo | groupId, e groupName e participantCount quando conhecidos |
group.left | O número foi removido de um grupo | groupId, reason |
group.updated | Um grupo de que o número participa mudou | groupId 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:
- criar grupos e alterar nome, descrição, foto e configurações;
- adicionar, remover, promover e rebaixar participantes, incluindo administradores;
- gerar e revogar links de convite;
- sair de um grupo pela API;
- consultar os participantes de cada grupo e receber um evento quando eles mudam.
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:
- adicione quem pediu para entrar, como alunos matriculados ou clientes que aceitaram o convite;
- prefira o link de convite para grupos grandes: a pessoa entra por vontade própria;
- num número recém-conectado, lembre que o aquecimento de 14 dias reduz os limites nos primeiros dias.
Nada disso garante que um número nunca seja restringido pelo WhatsApp, mas reduz bastante o risco.
Usos comuns
- Turmas e cursos. Um grupo por turma, com os avisos de aula enviados pelo sistema da escola e as dúvidas dos alunos chegando no webhook.
- Comunidades de clientes. Uma loja ou um clube que mantém um grupo de clientes e quer registrar as mensagens no CRM.
- Equipes operacionais. Entregadores, técnicos de campo ou plantonistas recebendo alertas do sistema num grupo da equipe.
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.
Outros recursos
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.