> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Campanhas de marketing
> Opt-in, frequência, teste A/B e como criar uma campanha de marketing no WhatsApp pela API.
WhatsApp não é email. Envio para quem não pediu gera bloqueio e denúncia, e isso derruba a qualidade do número. Esta página resume o que importa para rodar campanhas de marketing com a Arara.
## As 3 regras
O cliente precisa ter aceitado receber mensagens da sua marca. Respeite quem pediu para sair: números em opt-out (`/v1/opt-outs`) não recebem envio. Ver [Compliance](/concepts/compliance) e [Política de templates](/templates/policy).
Fora da janela de 24h (cliente não falou com você nas últimas 24h), só template aprovado pela Meta. Texto livre fora da janela é recusado pela API. Ver [Templates](/concepts/templates) e [Janela de 24h](/concepts/24h-window).
Promoção, oferta e reengajamento são **MARKETING**. Aviso transacional real (pedido confirmado, pagamento, entrega) é **UTILITY**. Template de marketing tem custo maior na Meta, sofre limite de frequência por destinatário e pesa mais na qualidade do número. Use UTILITY quando o conteúdo for de fato transacional.
## Custo
A cobrança é por mensagem e depende da categoria do template e do seu plano. Consulte os valores vigentes no dashboard e em [Preços](/concepts/pricing). Antes de criar a campanha, `GET /v1/campaigns/estimate` (ou `POST` com a lista) devolve a estimativa da campanha.
O tier do número (limite de destinatários únicos por dia) é definido pela Meta e limita **quantas** conversas você inicia, não o preço.
## Fluxo recomendado
```
1. Segmente no seu CRM → exporte a lista
2. Carregue contatos na Arara → POST /v1/contacts/batch
3. Crie o template MARKETING → POST /v1/templates (aprovação da Meta)
4. Crie a campanha, com A/B se quiser → POST /v1/campaigns (abTest opcional)
5. Acompanhe entrega e respostas → webhooks message.status_updated e message.received
6. Meça clique e conversão → Smart Links e conversões reportadas
```
Como criar, categorizar e aprovar.
API de envio em massa.
Campanha completa com teste A/B.
## Contatos
```bash theme={null}
curl -X POST https://api.ararahq.com/v1/contacts/batch \
-H "Authorization: Bearer $ARARA_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{ "name": "João Silva", "phone": "+5511999999999", "attributes": { "segment": "vip", "city": "SP" } },
{ "name": "Maria Souza", "phone": "+5521988887777", "email": "maria@exemplo.com" }
]'
```
O corpo é uma lista. `name` e `phone` (E.164) são obrigatórios; `email` e `attributes` são opcionais. O uso de contatos depende do plano.
A campanha não filtra por atributo: você seleciona o público fora da Arara e passa a lista em `contacts` no `POST /v1/campaigns`.
## Frequência
Template de marketing sofre limite de frequência por destinatário na Meta, e excesso de mensagens vira bloqueio e denúncia.
* Envie só para quem tem opt-in recente.
* Envie em horário comercial.
* Não repita a mesma oferta para a mesma pessoa em sequência.
## Segmentação que funciona
* **Comportamento**: quem comprou nos últimos 30 dias, quem abandonou carrinho.
* **Localização**: oferta de loja física só para região atendida.
* **Valor do cliente**: clientes de maior valor recebem atendimento humano; o restante recebe template.
* **Horário**: mensagem de madrugada vira bloqueio.
## Teste A/B
O A/B vai junto na criação da campanha. `templateName` é a variante A e `abTest.variantBTemplateName` é a B:
```bash theme={null}
curl -X POST https://api.ararahq.com/v1/campaigns \
-H "Authorization: Bearer $ARARA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: blackfriday-2026-lote-1" \
-d '{
"name": "Black Friday 2026",
"templateName": "blackfriday_v1",
"contacts": [
{ "to": "+5511999999999", "variables": ["João"] },
{ "to": "+5521988887777", "variables": ["Maria"] }
],
"abTest": {
"variantBTemplateName": "blackfriday_v2",
"metric": "CLICKED",
"samplePct": 20,
"splitPct": 50,
"decisionWindowMinutes": 240,
"autopilot": true
}
}'
```
| Campo | Default | Descrição |
| - | - | - |
| `metric` | `CLICKED` | `DELIVERED`, `READ`, `CLICKED` ou `CONVERTED` |
| `samplePct` | `20` | % dos contatos que entra no teste |
| `splitPct` | `50` | Divisão entre A e B dentro da amostra |
| `decisionWindowMinutes` | `240` | Tempo até decidir a vencedora |
| `autopilot` | `true` | Envia o restante com a vencedora automaticamente |
`CLICKED` conta cliques nos links curtos das mensagens (botão `SMART_LINK` ou URL em variável). `CONVERTED` conta [conversões reportadas](/smart-links/attribution).
Resultado e controle manual:
* `GET /v1/campaigns/{campaignId}/ab-test` traz vencedora, `pValue`, `relativeLiftPct` e as métricas de cada variante.
* `POST /v1/campaigns/{campaignId}/ab-test/winner` com `{ "winner": "A" }` força a vencedora.
`POST /v1/campaigns` exige o header `Idempotency-Key` e um número conectado.
## Medindo resultado
Links de mensagem saem como links curtos que registram cada clique, e a venda é ligada à mensagem quando o seu backend reporta a conversão. O que é um Smart Link e como usar está em [Smart Links](/smart-links). Para reportar vendas, veja [Atribuição de conversão](/smart-links/attribution).
## Quando não usar marketing no WhatsApp
* Comunicação genérica para a base inteira, sem segmentação.
* Oferta de ticket muito baixo, em que o custo por mensagem come a margem.
* Base inativa há meses sem opt-in recente. O risco de bloqueio e denúncia é alto.
* Cobrança de inadimplência como MARKETING. Aviso de fatura é UTILITY.
## Próximos passos
Link curto com contagem de cliques.
O que evitar e qual categoria escolher.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.