Onvox AI Docs

Quick Start

Crie sua primeira análise de vendas em minutos seguindo este guia passo a passo.

Quick Start

Neste guia você vai criar sua primeira análise de ligação de vendas em 2 passos: buscar o ID do vendedor → enviar o áudio → receber a análise com score, transcrição e insights.

Você precisa de uma API Key válida antes de começar. Veja como obter uma em Autenticação.

Pré-requisitos

ItemValor
Base URLhttps://api.evolu-ai.com/api
Header obrigatórioX-API-Key: evai_your_key_here
Content-Typeapplication/json

Esta é a única Base URL que aceita autenticação por X-API-Key. Existe também uma rota /v1 usada internamente pelo painel web (sessão de navegador); não use /v1 com API Key, pois algumas operações lá exigem sessão e não funcionam só com a chave.

Passo 1: Buscar o ID do vendedor

A análise precisa do salespersonId para associar a ligação ao vendedor correto. Liste os vendedores da sua empresa; a API Key já identifica automaticamente a empresa correspondente:

curl -X GET 'https://api.evolu-ai.com/api/salespersons' \
  -H 'X-API-Key: evai_your_key_here'

Resposta:

[
  {
    "id": "user_abc123",
    "name": "João Pereira",
    "role": "salesperson",
    "supervisorName": "Ana Costa"
  },
  {
    "id": "user_def456",
    "name": "Ana Costa",
    "role": "supervisor",
    "supervisorName": null
  }
]

Copie o id do vendedor desejado (no exemplo acima, user_abc123 para João Pereira).

Passo 2: Criar a análise

Agora envie a ligação para análise. Use o link de áudio público abaixo para testar sem precisar de upload próprio:

Áudio de exemplo para testes: https://storage.evolu-ai.com/samples/demo-sales-call.mp3

Este arquivo é uma ligação de vendas fictícia de ~3 minutos, hospedada publicamente e aceita pela API para fins de demonstração.

O campo que recebe o áudio se chama audioKey. Apesar do nome, ele aceita uma URL HTTP/HTTPS direta (como no exemplo abaixo), uma Data URL em base64, ou uma chave de objeto do storage da Onvox AI. Veja todas as formas em Endpoints.

curl -X POST 'https://api.evolu-ai.com/api/analyses' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: evai_your_key_here' \
  -d '{
    "salespersonId": "user_abc123",
    "audioKey": "https://storage.evolu-ai.com/samples/demo-sales-call.mp3",
    "clientName": "Empresa Teste Ltda"
  }'

Resposta (pode levar 30–90 segundos):

{
  "id": "anal_xyz789",
  "score": 74,
  "summary": "O vendedor demonstrou boa escuta ativa e identificou necessidades claras do cliente. Houve dificuldade no fechamento, pois a proposta foi apresentada sem confirmação de BANT.",
  "stage": "Qualify",
  "salespersonName": "João Pereira",
  "clientName": "Empresa Teste Ltda",
  "audioDurationSeconds": 187,
  "createdAt": "2025-01-15T14:32:00Z"
}

Fluxo completo em código

JavaScript / Node.js

const API_KEY = 'evai_your_key_here';
const BASE_URL = 'https://api.evolu-ai.com/api';

async function primeiraAnalise() {
  // Passo 1: Listar vendedores (a API Key já identifica sua empresa)
  const usersRes = await fetch(`${BASE_URL}/salespersons`, {
    headers: { 'X-API-Key': API_KEY }
  });
  const vendedores = await usersRes.json();

  const vendedor = vendedores[0]; // pega o primeiro da lista
  console.log('Vendedor selecionado:', vendedor.name, '| ID:', vendedor.id);

  // Passo 2: Criar análise com áudio de exemplo
  const analysisRes = await fetch(`${BASE_URL}/analyses`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      salespersonId: vendedor.id,
      audioKey: 'https://storage.evolu-ai.com/samples/demo-sales-call.mp3',
      clientName: 'Empresa Teste Ltda'
    })
  });

  const analise = await analysisRes.json();

  console.log('=== Análise Criada ===');
  console.log('ID:', analise.id);
  console.log('Score:', analise.score, '/ 100');
  console.log('Etapa da venda:', analise.stage);
  console.log('Duração do áudio:', analise.audioDurationSeconds, 'segundos');
  console.log('Resumo:', analise.summary);

  return analise;
}

