Campanha Black Friday

Ao final, você tem uma campanha agendada para a data, com A/B test entre dois templates, custo estimado antes do envio e o Brain respondendo quem responder. Os exemplos usam a API REST direto: os SDKs não têm métodos de campanha.

Antes de começar

Chave de API na variável ARARA_API_KEY. Ver Autenticação.
Número conectado e com a qualidade acompanhada antes de subir volume. Ver Números.
Templates MARKETING aprovados (o passo 1 cria). Ver Templates.
Lista de contatos com consentimento para marketing. A segmentação é do seu lado: a campanha recebe a lista pronta.
Lista sem opt-out. Confira os contatos com optOutAt preenchido (GET /v1/contacts) e os números em GET /v1/opt-outs.

Passo a passo

Crie os templates com antecedência

A aprovação é da Meta e o prazo não é controlado pela Arara. Um conjunto comum:

Template	Uso
`bf_aquecimento`	Aviso alguns dias antes
`bf_lancamento_a` e `bf_lancamento_b`	Variantes A e B do dia principal
`bf_lembrete`	Reabordagem de quem não comprou
`bf_ultimo_dia`	Último dia da promoção

curl -X POST https://api.ararahq.com/v1/templates \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bf_aquecimento",
    "category": "MARKETING",
    "language": "pt_BR",
    "body": "Oi {{1}}, no dia {{2}} começa a nossa Black Friday. Quer receber o aviso quando abrir? Responda SIM.",
    "samples": { "1": "João", "2": "27/11" }
  }'

samples é um objeto com o número da variável como chave. Acompanhe a aprovação com GET /v1/templates/{id}/status ou pelo webhook template.updated.

Estime o custo

Pela contagem de destinatários:

curl "https://api.ararahq.com/v1/campaigns/estimate?templateName=bf_lancamento_a&count=50000" \
  -H "Authorization: Bearer $ARARA_API_KEY"

Pela lista real de telefones, que calcula por país de destino:

curl -X POST https://api.ararahq.com/v1/campaigns/estimate \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateName": "bf_lancamento_a", "phones": ["+5511999999999"] }'

A resposta traz templateCategory, recipientCount, templateCost (custo Meta total), araraFee (taxa Arara total), unitPrice (preço médio por mensagem), totalCost e, só no POST, markets (quebra por mercado de destino).

Aqueça a base

Envie bf_aquecimento alguns dias antes, em uma campanha própria. Quem responder SIM abre a janela de 24h e vira um grupo prioritário para o dia principal. Para identificar as respostas, escute o webhook message.received e marque o contato do seu lado ou com etiqueta (PATCH /v1/contacts/{phone}).

Crie a campanha principal com A/B test

A/B test e agendamento vão no mesmo pedido. templateName é a variante A.

curl -X POST https://api.ararahq.com/v1/campaigns \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Idempotency-Key: campanha-bf-2026-principal" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BF principal",
    "templateName": "bf_lancamento_a",
    "contacts": [
      { "to": "+5511999999999", "variables": ["João"] }
    ],
    "abTest": {
      "variantBTemplateName": "bf_lancamento_b",
      "metric": "CLICKED",
      "samplePct": 20,
      "splitPct": 50,
      "decisionWindowMinutes": 240,
      "autopilot": true
    },
    "scheduledAt": "2026-11-27T12:00:00Z"
  }'

Resposta 200 com { id, name, status, totalMessages, totalCost, scheduledAt }. status nasce SCHEDULED com scheduledAt e INGESTING quando envia na hora.

Idempotency-Key é obrigatória. Use um identificador da campanha no seu sistema. Repetir a chave devolve a campanha já criada, sem enviar de novo.
contacts[].to é o telefone. contacts[].variables preenche {{1}}, {{2}}… na ordem.
sender (opcional) escolhe o número de envio.
scheduledAt (opcional, ISO 8601) aceita de 5 minutos a 30 dias no futuro. Fora disso a API responde CAMPAIGN_SCHEDULE_TOO_SOON ou CAMPAIGN_SCHEDULE_TOO_FAR. Sem scheduledAt, envia na hora.

