Referencia de endpoints API: equipos, webhooks, miembros y agentes/horarios
Endpoints de la API REST v1 de Omnifox para gestionar equipos, suscripciones a webhooks, miembros y la disponibilidad de agentes.
Mira este paso en el video · La documentación de la API
Introducción
La API REST v1 de Omnifox te permite automatizar equipos, webhooks salientes y agentes desde tus propios sistemas. Base de la API: https://omnifox.io/api/v1. Todas las llamadas usan Bearer token (token personal Sanctum) que generas en Configuración → API Keys (/api-keys). En la lista lo identificas por un prefijo visible omf_…, pero el valor que envías en el header tiene el formato 123_aBc…. Cada token está scopeado a un solo workspace: no puedes operar sobre otro workspace con el mismo token.
Authorization: Bearer 123_aBc...tuTokenCompleto
Content-Type: application/json
Equipos (Teams)
GET /v1/teams— lista equipos. Filtro opcional?workspace_id=.POST /v1/teams— crea un equipo. Body:workspace_id(req),name(req),description,assignment_strategy.GET /v1/teams/{team}— devuelve el equipo con sus miembros.PUT /v1/teams/{team}— actualizaname,description,assignment_strategy.DELETE /v1/teams/{team}— elimina el equipo.
Miembros de equipo (Members)
POST /v1/teams/{team}/members— agrega un usuario. Body:user_id(req).DELETE /v1/teams/{team}/members/{user}— quita un usuario del equipo.GET /v1/teams/{team}/members/{user}— chequea una membresía puntual; devuelve{ is_member, role }.GET /v1/users/{user}/teams— equipos a los que pertenece un agente (scopeado al workspace).
Webhooks salientes
GET /v1/webhooks— lista las suscripciones con estadísticas de entrega.POST /v1/webhooks— crea una suscripción. Body:name(req),url(req),events(req, array),headers,retry_count,timeout_seconds. Al crearla se genera un secreto HMAC y se envía un ping de prueba a la URL.GET /v1/webhooks/{webhook}— detalle con los logs de entrega recientes.PUT /v1/webhooks/{webhook}— actualizaurl,events,is_active, etc.DELETE /v1/webhooks/{webhook}— elimina la suscripción.POST /v1/webhooks/{webhook}/rotate-secret— regenera elsigning_secret.
Eventos disponibles: contact.created/updated/deleted, conversation.created/closed/resolved/pending/assigned, message.received/sent/delivered/read/failed, note.created, call.started/ended, agent.assigned/status_changed, tag.added/removed, workflow.completed, broadcast.completed.
Cada entrega lleva las cabeceras X-Omnifox-Signature (HMAC-SHA256 del cuerpo) y X-Omnifox-Timestamp. Verifícalas en tu endpoint con el signing_secret.
Agentes y disponibilidad (horarios)
GET /v1/agents— lista agentes con su estado de disponibilidad y asignaciones de workspace. Filtros:?workspace_id=,?status=,?team_id=.GET /v1/agents/{agent}— detalle con workspaces, equipos y estadísticas (assigned_open_conversations,total_conversations_handled). Cada asignación traemax_concurrent_conversations.PUT /v1/agents/{agent}/status— cambia la disponibilidad. Body:workspace_id(req),status(req:available,busy,away,offline). Difunde el cambio en tiempo real.
Los horarios de turno (on-shift) que deciden a quién auto-asignar se configuran en el workspace; la API expone el estado de disponibilidad resultante vía
status.
Verificación
Prueba tu token con GET /v1/teams. Un 200 con JSON confirma que el Bearer es válido y está scopeado al workspace correcto.
Tips
- La API REST está disponible desde el plan Crece y el límite de peticiones depende de tu plan: Crece 1.200/min, Escala 2.400/min, Exclusivo sin límite. Ante
429, reintenta con backoff. - Guarda el
signing_secretde cada webhook en un vault: solo se muestra al crearlo o rotarlo.
Artículos relacionados
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.