Quando usar
- Você quer disparar campanhas a partir do seu próprio sistema, sem abrir a tela do Cloud Chat.
- Você quer estimar quantos contatos uma audiência alcança antes de gastar envio.
- Você precisa acompanhar o estado de uma campanha de forma programática.
Pré-requisitos
Criar uma campanha dispara o envio. Não existe rascunho intermediário na API, igual à tela. Não use o endpoint de criação para "montar e revisar depois".
- Chave de API da conta. Veja Como pegar a sua API key.
- Perfil com permissão para campanhas. O perfil de atendente não consegue disparar, na API nem na tela.
Como funciona
Conferir o alcance antes de enviar
Existe um endpoint que resolve a audiência e devolve quantos contatos ela de fato alcança. Use-o antes de criar: é o que evita descobrir o tamanho real do disparo depois que ele já saiu.
A confirmação obrigatória de destinatários
Na criação, você precisa declarar quantos destinatários espera alcançar. O sistema compara esse número com o que a audiência resolve de verdade:
- Se bater, a campanha é criada e entra na fila de envio.
- Se divergir, a resposta é um erro de conflito e nada é criado.
Essa é a proteção contra o disparo não intencional. Ela existe justamente porque não há rascunho: se a sua audiência cresceu desde a última vez que você a consultou, o pedido falha em vez de enviar para mais gente do que você esperava.
Canais disponíveis
A criação cobre os três canais que a tela também cobre: WhatsApp, e-mail e web widget.
Descobrir templates e variáveis
Como quem chama pela API não vê a tela, existem dois endpoints de descoberta: um lista os templates disponíveis na conta e o outro, as variáveis que você pode usar. Use-os para montar o corpo da campanha sem depender de alguém conferir no painel.
Consultar o estado depois
Há um endpoint de leitura para acompanhar a campanha criada.
Observações
- A referência completa dos endpoints está na documentação pública da API. As mesmas capacidades também estão disponíveis como ferramenta de MCP.
- A campanha criada pela API nasce no mesmo estado que a criada pela tela, e é o mesmo agendador que envia. A API é a porta de entrada, não um caminho de envio diferente.
- Existem tetos de destinatários, por audiência bruta e por canal. Se o pedido passar do teto, você recebe erro de validação e nada é criado.