grupos e comunidades
API WhatsApp grupos para o seu SaaS criar, organizar e moderar grupos
Com a API WhatsApp grupos da D-API, o seu SaaS cria grupos e comunidades já configurados, adiciona e remove participantes, controla convites e pedidos de entrada e recebe um webhook a cada movimentação.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Grupo pronto na criação
Nome, participantes, descrição, foto, só admins escrevendo, aprovação para entrar e mensagens temporárias, tudo numa chamada.
Participantes em lote
Adicione, remova, promova ou rebaixe vários participantes de uma vez, com o resultado de cada número na resposta.
Comunidades com grupo de avisos
Crie uma comunidade, grupos dentro dela e vincule grupos existentes, como uma escola organiza turmas sob uma mesma marca.
Movimentação em tempo real
Eventos de entrada, saída, promoção e pedidos de entrada chegam no webhook com o JID do grupo e de quem fez a ação.
A API WhatsApp grupos serve aos SaaS em que o grupo faz parte do produto. A edtech que abre um grupo por turma e coloca os alunos matriculados. O software de academia que mantém o grupo dos alunos do horário das 7h. A plataforma de eventos que cria um grupo por inscrição e remove quem cancelou. Sem API, alguém faz isso à mão, um número por vez. Com a D-API, o grupo nasce configurado a partir de um evento do seu sistema e se mantém em sincronia com o cadastro.
Os grupos são recurso da API não oficial, e todas as rotas recebem o sessionId do número que vai administrar o grupo.
Criar grupo pela API com as regras já definidas
POST /api/v1/groups/create recebe nome, participantes e as configurações que normalmente o administrador ajusta depois, no celular.
curl -X POST https://api.d-api.cloud/api/v1/groups/create \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "escola-idiomas-secretaria",
"name": "Inglês B1 - Terça e Quinta 19h",
"participants": ["5511999999999", "5511988887777"],
"description": "Avisos da turma, material e links das aulas.",
"admin_only_messages": true,
"admin_approval": true,
"disappearing_messages": "90d"
}'
As opções cobrem os ajustes mais comuns. admin_only_messages deixa só os administradores escreverem, ideal para grupo de avisos. lock_settings impede que participantes mudem nome e foto. admin_approval exige aprovação para entrar. admin_add_only restringe quem pode adicionar pessoas. picture define a foto, e disappearing_messages liga as mensagens temporárias com 24h, 7d ou 90d.
Para grupos grandes, envie async: true. A API responde na hora com um commandId e os participantes são adicionados em segundo plano, sem risco de timeout no seu request.
Gerenciar participantes em lote
Matrícula, cancelamento e troca de turma viram uma chamada só em POST /api/v1/groups/{groupId}/participants, com uma lista de números e uma action.
{
"sessionId": "escola-idiomas-secretaria",
"participants": ["5511977776666", "5511966665555"],
"action": "add"
}
As ações são add, remove, promote e demote. Promover serve, por exemplo, para dar ao professor o papel de administrador do grupo da turma. A resposta traz o resultado por participante, o que permite marcar no seu cadastro quem entrou e quem precisa de atenção.
Convites, entrada e pedidos de aprovação
Às vezes faz mais sentido o aluno entrar por conta própria do que ser adicionado. Para esses casos, o convite resolve.
GET /api/v1/groups/{groupId}/invite devolve o link de convite do grupo, que o seu sistema manda por e-mail ou por mensagem individual. POST /api/v1/groups/{groupId}/invite/revoke invalida o link atual e gera um novo, útil quando o convite vazou num lugar público.
Com admin_approval ligado, quem abre o link cria um pedido de entrada. O seu sistema decide: POST /api/v1/groups/{groupId}/join-requests/approve aprova a lista de números informada, e /join-requests/reject recusa. Para uma comunidade de alunos, isso permite aprovar só quem está com a matrícula ativa, checando no seu banco antes.
No sentido contrário, POST /api/v1/groups/{groupId}/join faz o número da sessão entrar num grupo existente, usando o código do convite no lugar do groupId. E POST /api/v1/groups/{groupId}/leave tira o número de um grupo.
Ajustar nome, descrição, foto e privacidade
O grupo muda ao longo do tempo, e as rotas de edição acompanham:
| Rota | O que muda |
|---|---|
PUT /api/v1/groups/{groupId}/name |
Nome do grupo |
PUT /api/v1/groups/{groupId}/description |
Descrição |
PUT /api/v1/groups/{groupId}/profile-picture |
Foto, por URL ou base64 |
PUT /api/v1/groups/{groupId}/settings |
announce, locked, joinApproval e memberAddMode |
Em settings, announce: true deixa só os admins enviarem mensagens, locked: true reserva aos admins a edição das informações, joinApproval: true exige aprovação para entrar e memberAddMode escolhe entre admin e all para quem pode adicionar participantes. Uma academia pode abrir o grupo para conversa na semana de desafio e fechar para avisos no resto do mês.
Comunidades: vários grupos sob uma mesma marca
Uma comunidade reúne grupos relacionados, com um grupo de avisos que fala com todos. Para uma escola, é a comunidade da unidade com um grupo por turma.
Crie a comunidade com is_parent: true em POST /api/v1/groups/create. O WhatsApp cria junto o grupo de avisos e um subgrupo Geral, e a comunidade nasce só com a sessão como administradora. Para criar uma turma já dentro dela, envie parent_jid com o JID da comunidade. E para trazer um grupo que já existe, use POST /api/v1/groups/{groupId}/link.
Os membros entram pelo grupo de avisos: um add no JID da comunidade é redirecionado para ele. A documentação da D-API detalha a criação e o vínculo de grupos em comunidades.
Enviar mensagens para grupos
O envio para grupo usa as mesmas rotas de enviar mensagem pela API: basta colocar o JID do grupo, terminado em @g.us, no campo to. Os JIDs dos grupos da sessão vêm em GET /api/v1/groups/list, que aceita participants=true para trazer também os membros, e os detalhes de cada um em GET /api/v1/groups/{groupId}/info.
Com mentionAll: true, a mensagem menciona todos os participantes, o jeito de chamar a atenção da turma inteira para o aviso de aula cancelada.
Acompanhar o grupo pelo webhook
Cada movimentação gera um evento com o group_jid e o group_name. Os de participantes trazem a lista de participants afetados e o sender que executou a ação; os de pedido de entrada trazem o requester_jid:
| Evento | Quando |
|---|---|
groups_participants.join |
Alguém entrou no grupo |
groups_participants.leave |
Alguém saiu ou foi removido |
groups_participants.promote |
Alguém virou admin |
groups_participants.demote |
Alguém deixou de ser admin |
group_participants.join-request |
Pedido de entrada criado |
group_participants.join-request.approved |
Pedido aprovado, com approved_by |
group_participants.join-request.revoked |
Pedido cancelado pelo solicitante |
Com esses eventos, o seu painel mostra a lista de membros sempre atualizada, e o seu relatório registra quem saiu do grupo da turma antes do fim do curso. Mensagens trocadas dentro dos grupos chegam em messages.received com is_group: true e o group_name, desde que a sessão esteja com ignoreGroups desligado. A lista completa está em eventos de webhook, e a visão geral da plataforma na página da API de WhatsApp.
Time D-API. Atualizado em .
Perguntas frequentes
Por que não recebo as mensagens dos grupos no webhook?
Porque a sessão nasce com ignoreGroups ligado, para não inundar o seu endpoint. Desligue na criação da sessão ou em POST /api/v1/sessions/{sessionId}/ignore-settings com ignoreGroups false.
Como o meu sistema entra num grupo pelo link de convite?
Use POST /api/v1/groups/{groupId}/join passando o código do convite no lugar do groupId, com o sessionId no corpo.
Existe evento quando um pedido de entrada é recusado?
Não. O webhook cobre o pedido criado, o pedido cancelado pelo solicitante (revoked) e o pedido aprovado. A recusa feita pela API é confirmada na resposta da rota de reject.
A API de grupos funciona na API Oficial?
As rotas de grupos descritas aqui fazem parte da conexão não oficial, que conecta o número por QR code ou código de pareamento.