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.
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"
}
typeadmitewhatsapp_template,smsoemail.- Para
whatsapp_templateel campowhatsapp_template_ides obligatorio; parasms/emailenvíamessage_content. - Omite
scheduled_aty manda"send_now": truepara 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_filterspara no recalcular audiencias.
Artículos relacionados
Artículos relacionados
-
Cómo crear una campaña de difusión (broadcast)
Crea, segmenta y programa una difusión a tus contactos paso a paso desde Omnifox.
-
Buenas prácticas para difundir sin que te bloqueen
Reduce reportes de spam y bloqueos siguiendo estas reglas al enviar difusiones por WhatsApp y otros canales.
-
Qué es una campaña y sus estados (draft, programada, enviando, completada)
Qué es una campaña de difusión en Omnifox y qué significan sus estados: borrador, programada, enviando y completada.
-
Canales soportados para broadcasts (WhatsApp, Email, SMS, Telegram)
Conoce qué canales puedes usar para enviar difusiones masivas en Omnifox y qué requisitos tiene cada uno.
-
Segmentar la audiencia: todos, grupos, tags (AND/OR) y campo personalizado
Aprende a elegir con precisión a quién llega tu difusión combinando grupos, etiquetas con lógica AND/OR y campos personalizados.