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.

1. O que você precisa saber antes

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

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

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

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, 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:

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.

Esta página em Markdown