API de grupos do WhatsApp: criar, gerenciar e automatizar grupos

Quando grupo por API faz sentido

Gerenciar um grupo no celular funciona até o dia em que são quarenta turmas, cada uma com alunos entrando e saindo toda semana. A partir daí, alguém passa a tarde adicionando número e removendo inadimplente, e erra. A API de grupos resolve esse trabalho braçal, e quem decide quem entra é a regra do seu sistema, não a memória de quem administra.

Os cenários mais comuns:

• Turmas e cursos: um grupo por turma, criado quando a turma abre, com alunos entrando ao confirmar matrícula e saindo quando o acesso termina. Plataformas de edtech usam muito esse modelo.
• Comunidades de clientes: grupos para assinantes de um plano, com entrada por pedido aprovado automaticamente quando a assinatura está ativa.
• Suporte VIP ou de implantação: um grupo por cliente com o time de atendimento, criado quando o contrato é assinado.
• Operação interna: grupos de equipe de campo ou lojas, com admins definidos pelo cargo no sistema de RH.

O que a API de grupos permite

Passo a passo: da turma nova ao grupo pronto

1. Crie o grupo já com as regras. Ao criar, defina se só admins enviam mensagens (admin_only_messages), se a entrada exige aprovação (admin_approval) e se só admins adicionam pessoas (admin_add_only).
2. Guarde o ID do grupo junto da turma no seu banco. Todas as operações seguintes usam ele.
3. Promova o professor ou o responsável a admin, para que alguém humano também possa moderar.
4. Distribua o link de convite no e-mail de boas-vindas ou na área do aluno.
5. Aprove os pedidos pelo webhook, conferindo a matrícula de cada número.

import { DApi } from 'd-api-sdk'

const dapi = new DApi({ apiKey: process.env.DAPI_KEY })

const { groupId } = await dapi.groups.create({
  sessionId: 'escola',
  name: 'Turma Python - Outubro',
  participants: ['5511999999999'],
  description: 'Avisos e dúvidas da turma',
  admin_only_messages: false,
  admin_approval: true,
})

// salve o groupId junto da turma antes de seguir
await dapi.groups.manageParticipants(groupId, {
  sessionId: 'escola',
  participants: ['5511999999999'],
  action: 'promote',
})

await dapi.groups.setSettings(groupId, {
  sessionId: 'escola',
  memberAddMode: 'admin',
})

Configurações e aprovação de entrada

Depois de criado, o grupo pode ser ajustado em /groups/{groupId}/settings:

• announce: só admins enviam mensagens. Bom para canais de aviso.
• locked: só admins editam nome, descrição e foto.
• joinApproval: quem entra pelo link precisa ser aprovado.
• memberAddMode: admin para só admins adicionarem, all para liberar.

A aprovação de entrada é o que torna o link de convite seguro. O link pode vazar, mas quem não está na sua base não passa. E se vazar demais, revogue o link e gere outro.

Eventos de grupo no webhook

Os movimentos do grupo chegam ao seu webhook em eventos próprios:

• groups_participants.join, .leave, .promote e .demote, com o grupo, os participantes afetados e quem fez a ação.
• group_participants.join-request quando alguém pede para entrar, além das variantes .approved e .revoked.

Use esses eventos como fonte da verdade. Se um admin humano remover alguém pelo celular, o leave chega e o seu sistema atualiza a matrícula, sem planilha paralela.

Como reforço, rode de tempos em tempos uma reconciliação: consulte o grupo com getInfo, compare os participantes com quem deveria estar lá e corrija as diferenças. Isso cobre eventos que o seu receptor não conseguiu processar e mudanças feitas enquanto a integração estava desligada. Para turmas temporárias, vale também criar o grupo com disappearing_messages ligado, de modo que o histórico não fique guardado além do necessário.

Cuidados para não virar spam

Grupo é o recurso do WhatsApp com maior potencial de denúncia. Adicionar alguém que não esperava, num grupo que manda promoção o dia todo, é o caminho mais curto para bloquear o número. Algumas regras:

• Prefira link de convite com aprovação a adicionar pessoas diretamente.
• Espaçe criação de grupos e adições em lote; não faça tudo no mesmo minuto.
• Deixe claro na descrição por que o grupo existe e como sair.
• Separe números: o que administra grupos não deveria ser o mesmo do atendimento principal.

Mais detalhes em como evitar banimento. Os grupos são um recurso da API de WhatsApp não oficial, conectada por QR Code; veja o que mais ela oferece na página da API não oficial de WhatsApp.