Gestionar campañas vía API (crear, listar, detalle, cancelar)

Automatiza tus difusiones con la API REST de Omnifox: crea, lista, consulta el detalle con estadísticas y cancela campañas desde tu propio sistema.

Jun 26, 2026

Para qué sirve

La API REST de Omnifox te permite operar las Difusiones desde tu CRM, ERP o cualquier integración propia, sin entrar al panel. Todos los recursos viven bajo /api/v1/ y se autentican con un token Bearer que está fijado a un workspace.

Requisitos

  • Un token de API del workspace (genéralo en Configuración → API Keys).
  • Plan con acceso a la API REST (desde Crece). Las Difusiones en sí están en todos los planes, con cupos mensuales.
  • Para crear y cancelar campañas necesitas rol administrador o propietario; un agente solo puede listar y ver.

Incluye siempre las cabeceras Authorization: Bearer TU_TOKEN y Accept: application/json. La respuesta es un sobre { "success", "data", "message" }.

1. Crear una campaña

POST /api/v1/broadcasts
{
  "channel_id": 12,
  "name": "Promo junio",
  "type": "whatsapp_template",
  "whatsapp_template_id": 84,
  "segment_filters": { "group_ids": [3, 7] },
  "scheduled_at": "2026-06-30T15:00:00Z"
}
  • type admite whatsapp_template, sms o email.
  • Para whatsapp_template el campo whatsapp_template_id es obligatorio; para sms/email envía message_content.
  • Omite scheduled_at y manda "send_now": true para enviar de inmediato.
  • Responde 201 con la campaña creada.

2. Listar campañas

GET /api/v1/broadcasts?status=sending&channel_id=12&sort=created_at

Filtros disponibles: status, channel_id, type. Orden por created_at o scheduled_at.

3. Ver el detalle con estadísticas

GET /api/v1/broadcasts/{id}

Devuelve la campaña con su canal y plantilla, más un objeto stats con los contadores sent, delivered, read, replied, failed, pending.

4. Cancelar una campaña

POST /api/v1/broadcasts/{id}/cancel

Solo se puede cancelar una campaña en estado draft, scheduled o sending. Los destinatarios pendientes pasan a fallido con el motivo "Broadcast cancelled". Si la campaña ya terminó, responde 422.

Verificación

Tras crear, llama al endpoint de detalle y confirma que el estado evoluciona de scheduled/sending a sent. Si recibes 402, alcanzaste uno de los topes de difusiones de tu plan (por ejemplo, el tope mensual de destinatarios).

Tips

  • El token está atado a un workspace: no necesitas (ni puedes) operar sobre otro workspace_id.
  • Reutiliza tus grupos y etiquetas en segment_filters para no recalcular audiencias.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp