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.

Jun 26, 2026

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"
}
  • type aceita whatsapp_template, sms ou email.
  • Para whatsapp_template o campo whatsapp_template_id é obrigatório; para sms/email envie message_content.
  • Omita scheduled_at e passe "send_now": true para 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_filters para não recalcular públicos.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp