Guias
Grupos no WhatsApp
Criar e administrar grupos pela Groups API, mandar e receber mensagens de grupo e os eventos group.*.
A Groups API da Meta deixa um número em modo só API criar e administrar grupos pequenos. No Messajo ela existe só pela API: o painel não tem tela de grupos.
Antes de começar
Seção intitulada “Antes de começar”- Conexão de WhatsApp só API. Na coexistência,
422group_not_supported. - No webhook do app da Meta, os campos
group_lifecycle_update,group_participants_update,group_settings_updateegroup_status_updateassinados. - Chave com
sendpara criar, editar e moderar,readpara ler eadminpara apagar.
curl https://api.messajo.com/v1/groups \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "subject": "Turma de sábado", "description": "Avisos da turma", "join_approval_mode": "approval_required" }'O grupo nasce creating (grp_…). A Meta cria em segundo plano e avisa por webhook: deu certo → active com o invite_link e o evento group.created; falhou → failed e group.create_failed com o motivo. subject vai até 128 caracteres e description até 2048.
| Status | O que quer dizer |
|---|---|
creating |
esperando a Meta |
active |
pronto para mensagens |
suspended |
suspenso pela Meta |
deleting · deleted |
apagado |
failed |
a Meta não criou |
Administrar
Seção intitulada “Administrar”| Chamada | O que faz |
|---|---|
GET /v1/groups · GET /v1/groups/{id} |
lista e lê (assunto, descrição, participantes, status) |
PATCH /v1/groups/{id} |
troca assunto e descrição; em multipart/form-data, o campo picture troca a foto (JPEG quadrado, ≥ 192 px, até 5 MiB) |
GET /v1/groups/{id}/invite-link · POST …/invite-link/reset |
lê ou gera um link de convite novo (o antigo deixa de valer) |
POST /v1/groups/{id}/participants/remove |
{ "participants": [{ "wa_id": "5511…" }] } ou { "user_id": "…" } |
GET /v1/groups/{id}/join-requests · POST …/approve · POST …/reject |
pedidos de entrada (join_approval_mode: approval_required); { "join_request_ids": [...] } → { approved | rejected, failed[] } |
DELETE /v1/groups/{id} |
apaga o grupo na Meta (chave admin) |
Mensagens
Seção intitulada “Mensagens”Mande com o mesmo POST /v1/messages, com o id do grupo em to:
{ "connection_id": "conn_...", "to": "grp_...", "type": "text", "text": { "body": "Aula confirmada às 9h" } }- Não há checagem de janela de 24 h: a Meta decide.
- Grupo que não está
active→409group_not_active. - Tipo de conteúdo que a Meta não aceita em grupo →
422group_message_type_not_supported.
A conversa do grupo tem kind: "group". Os eventos message.* trazem group: { id, external_id, subject } (ou null fora de grupo); numa mensagem recebida, o contact é o participante que escreveu.
Limites
Seção intitulada “Limites”| Limite | Valor |
|---|---|
| Participantes por grupo | 8 (acima → 422 group_participant_limit) |
| Grupos por número | 10.000 (o Messajo só avisa; a Meta decide) |
| Participantes por remoção | 8 |
Eventos
Seção intitulada “Eventos”| Tipo | Quando |
|---|---|
group.created · group.create_failed |
a Meta terminou de criar (ou não) |
group.settings_updated |
assunto, descrição, foto ou modo de entrada mudaram |
group.participants_updated |
alguém entrou, saiu ou foi removido (joined[], left[], removed[]) |
group.join_requested |
chegou um pedido de entrada (join_request) |
group.suspended · group.unsuspended |
a Meta suspendeu ou liberou o grupo |
group.deleted |
o grupo foi apagado |
Os eventos group.* não têm sequence. Filtre por família com group.* no destino.