# Campanhas

Envio em massa com intervalo entre as mensagens, agendamento e acompanhamento. Cada mensagem tem o formato do
corpo do [`POST /messages`](/endpoint/post/messages), sem `to`, `reply_to`, `track_source`, `track_id` e `options`: o
`type` e os campos do tipo soltos, mais `mentions`, `mention_all` e `forwarded`.

## Criar

**Simples** (a mesma mensagem para vários):

```json
POST /campaigns
{
  "name": "Black Friday",
  "scheduled_at": "2026-11-27T12:00:00.000Z",
  "delay_min_seconds": 10,
  "delay_max_seconds": 30,
  "recipients": ["5511999999999", "5511988888888"],
  "message": { "type": "text", "text": "Só hoje: 30% em tudo!" }
}
```

**Avançada** (uma mensagem para cada um):

```json
POST /campaigns
{
  "name": "Lembrete de pagamento",
  "messages": [
    { "to": "5511999999999", "message": { "type": "text", "text": "Oi, Maria! Sua fatura vence amanhã." } },
    { "to": "5511988888888", "message": { "type": "document", "url": "https://loja.com/boleto.pdf", "filename": "boleto.pdf" } }
  ]
}
```

A resposta é a campanha, com `id` e `status` (`scheduled` ou `sending`). O intervalo entre as mensagens é sorteado
de `delay_min_seconds` até um segundo a menos que `delay_max_seconds` (com os dois iguais, sai entre esse valor e ele mais 1 s; não existe intervalo fixo). Intervalos curtos aumentam o risco de bloqueio do número.

## Acompanhar

- [`GET /campaigns`](/endpoint/get/campaigns): todas, com os contadores (`total`, `sent`, `delivered`, `read`, `failed`).
- [`GET /campaigns/{campaign_id}/messages?status=failed`](/endpoint/get/campaigns~:campaign_id~messages): as que falharam, com o motivo em `error`.
- Eventos: `campaign.updated` (agendada, enviando, pausada e concluída), `message.status` de cada mensagem e, só para as que falharam, `message.failed` (com `campaign_id`).

## Controlar

| Quero | Rota |
|---|---|
| Pausar | `PATCH /campaigns` com `status: paused` |
| Retomar | `PATCH /campaigns` com `status: scheduled` (se o horário marcado ainda não chegou, espera por ele) |
| Mandar agora | `PATCH /campaigns` com `status: sending` (agendada ou pausada) |
| Reagendar | `PATCH /campaigns` com `scheduled_at` |
| Apagar uma | `DELETE /campaigns/{campaign_id}` |
| Limpar as campanhas terminadas | `DELETE /campaigns?status=done&older_than_hours=168` |