Referência de endpoints da API: equipes, webhooks, membros e agentes/horários

Endpoints da API REST v1 do Omnifox para gerenciar equipes, assinaturas de webhooks, membros e a disponibilidade dos agentes.

Jun 26, 2026

Veja este passo no vídeo · A documentação da API

Introdução

A API REST v1 do Omnifox permite automatizar equipes, webhooks de saída e agentes a partir dos seus próprios sistemas. Base da API: https://omnifox.io/api/v1. Toda chamada usa Bearer token (token pessoal Sanctum) gerado em Configurações → Chaves API (/api-keys). Na lista você o reconhece por um prefixo visível omf_…, mas o valor que você envia no header tem o formato 123_aBc…. Cada token tem escopo de um único workspace: você não pode operar em outro workspace com o mesmo token.

Authorization: Bearer 123_aBc...seuTokenCompleto
Content-Type: application/json

Equipes (Teams)

  • GET /v1/teams — lista equipes. Filtro opcional ?workspace_id=.
  • POST /v1/teams — cria uma equipe. Body: workspace_id (obr), name (obr), description, assignment_strategy.
  • GET /v1/teams/{team} — retorna a equipe com seus membros.
  • PUT /v1/teams/{team} — atualiza name, description, assignment_strategy.
  • DELETE /v1/teams/{team} — exclui a equipe.

Membros da equipe

  • POST /v1/teams/{team}/members — adiciona um usuário. Body: user_id (obr).
  • DELETE /v1/teams/{team}/members/{user} — remove um usuário da equipe.
  • GET /v1/teams/{team}/members/{user} — verifica uma associação específica; retorna { is_member, role }.
  • GET /v1/users/{user}/teams — equipes às quais um agente pertence (escopo do workspace).

Webhooks de saída

  • GET /v1/webhooks — lista as assinaturas com estatísticas de entrega.
  • POST /v1/webhooks — cria uma assinatura. Body: name (obr), url (obr), events (obr, array), headers, retry_count, timeout_seconds. Ao criar, um segredo HMAC é gerado e um ping de teste é enviado à URL.
  • GET /v1/webhooks/{webhook} — detalhe com os logs de entrega recentes.
  • PUT /v1/webhooks/{webhook} — atualiza url, events, is_active, etc.
  • DELETE /v1/webhooks/{webhook} — exclui a assinatura.
  • POST /v1/webhooks/{webhook}/rotate-secret — regenera o signing_secret.

Eventos disponíveis: 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 leva os cabeçalhos X-Omnifox-Signature (HMAC-SHA256 do corpo) e X-Omnifox-Timestamp. Verifique-os no seu endpoint com o signing_secret.

Agentes e disponibilidade (horários)

  • GET /v1/agents — lista agentes com seu status de disponibilidade e atribuições de workspace. Filtros: ?workspace_id=, ?status=, ?team_id=.
  • GET /v1/agents/{agent} — detalhe com workspaces, equipes e estatísticas (assigned_open_conversations, total_conversations_handled). Cada atribuição traz max_concurrent_conversations.
  • PUT /v1/agents/{agent}/status — altera a disponibilidade. Body: workspace_id (obr), status (obr: available, busy, away, offline). Transmite a mudança em tempo real.

Os horários de turno (on-shift) que decidem quem recebe a atribuição automática são configurados por workspace; a API expõe o status de disponibilidade resultante via status.

Verificação

Teste seu token com GET /v1/teams. Um 200 com JSON confirma que o Bearer é válido e tem escopo do workspace correto.

Dicas

  • A API REST está disponível a partir do plano Crece e o limite de requisições depende do seu plano: Crece 1.200/min, Escala 2.400/min, Exclusivo sem limite. Em 429, repita com backoff.
  • Guarde o signing_secret de cada webhook em um cofre: ele só é exibido ao criar ou rotacionar.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp