Gerenciar campanhas via API (criar, listar, detalhar, cancelar)
Automatize suas transmissões com a API REST do Omnifox: crie, liste, consulte o detalhe com estatísticas e cancele campanhas a partir dos seus próprios sistemas.
Para que serve
A API REST do Omnifox permite operar as Transmissões a partir do seu CRM, ERP ou qualquer integração própria, sem entrar no painel. Todos os recursos ficam sob /api/v1/ e são autenticados com um token Bearer fixado a um workspace.
Requisitos
- Um token de API do workspace (gere em Configurações → Chaves API).
- Plano com acesso à API REST (a partir do Crece). As Transmissões em si estão em todos os planos, com limites mensais.
- Criar e cancelar campanhas exige o papel administrador ou proprietário; um agente só pode listar e visualizar.
Envie sempre os cabeçalhos Authorization: Bearer SEU_TOKEN e Accept: application/json. A resposta usa o envelope { "success", "data", "message" }.
1. Criar uma campanha
POST /api/v1/broadcasts
{
"channel_id": 12,
"name": "Promo de junho",
"type": "whatsapp_template",
"whatsapp_template_id": 84,
"segment_filters": { "group_ids": [3, 7] },
"scheduled_at": "2026-06-30T15:00:00Z"
}
typeaceitawhatsapp_template,smsouemail.- Para
whatsapp_templateo campowhatsapp_template_idé obrigatório; parasms/emailenviemessage_content. - Omita
scheduled_ate passe"send_now": truepara enviar de imediato. - Responde 201 com a campanha criada.
2. Listar campanhas
GET /api/v1/broadcasts?status=sending&channel_id=12&sort=created_at
Filtros disponíveis: status, channel_id, type. Ordene por created_at ou scheduled_at.
3. Ver o detalhe com estatísticas
GET /api/v1/broadcasts/{id}
Retorna a campanha com seu canal e modelo, além de um objeto stats com os contadores sent, delivered, read, replied, failed, pending.
4. Cancelar uma campanha
POST /api/v1/broadcasts/{id}/cancel
Só é possível cancelar uma campanha em status draft, scheduled ou sending. Os destinatários pendentes passam a falha com o motivo "Broadcast cancelled". Se a campanha já terminou, retorna 422.
Verificação
Após criar, chame o endpoint de detalhe e confirme que o status evolui de scheduled/sending para sent. Um 402 indica que você atingiu um dos limites de transmissões do seu plano (por exemplo, o limite mensal de destinatários).
Dicas
- O token está atrelado a um workspace: você não precisa (nem pode) operar sobre outro
workspace_id. - Reutilize seus grupos e etiquetas em
segment_filterspara não recalcular públicos.
Artigos relacionados
Artigos relacionados
-
Como criar uma campanha de difusão (broadcast)
Crie, segmente e agende uma difusão para seus contatos passo a passo no Omnifox.
-
Boas práticas para difundir sem ser bloqueado
Reduza denúncias de spam e bloqueios seguindo estas regras ao enviar difusões pelo WhatsApp e outros canais.
-
O que é uma campanha e seus status (rascunho, agendada, enviando, concluída)
O que é uma campanha de transmissão na Omnifox e o que significam seus status: rascunho, agendada, enviando e concluída.
-
Canais suportados para transmissões (WhatsApp, E-mail, SMS, Telegram)
Conheça quais canais voce pode usar para enviar transmissões no Omnifox e o que cada um exige.
-
Segmentar a audiência: todos, grupos, tags (E/OU) e campo personalizado
Aprenda a escolher com precisão quem recebe sua transmissão combinando grupos, tags com lógica E/OU e campos personalizados.