Gestão de grupos do WhatsApp

A SiteUP administra grupos WhatsApp via WAHA (não só o canal Cloud API 1:1), pelo painel em Grupos e pela API. Criar, adotar ou alterar grupos, sincronizar membros, adicionar, remover ou promover membros e criar, agendar ou cancelar disparos exigem perfil de administrador da conta. Agentes de IA que usam a API seguem as mesmas permissões do usuário autenticado.

Campanhas de grupos aceitam administrador ou cargo personalizado com a permissão campaigns_view. Essa permissão não libera as operações administrativas de grupos, membros e disparos. O fluxo completo abaixo pressupõe administrador. Consultar informações não concede permissão para alterá-las.

O que você consegue fazer

Conceitos

1. Inbox WAHA, número conectado (ex.: sessão whatsapp_123_13_1). Precisa status WORKING.

2. Grupo: sala real no WhatsApp (waha_group_id tipo [email protected]), capacidade 1024.

3. 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.

4. Comunidade. O registro na SiteUP é sempre o grupo de avisos, nunca a comunidade-mãe. Dois caminhos:

   • Criar pelo painel ou POST /whatsapp_groups com is_community: true. O WhatsApp cria a comunidade e o grupo de avisos; a SiteUP guarda o avisos e settings.community_parent_jid da mãe.
   • Adotar um avisos que já existe: POST /whatsapp_groups/adopt com is_community: true. A SiteUP confere no WhatsApp que o JID é avisos (IsAnnounce + LinkedParentJID) antes de aceitar.

   Campanha chat_kind: community: o link /g/:slug gira as salas e ignora o grupo de avisos enquanto houver sala ativa. Sem sala ativa, o /g/ manda para o avisos (settings.community_group_id) usando o convite da comunidade-mãe. O avisos não tem convite próprio.

5. Campanha: agrupa salas + pool ordenado de inboxes + regras (auto-próximo, prefixo #N, admins).

6. Disparo (broadcast), mensagem para um ou mais grupos da campanha (agora ou agendado).

7. Webhook de entrada, URL pública que convida/adiciona contatos a um grupo.

Fluxo de gestão com perfil administrador

Antes de começar, confiram que o usuário conectado ao painel ou associado ao token da API é administrador desta conta e que o módulo de grupos está habilitado. Isso vale também quando um agente de IA executa o fluxo.

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.
• As observações acima são históricas de agosto de 2026 e exigem revalidação. Esta página não comprova a versão atual de produção ou staging.

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.

Relacionados

• Conectar WhatsApp
• Manual IA, terminais de grupos