Manual IA — terminais de Grupos WhatsApp

Use este guia quando o gestor pedir controle de grupos via IA. Cada “terminal” = um endpoint HTTP. Spec: /specs/whatsapp-groups-api.yml.

Contrato global

Antes de mutar: confirme account_id, inbox WORKING (available_waha_sessions / inbox_status), e que o gestor autorizou envio real.

Ordem canônica

1. GET .../whatsapp_groups/available_waha_sessions
2. POST .../whatsapp_groups (criar sala)
3. POST .../whatsapp_group_campaigns com group_ids
4. POST .../whatsapp_group_broadcasts (conteúdo)
5. Opcional: POST .../broadcasts/{id}/cancel se agendado

Terminais

T1 — Sessões WAHA

GET /whatsapp_groups/available_waha_sessions
GET /whatsapp_groups/inbox_status
Quando: abrir operação; escolher inbox_id.
OK: status WORKING. Bloquear envio se desconectado.

T2 — Grupos

POST create exemplo:

{
  "whatsapp_group": {
    "name": "Turma Maio #1",
    "inbox_id": 13,
    "max_members": 1024,
    "initial_members": ["5551989769026"],
    "admin_members": ["5551989769026"]
  }
}

Este POST só cria grupo — não aceita chat_kind. Canal só sai pelo provisionamento em lote (T2b). Não invente um campo chat_kind aqui.

T2b — Provisionar em lote (grupo ou canal)

POST /whatsapp_group_launches/provision

{
  "launch_id": "lancamento-x",
  "inbox_id": 13,
  "count": 3,
  "name_prefix": "Turma Maio",
  "chat_kind": "channel",
  "create_campaign": true,
  "campaign_name": "Turma Maio"
}

chat_kind: "group" (padrão) ou "channel". Canal ignora max_members e admin_members mesmo se enviados (canal não tem esse conceito).

T3 — Membros

T4 — Campanhas

POST create exemplo:

{
  "whatsapp_group_campaign": {
    "name": "Campanha Turma Maio",
    "status": "active",
    "group_ids": [10],
    "settings": {
      "default_inbox_id": 13,
      "admin_inbox_ids": [13],
      "max_members": 1024,
      "auto_provision": false,
      "name_prefix": "Turma Maio"
    }
  }
}

T5 — Disparos (broadcasts)

Tipos (media_type): omitir = texto · image · video · document · audio · poll · contact · event · location.

Texto agora:

{
  "whatsapp_group_broadcast": {
    "content": "Olá turma!",
    "whatsapp_group_campaign_id": 6,
    "target_group_ids": [10],
    "remove_members_after": false
  }
}

Imagem com legenda: content + media_type: image + media_url (URL pública).
Enquete: media_type: poll, content = pergunta, poll_options: ["A","B"].
Localização: media_type: location, extras: { latitude, longitude, title?, address? }.
Agendar: scheduled_at: "2026-08-02T15:00:00-03:00".

Após POST 201: poll GET até completed|failed|cancelled. Não reenvie.

T6 — Atividades

GET /whatsapp_group_activities — auditoria (joined, broadcast, etc.).

T7 — Webhooks de entrada

CRUD em /whatsapp_group_webhooks.
Create body aninhado whatsapp_group_webhook. Retorna webhook_url + token.

T8 — Sequências

CRUD em /whatsapp_group_sequences.
Envie steps (whatsapp_group_sequence_steps_attributes). Create vazio pode falhar.

T9 — Adotar grupo, canal ou comunidade existente

POST /whatsapp_groups/adopt

Quando: o grupo/canal já existe no WhatsApp (criado à mão ou por outra via) e só precisa entrar na conta — sobretudo comunidade, que a API do WhatsApp não deixa criar. O caminho é a pessoa criar a comunidade à mão e adotar o grupo de avisos dela.

{
  "whatsapp_group": {
    "inbox_id": 13,
    "jid": "[email protected]",
    "name": "Avisos — Lançamento X",
    "max_members": 1024,
    "is_community": true
  }
}

422 específicos deste terminal (além dos genéricos): invalid_jid, already_adopted, not_visible_to_session, not_admin (não se aplica a canal), community_must_be_group, community_is_parent_jid (colou o JID da comunidade, não do grupo de avisos), not_community_group.

Respostas que a IA deve interpretar

Proibições

• Inventar endpoint ou campo
• Retry após 201 de create (duplica grupo/disparo)
• Expor token/telefone completo em logs públicos
• Disparo em massa sem confirmação do gestor
• Usar produção como playground sem OK

Checklist pré-envio (IA)

• account_id correto
• inbox WORKING
• group_id e campaign_id existem
• mídia URL pública e tipo certo
• gestor confirmou texto/agendamento
• remove_members_after=false salvo se pedido

Evidência mínima ao reportar

method path → http → ids → status final do broadcast