A SiteUp administra grupos WhatsApp via WAHA (não só o canal Cloud API 1:1). Gestores operam pelo painel em Grupos e também pela API — o mesmo contrato que agentes de IA devem usar.

O que você consegue fazer

Recurso	Painel	API
Criar grupo no WhatsApp	Sim (Criar Grupo)	`POST .../whatsapp_groups`
Provisionar canal em lote	Sim (wizard, tipo Canal)	`POST .../whatsapp_group_launches/provision` com `chat_kind: "channel"`
Adotar grupo, canal ou comunidade já existente	Sim ("Adotar grupo existente")	`POST .../whatsapp_groups/adopt`
Listar / filtrar / sync membros	Sim	GET + `POST .../sync_members`
Adicionar / promover / remover membro	Sim	members CRUD + promote/demote
Campanhas (pool de números + salas)	Wizard 5 etapas	`whatsapp_group_campaigns`
Disparo texto + mídia + enquete + contato + evento + localização	Novo disparo	`whatsapp_group_broadcasts`
Agendar e cancelar disparo	Sim	create + `POST .../cancel`
Webhook de entrada (lead → grupo)	Sim	`whatsapp_group_webhooks`
Sequências de nutrição	Sim	`whatsapp_group_sequences`

Conceitos

Inbox WAHA — número conectado (ex.: sessão whatsapp_123_13_1). Precisa status WORKING.
Grupo — sala real no WhatsApp (waha_group_id tipo [email protected]), capacidade 1024.
Canal — waha_group_id termina em @newsletter. Sem participantes, sem admin promovível, sem teto — só link de convite. Só sai via provisionamento em lote (chat_kind: "channel"), o POST .../whatsapp_groups de criação individual não tem essa opção.
Comunidade — a API do WhatsApp não permite criar comunidade (só ler se um grupo pertence a uma). O caminho é criar a comunidade à mão no número conectado e adotar o grupo de avisos dela por JID (is_community: true no adopt) — a SiteUp confere no WhatsApp que o JID é realmente o grupo de avisos antes de aceitar.
Campanha — agrupa salas + pool ordenado de inboxes + regras (auto-próximo, prefixo #N, admins).
Disparo (broadcast) — mensagem para um ou mais grupos da campanha (agora ou agendado).
Webhook de entrada — URL pública que convida/adiciona contatos a um grupo.

Fluxo feliz (gestor ou IA)

1. Conferir sessões WAHA WORKING
2. Criar grupo (inbox_id + membros/admins)
3. Criar campanha com group_ids = [grupo]
4. Disparar conteúdo (texto ou midia)
5. Opcional: agendar / cancelar / webhook

API e specs

Spec Grupos (OpenAPI): /specs/whatsapp-groups-api.yml
Spec geral: /specs/siteup-api.yml
Manual para IA (terminais): /ajuda/canais/api-grupos-manual-ia
Cursor rules: /cursor-rules.md
Claude instructions: /claude-instructions.md

Auth

api_access_token: <token do usuario Profile>

Ou login Devise (POST /auth/sign_in) com headers access-token, client, uid.

Regras que evitam erro

Telefone sem + (5551...).
Campanha sem group_ids → 422.
Áudio: use mp3 (ogg genérico falha com frequência).
Caption em áudio não é enviada pelo backend.
Mutações sensíveis: perfil admin da conta.

Limitações conhecidas (2026-08)

PUT de campanha com payload mínimo pode retornar 500 em alguns casos — revalidar no app/logs.
POST de sequência sem steps completos pode 500 — enviar whatsapp_group_sequence_steps_attributes válidos.
Prod e staging rodam o mesmo digest de produto Groups v741.

UI no painel

Rota: /app/accounts/:id/whatsapp-groups/campaigns (hífen).
Wizard campanha: Objetivo → Números → Salas → Admins → Entrada.
Wizard disparo: Conteúdo → Destino → Agenda.

Gestão de grupos do WhatsApp