# Campanhas

Estas rotas devolvem o **desempenho das campanhas de mensagens** (WhatsApp e e-mail) da empresa: quantas mensagens foram enviadas, entregues, lidas, respondidas, com falha ou puladas. Servem para BI de marketing.

**Escopo exigido:** `campaigns:read`. Sem ele, as rotas respondem [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing).

Saem só **números**. Nunca saem os destinatários (nome, telefone, e-mail), o texto das mensagens, o corpo e o link do e-mail, o público escolhido, a declaração de consentimento nem qualquer valor em dinheiro. Os contadores de resposta e de saída olham apenas a data e a direção das mensagens, nunca o conteúdo da conversa.

[Testar na referência interativa](https://developers.festero.com.br/referencia/)

## Listar campanhas

### `GET /v1/campaigns`

Lista as campanhas, da alteração mais antiga para a mais recente. [Paginação por cursor](https://developers.festero.com.br/paginacao.md).

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `status` | texto | `draft`, `scheduled`, `sending`, `paused`, `completed` ou `cancelled`. |
| `updatedSince`, `limit`, `cursor` | | Como nas demais listas. |

| Campo | Descrição |
|---|---|
| `name`, `status`, `channel` | Nome, situação e canal (`whatsapp`, `email` ou `both`). |
| `templateName` | Modelo de mensagem do WhatsApp usado. |
| `scheduledAt`, `startedAt`, `completedAt` | Instantes do agendamento, do início e do fim. |
| `pausedBySystem`, `pauseReasonCode` | Pausa feita pelo sistema (por exemplo, por qualidade ou limite da conta) e o código do motivo. |
| `counters` | WhatsApp: `total`, `pending`, `sent`, `delivered`, `read`, `failed`, `skipped`, `replied` (respondeu em até 72 horas) e `optedOut` (pediu para sair depois do envio). |
| `emailStatus`, `emailCounters` | Canal de e-mail: situação e `total`, `pending`, `sent`, `delivered`, `bouncedPermanent`, `bouncedTransient`, `complained`, `clicked`, `opened`, `unsubscribed`, `failed` e `skipped`. |

## Buscar uma campanha

### `GET /v1/campaigns/{id}`

Devolve uma campanha com os mesmos campos. `404` se não existe ou é de outra empresa. Traz `ETag`.

## Relatório da campanha

### `GET /v1/campaigns/{id}/report`

Devolve a campanha (`campaign`) mais as quantidades de destinatários por motivo, para cada canal: `failureReasons` e `skipReasons` (WhatsApp) e `emailFailureReasons` e `emailSkipReasons` (e-mail). Cada item tem o `code` do motivo e a `count`. Sem destinatários.