Segmentos e Campanhas (Marketing)

Os módulos de Segmentos e Campanhas permitem estruturar ações de relacionamento em massa (disparos de e-mail e mensagens de chat) com base em audiências segmentadas dinamicamente.

---

Módulo de Segmentos (Filtros Dinâmicos)

Segmentos são grupos dinâmicos de contatos cujos membros atendem a regras específicas (ex: "Contatos com e-mail preenchido criados há menos de 30 dias").

1. Listar Segmentos

Retorna a lista de segmentos cadastrados na organização.

• Método: GET
• Caminho: /segments

2. Simular/Preview do Segmento

Permite testar as regras de filtragem antes de salvar o segmento definitivamente, retornando uma prévia dos contatos elegíveis.

• Método: POST
• Caminho: /segments/preview
• Payload de Exemplo (Regra de filtro JSON):

  {
    "rules": {
      "condition": "AND",
      "rules": [
        {
          "field": "email",
          "operator": "contains",
          "value": "@empresa.com"
        }
      ]
    }
  }

3. Obter Contagem do Segmento

Retorna a quantidade exata de contatos atualmente qualificados dentro daquele segmento.

• Método: GET
• Caminho: /segments/{id}/count

---

Módulo de Campanhas (Disparos Omnichannel)

Campanhas gerenciam a fila de entrega em massa para uma audiência vinculada a um Canal e um Segmento.

1. Criar Campanha

Cria um rascunho de campanha informando o canal de disparo, a audiência (segmento) e a mensagem/template.

• Método: POST
• Caminho: /campaigns
• Payload de Exemplo:

  {
    "data": {
      "name": "Campanha de Inverno 2026",
      "channel": "channel_whatsapp_01",
      "segment": "segment_leads_ativos_12",
      "template": "template_doc_id_123",
      "variables": {
        "cupom": "WINTER26"
      }
    }
  }

---

2. Controlar Ciclo de Vida da Campanha

Uma campanha criada fica em estado draft (rascunho). Para operá-la, utilize os endpoints de disparo e controle:

• Disparar / Iniciar: POST /campaigns/{id}/trigger
• Pausar Envios: POST /campaigns/{id}/pause
• Retomar Envios: POST /campaigns/{id}/resume
• Cancelar Disparo: POST /campaigns/{id}/cancel

---

3. Obter Estatísticas da Campanha

Retorna as métricas de entrega em tempo real, incluindo quantidade de envios bem-sucedidos, falhas, taxa de abertura e leitura.

• Método: GET
• Caminho: /campaigns/{id}/stats
• Exemplo de Resposta:

  {
    "campaignId": "camp_abc_123",
    "stats": {
      "totalAudience": 450,
      "sent": 380,
      "failed": 2,
      "pending": 68,
      "readRate": 0.74
    }
  }