primeiraAnalise().catch(console.error);

Python

import requests

API_KEY = 'evai_your_key_here'
BASE_URL = 'https://api.evolu-ai.com/api'
headers = {'X-API-Key': API_KEY, 'Content-Type': 'application/json'}

# Passo 1: Listar vendedores (a API Key já identifica sua empresa)
vendedores = requests.get(f'{BASE_URL}/salespersons', headers=headers).json()
vendedor = vendedores[0]
print(f"Vendedor: {vendedor['name']} | ID: {vendedor['id']}")

# Passo 2: Criar análise
payload = {
    'salespersonId': vendedor['id'],
    'audioKey': 'https://storage.evolu-ai.com/samples/demo-sales-call.mp3',
    'clientName': 'Empresa Teste Ltda'
}

res = requests.post(f'{BASE_URL}/analyses', json=payload, headers=headers)
analise = res.json()

print(f"\n=== Análise Criada ===")
print(f"ID: {analise['id']}")
print(f"Score: {analise['score']}/100")
print(f"Etapa: {analise['stage']}")
print(f"Resumo: {analise['summary'][:200]}...")

Regras e limites importantes

Leia as regras abaixo antes de integrar em produção para evitar erros inesperados.

Sobre o áudio

RegraValor
Tamanho máximo (Data URL base64)10 MB
Tamanho máximo (download por URL)40 MB
Duração máximaSem limite fixo: o custo em créditos escala com a duração
Formatos aceitosmp3, mp4, wav, ogg, opus
URL deve ser públicaSim, a API faz o download diretamente
URL deve usar HTTPSRecomendado; http:// também é aceito
Extensão no caminho da URLO caminho precisa terminar em .mp3, .mp4, .wav, .ogg ou .opus (a query string não conta). Sem isso, o valor não é baixado como URL: é tratado como chave de storage e o áudio não é encontrado
Content-Type do servidor do áudioSe o servidor enviar esse header, ele precisa ser de áudio (audio/mpeg, audio/mp3, audio/mp4, audio/wav, audio/wave, audio/ogg, audio/opus). Outro valor, como application/octet-stream, devolve 400

Os dois limites de tamanho são diferentes: um arquivo de 25MB funciona por URL, mas falha com 400 se enviado em base64 (limite de 10MB). Prefira audioKey como URL direta para arquivos grandes.

Sobre os inputs

Pelo menos um dos dois campos abaixo é obrigatório por requisição. Se vierem os dois, vale o transcript e o áudio não é transcrito:

CampoQuando usar
audioKeyURL HTTP/HTTPS direta de um arquivo de áudio, Data URL em base64, ou chave de objeto no storage da Onvox AI
transcriptTranscrição em texto puro, quando o áudio já foi transcrito externamente

Rate limit

RecursoLimite
Criar análise (POST /api/analyses)15 requisições/min por empresa
Análises simultâneasNão há limite fixo, mas análises consomem créditos

Créditos: Cada análise consome créditos baseados na duração do áudio e tokens de IA processados. O saldo de créditos hoje só é consultável pelo painel web (sessão de usuário); se sua chave ficar sem crédito, a requisição de análise devolve 403 Forbidden.

Tempo de processamento

O tempo de resposta varia conforme a duração do áudio:

Duração do áudioTempo estimado
Até 5 minutos20–45 segundos
5–30 minutos45–120 segundos
30–120 minutos2–8 minutos

Próximos passos

Autenticação

Entenda API Keys, permissões e boas práticas de segurança

Endpoints

Referência completa de todos os endpoints disponíveis

Exemplos

Código completo em JavaScript, Python e cURL, e como receber webhooks

Erros

Códigos de erro, rate limit e estratégias de retry

Onvox AI API

Documentação oficial da API da Onvox AI para análise de conversas com inteligência artificial.

Autenticação

Como autenticar suas requisições à API da Onvox AI usando API Keys.

Nesta página

Quick StartPré-requisitosPasso 1: Buscar o ID do vendedorPasso 2: Criar a análiseFluxo completo em códigoJavaScript / Node.jsPythonRegras e limites importantesSobre o áudioSobre os inputsRate limitTempo de processamentoPróximos passos