Campanhas

​

O objeto campanha

​

Criar uma campanha

curl -X POST https://api.ararahq.com/v1/campaigns \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Idempotency-Key: acme-campanha-8842" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday 2026",
    "templateName": "bf_oferta_geral",
    "contacts": [
      { "to": "+5511999999999", "variables": ["João", "30"] },
      { "to": "+5511888888888", "variables": ["Maria", "25"] }
    ]
  }'

{
  "id": "7b3789fb-4c5d-6789-abcd-ef0123456789",
  "name": "Black Friday 2026",
  "status": "INGESTING",
  "totalMessages": 2,
  "totalCost": 0.767,
  "scheduledAt": null
}

​

Regras que valem saber

• Idempotency-Key é obrigatório. Repetir a chave devolve a campanha já criada, sem cobrar de novo. Derive a chave do identificador da campanha no seu sistema e reuse nas retentativas. A unicidade é global na Arara, não por organização: inclua um prefixo só seu (acme-campanha-8842), nunca um valor genérico como campanha-1. Sem o header, a resposta hoje é 500, e não 400.
• Cobrança antecipada. O total sai da carteira na criação. Contatos bloqueados no envio (opt-out, número inválido, limite de frequência) são estornados um a um.
• Pré-requisitos. Número dedicado conectado (403 NO_DEDICATED_NUMBER), saldo para o total (402 INSUFFICIENT_FUNDS) e cota do plano (403 PLAN_LIMIT_REACHED).
• variables é array posicional. ["João", "30"], não objeto.
• Estime antes. POST /v1/campaigns/estimate com a lista de telefones calcula por país de destino e bate com o valor cobrado. O GET usa só o preço do mercado local.
• Cancelar estorna o que não saiu. POST /v1/campaigns/{id}/cancel devolve à carteira os contatos que ainda não viraram mensagem. Mensagens já enfileiradas seguem. Campanha já finalizada responde 422.
• A lista tem envelope próprio. GET /v1/campaigns responde { content, totalPages, totalElements }, e não { data, pagination }.

​

Agendar

# Amanhã, neste horário. No macOS: date -u -v+1d +%Y-%m-%dT%H:%M:%SZ
SCHEDULED_AT=$(date -u -d '+1 day' +%Y-%m-%dT%H:%M:%SZ)

curl -X POST https://api.ararahq.com/v1/campaigns \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Idempotency-Key: acme-campanha-8843" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lembrete do evento",
    "templateName": "lembrete_evento",
    "scheduledAt": "'"$SCHEDULED_AT"'",
    "contacts": [{ "to": "+5511999999999", "variables": ["João"] }]
  }'

​

Teste A/B

​

Endpoints

​

Erros mais comuns

​

Próximos passos