Campo de `abTest`	Default	Significado
`variantBTemplateName`	obrigatório	Template da variante B, da sua organização
`metric`	`CLICKED`	`DELIVERED`, `READ`, `CLICKED` ou `CONVERTED`
`samplePct`	`20`	Percentual dos contatos que entra no teste. O restante espera a vencedora.
`splitPct`	`50`	Divisão entre A e B dentro da amostra (1 a 99)
`decisionWindowMinutes`	`240`	Prazo máximo para decidir
`autopilot`	`true`	Envia o restante pela vencedora assim que houver decisão

Use CLICKED em template com link rastreado e READ quando o objetivo é a leitura. CONVERTED só serve se você registra conversões (ver Atribuição). DELIVERED raramente ajuda: a entrega não depende do texto.A vencedora sai quando a diferença entre A e B fica estatisticamente significativa ou quando a janela termina. Com autopilot: false, o restante fica retido até você escolher:

curl -X POST https://api.ararahq.com/v1/campaigns/{id}/ab-test/winner \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "winner": "A" }'

GET /v1/campaigns/{id}/ab-test mostra o estado do teste (winner, decidedReason, pValue e as métricas de cada variante).

Acompanhe o envio

curl https://api.ararahq.com/v1/campaigns/{id} \
  -H "Authorization: Bearer $ARARA_API_KEY"

Campos principais: status, totalMessages, sentCount, deliveredCount, readCount, failedCount, clickedCount, convertedCount, replyCount, holdoutCount (retidos esperando a vencedora), blockedCount e blockReasons (cada motivo de bloqueio com a quantidade de contatos), refundCount, refundValue, totalCost, startedAt e finishedAt.GET /v1/campaigns?status=... lista as campanhas. POST /v1/campaigns/{id}/cancel cancela. Ao terminar, a Arara envia o webhook campaign.completed.

Sinal	O que fazer
`failedCount` subindo	Veja `blockReasons` e o `errorDetails` dos webhooks `message.status_updated`
Webhook `number.tier_updated` ou `template.quality_updated`	Reduza o volume de marketing e revise o texto
`replyCount` alto	Garanta Brain ou time respondendo

Reaborde quem não comprou

O cruzamento é do seu lado: pegue quem recebeu a campanha principal, remova quem comprou no período e quem está em opt-out, e crie outra campanha com a lista resultante.

curl -X POST https://api.ararahq.com/v1/campaigns \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Idempotency-Key: campanha-bf-2026-reabordagem" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BF reabordagem",
    "templateName": "bf_lembrete",
    "contacts": [
      { "to": "+5511999999999", "variables": ["João"] }
    ],
    "scheduledAt": "2026-11-29T15:00:00Z"
  }'

O mesmo vale para o último dia, com bf_ultimo_dia.

Responda quem respondeu

Resposta a template abre a janela de 24h. Com volume alto, o Brain responde primeiro e passa para o time quando precisa. Adicione a promoção à base de conhecimento e ligue a resposta automática:

curl -X POST https://api.ararahq.com/v1/brain/knowledge \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Promoção válida de 27/11 a 30/11. Frete grátis acima de R$ 199. Cupom não acumula com outros descontos. Troca em até 7 dias."
  }'

curl -X PATCH https://api.ararahq.com/v1/brain/config \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": true,
    "assistMode": "AUTO",
    "exitTriggers": {
      "customerAsks": ["falar com atendente", "humano", "reclamação"],
      "maxMessages": 10
    }
  }'

exitTriggers.maxMessages conta o histórico inteiro com o contato, incluindo as mensagens da campanha. Cada passagem para humano gera o webhook conversation.needs_human. Modos, gatilhos e pré-requisitos do Brain em Atendimento com vários atendentes.

Armadilhas

A janela de decisão do A/B test conta a partir da criação da campanha, não do envio. Em campanha agendada, some o tempo até o scheduledAt ao decisionWindowMinutes, senão o teste termina antes de ter métricas.

Próximos passos

Campanhas de marketing

O que vale fora da data sazonal.

Campanhas na API

Todos os campos e erros.

Carrinho abandonado

Fluxo contínuo, que segue depois da campanha.

Receitas

Recursos

Automações

Brain (IA)

Integrações

Migrar de

Antes de começar

Passo a passo

Armadilhas

Próximos passos

Campanhas de marketing

Campanhas na API

Carrinho abandonado

​Antes de começar

​Passo a passo

​Armadilhas

​Próximos passos

Campanhas de marketing

Campanhas na API

Carrinho abandonado

Antes de começar

Passo a passo

Armadilhas

Próximos passos