# Campanhas, do começo ao fim

Uma campanha manda um modelo aprovado pela Meta, de um número seu, para uma lista de contatos, e leva as respostas para quem você escolher (uma equipe, um fluxo ou um assistente de IA). Este guia faz uma campanha inteira pela API. Teste tudo antes com a [chave de demonstração](/desenvolvedores/modo-teste/).

## 1. O que você precisa saber antes

```bash
curl https://api.donetalk.com/v1/c/{empresa}/channels -H "Authorization: Bearer $DONETALK_KEY"
curl https://api.donetalk.com/v1/c/{empresa}/templates -H "Authorization: Bearer $DONETALK_KEY"
curl https://api.donetalk.com/v1/c/{empresa}/teams -H "Authorization: Bearer $DONETALK_KEY"
```

- **Número (`channelId`):** de onde a mensagem sai.
- **Modelo (`templateId`):** um modelo `approved` da mesma conta do número. As variáveis aparecem no texto como `{{1}}`, `{{2}}`.
- **Equipe (`reply.id`):** quem recebe as respostas.

## 2. Criar o rascunho, com a lista

```bash
curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Idempotency-Key: reativacao-2026-10" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reativação · outubro",
    "channelId": "…",
    "templateId": "…",
    "variables": [
      { "slot": "body.1", "source": "first_name", "fallback": "tudo bem" },
      { "slot": "body.2", "source": "value.cupom", "format": "upper" }
    ],
    "audience": {
      "kind": "contacts",
      "people": [
        { "phone": "+5548999990001", "name": "Ana Souza", "values": { "cupom": "ana10" } },
        { "phone": "+5548999990002", "name": "Bruno Lima", "values": { "cupom": "bru15" } }
      ]
    },
    "reply": { "kind": "team", "id": "…" },
    "startAt": "2026-10-24T12:00:00.000Z"
  }'
```

- **Público:** `people` traz telefone, nome e valores de cada pessoa (até 20 mil; cada telefone vira um contato, criado ou atualizado, o que pede também o escopo `contacts:write`). Também dá para usar contatos já cadastrados (`contactIds`), um segmento (`{"kind": "segment", "segmentId": "…"}`) ou um filtro.
- **Variáveis:** cada `{{n}}` do modelo vem de `name`, `first_name`, `phone`, um campo do contato (`field.<chave>`), um valor da lista (`value.<chave>`) ou um texto fixo. `fallback` entra quando o valor falta.
- **Quando:** sem `startAt`, começa ao disparar; com, fica agendada. Por padrão só envia de segunda a sexta, 9h às 18h, no fuso da empresa (`sendWindow`).

## 3. Conferir antes de enviar

```bash
curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/message-preview -H "Authorization: Bearer $DONETALK_KEY"
curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/review -H "Authorization: Bearer $DONETALK_KEY"
```

A prévia mostra o texto de cinco pessoas e as variáveis vazias. A revisão traz o custo estimado (até), o limite diário do número, os orçamentos e se vai precisar de aprovação. `POST /campaigns/{id}/test` manda a mensagem para o seu telefone.

## 4. Disparar

```bash
curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/submit -H "Authorization: Bearer $DONETALK_KEY"
```

A resposta diz `running` (começou), `scheduled` (agendada) ou `pending_approval` (a regra da empresa pede aprovação, e alguém aprova no app). Uma chave marcada “Disparar campanhas sem esperar aprovação” não espera. Quem já recebeu marketing nos últimos 7 dias, pediu para sair ou está bloqueado fica de fora; a prévia do público diz quantos e por quê.

## 5. Acompanhar

Pelos [avisos](/desenvolvedores/avisos/), sem consultar nada: `campaign.started`, `campaign.recipient.sent`, `.delivered`, `.read`, `.replied`, `.failed`, `.opted_out` e `campaign.completed`, com os totais. Quando o atendimento aberto pela campanha é concluído, chega `conversation.closed` com o desfecho e o `campaignId`.

Ou consultando:

```bash
curl "https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}" -H "Authorization: Bearer $DONETALK_KEY"
curl "https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/recipients?status=replied" -H "Authorization: Bearer $DONETALK_KEY"
```

## 6. Pausar, retomar, cancelar, reenviar

`POST /campaigns/{id}/pause`, `/resume`, `/cancel`. As falhas que vale repetir voltam à fila com `POST /campaigns/{id}/retry` (todas, ou só alguns contatos ou códigos de erro). A campanha também pausa sozinha se o modelo for pausado pela Meta, a qualidade do número cair, muitos pedirem para sair ou o orçamento acabar.