API v1 · Produção

Integre a operação de voz aos seus sistemas.

Gerencie agentes e números, consulte chamadas, transcrições, análises e auditorias de qualidade. Use webhooks assinados para receber resultados sem precisar consultar a API continuamente.

Começar agora Baixar especificação OpenAPI

Base URLhttps://api.voxiomni.com/api/v1

Escopo desta versão

A v1 não inicia chamadas ativas, não envia variáveis ou metadados para chamadas e não configura roteamento externo de números.

Fundamentos

Autenticação

Crie a chave em Configurações → Desenvolvimento. Envie-a no header Authorization. A chave é exibida somente uma vez e pertence exclusivamente ao workspace em que foi criada.

Permissões granulares

Cada chave possui apenas os escopos selecionados. Use chaves diferentes para integrações diferentes e revogue uma credencial sem afetar as demais.

agents:readConsultar agentes
agents:writeCriar e editar rascunhos
agents:publishPublicar agentes
phone_numbers:readConsultar números
phone_numbers:writeComprar e cancelar números
calls:readConsultar chamadas
recordings:readAcessar gravações
quality:readConsultar auditorias

cURL

curl https://api.voxiomni.com/api/v1/agents \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Fundamentos

Respostas e erros

As respostas usam JSON em camelCase. Erros possuem código estável e uma mensagem legível.

Exemplo de erro

{
  "code": "forbidden",
  "message": "The API key does not have the required scope: calls:read."
}

400Dados inválidos

401Chave ausente ou inválida

403Escopo insuficiente

404Recurso não encontrado

409Conflito de estado

500Erro interno

Recursos

Agentes

Consulte agentes, crie rascunhos, altere configurações e publique quando estiver pronto. Associar números é feito pelo campo phoneNumberIds do agente.

GET/agents

Lista os agentes do workspace.

agents:read

GET/agents/{agentId}

Consulta um agente.

agents:read

POST/agents

Cria um agente em rascunho.

agents:write

PUT/agents/{agentId}

Atualiza o rascunho e suas associações com números.

agents:write

POST/agents/{agentId}/publish

Publica a versão atual.

agents:publish

Recursos

Números telefônicos

Consulte, compre e cancele números do workspace. O roteamento personalizado não faz parte desta versão; a associação operacional com um agente usa agentId na compra ou phoneNumberIds no agente.

GET/phone-numbers

Lista os números do workspace.

phone_numbers:read

GET/phone-numbers/available

Busca números disponíveis para compra.

phone_numbers:write

POST/phone-numbers

Compra um número, com associação opcional a um agente.

phone_numbers:write

GET/phone-numbers/{phoneNumberId}

Consulta um número.

phone_numbers:read

DELETE/phone-numbers/{phoneNumberId}

Cancela um número desassociado.

phone_numbers:write

Recursos

Chamadas

Consulte até 90 dias por requisição. Sem datas, a API retorna os últimos 30 dias. Use page e pageSize para paginação.

GET/calls

Lista chamadas. Filtros: from, to, customerPhone, agent e outcome.

calls:read

GET/calls/{callId}

Retorna status, transcrição, resumo e análise.

calls:read

GET/calls/{callId}/recording

Transmite a gravação quando ela estiver disponível e dentro da retenção.

recordings:read

Listar chamadas processadas

curl "https://api.voxiomni.com/api/v1/calls?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z&pageSize=50" \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Recursos

Qualidade

Consulte as auditorias selecionadas pela configuração de qualidade do agente, incluindo score, critérios, evidências e revisão humana.

GET/quality-audits

Lista auditorias. Filtros: from, to, agentId e reviewStatus.

quality:read

GET/quality-audits/{callId}

Consulta a auditoria, suas evidências e a transcrição associada.

quality:read

Webhooks

Um endpoint, vários eventos

Cadastre uma URL HTTPS no APP e selecione quais eventos ela recebe. O campo type identifica o evento; o campo id é único e deve ser usado para deduplicação.

Envelope de evento

{
  "id": "evt_01K8...",
  "type": "call.processed",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-11T18:32:14Z",
  "tenantId": "tenant_...",
  "data": {
    "id": "call_...",
    "status": "completed",
    "summary": "Cliente confirmou o acordo."
  }
}

Webhooks

Validar a assinatura

Calcule HMAC-SHA256 sobre {timestamp}.{corpo_bruto} usando o segredo exibido ao criar o endpoint. Compare o resultado com o header Voxiomni-Signature.

Voxiomni-Event-IdID para deduplicação

Voxiomni-TimestampUnix timestamp da tentativa

Voxiomni-Signaturev1=<hex>

Node.js

import crypto from 'node:crypto'

const signed = `${timestamp}.${rawBody}`
const expected = crypto
  .createHmac('sha256', process.env.VOXIOMNI_WEBHOOK_SECRET)
  .update(signed)
  .digest('hex')

const received = signature.replace('v1=', '')
const valid = crypto.timingSafeEqual(
  Buffer.from(expected, 'hex'),
  Buffer.from(received, 'hex')
)

Webhooks

Eventos disponíveis

call.ended

A ligação terminou. Transcrição e análise ainda podem estar em processamento.

call.processed

Todo o processamento pós-chamada terminou. Use este evento para consumir o resultado final.

call.failed

A ligação terminou com falha.

quality.completed

A auditoria automática terminou.

quality.failed

A auditoria não pôde ser concluída.

quality.reviewed

A revisão humana da auditoria foi concluída.

Webhooks

Entrega e novas tentativas

A entrega é at-least-once: em situações excepcionais, o mesmo evento pode chegar mais de uma vez. Responda rapidamente com qualquer status 2xx e processe de forma assíncrona.

Imediata+1 min+5 min+30 min+2 h+12 h

Respostas 408, 409, 425, 429, erros 5xx e falhas de rede são tentadas novamente. As entregas permanecem visíveis no APP por 30 dias e podem ser reenviadas manualmente.