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.

Jun 26, 2026

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} — actualiza name, 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} — actualiza url, events, is_active, etc.
  • DELETE /v1/webhooks/{webhook} — elimina la suscripción.
  • POST /v1/webhooks/{webhook}/rotate-secret — regenera el signing_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 trae max_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_secret de cada webhook en un vault: solo se muestra al crearlo o rotarlo.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp