API pública

Documentação da API Call Trace

Envie gravações de chamadas do seu sistema, receba uma resposta 202 imediata e obtenha a transcrição e avaliação finais por webhooks.

Crie uma chave API

Abra Admin > Integrações e crie uma chave com o escopo analysis:write.

Envie uma URL de arquivo

Envie um fileUrl HTTPS para POST /api/v1/analyses. A API responde com 202 Accepted.

Receba o resultado

Inscreva-se em analysis.completed e analysis.failed para obter a avaliação final.

Verifique o secret

Compare X-CallTrace-Secret com o webhook secret salvo ao criar o endpoint.

Chaves API

Crie um token no painel admin

Apenas administradores podem criar chaves API de integração. As chaves têm escopos, podem expirar, ser revogadas e são independentes das sessões de funcionários.

01
Abra Integrações
Entre como administrador e abra Admin > Integrações > API Keys.
02
Nomeie a chave
Use um nome que identifique o sistema externo, ambiente e responsável.
03
Escolha os escopos
Selecione apenas as permissões necessárias. A maioria das integrações de upload precisa de analysis:write e analysis:read.
04
Defina a validade
Escolha uma data de expiração para acesso temporário ou deixe permanente para integrações de serviço de longa duração.
05
Copie uma vez
O token ct_live_ completo é exibido apenas uma vez. Após fechar o painel, apenas o prefixo permanece visível.
ct_live_••••••••

Formato do token

ct_live_8Lk3...full-secret-value

Armazene o token completo no gerenciador de segredos do seu sistema externo. O Call Trace armazena apenas um hash e mostra só o prefixo após a criação.

Autenticação

Use uma chave de integração com escopos

As chaves API de integração são separadas das sessões de funcionários. Envie a chave no cabeçalho Authorization e conceda apenas os escopos que seu sistema precisa.

Cabeçalho

Authorization: Bearer ct_live_...
Content-Type: application/json

Escopos

analysis:write cria análises.

analysis:read lê status e resultados.

webhooks:write gerencia configurações de webhooks.

Permissões

O que cada escopo permite

Os escopos são cumulativos. Comece com o menor conjunto que suporta a integração e adicione mais apenas quando um endpoint específico exigir.

Escopo

Uso

Descrição

analysis:write

Criar novas análises

Obrigatório para POST /api/v1/analyses. Permite que o sistema externo envie um fileUrl e enfileire a análise.

analysis:read

Ler status e resultado da análise

Obrigatório para GET /api/v1/analyses e GET /api/v1/analyses/{analysisId}. Use para polling e reconciliação.

calls:read

Ler dados no nível da chamada

Permite acesso a metadados de chamadas expostos por endpoints seguros para integração. Não conceda se a integração apenas envia arquivos.

storage:write

Gravar arquivos de origem

Reservado para integrações que precisam de fluxos de upload direto ao storage. Integrações fileUrl geralmente não precisam.

webhooks:read

Ler configuração e histórico de webhooks

Permite listar endpoints de webhook e tentativas de entrega para suporte ou monitoramento.

webhooks:write

Gerenciar webhooks

Permite criar ou atualizar endpoints de webhook. Mantenha em chaves admin/serviço, não em chaves comuns de envio de análises.

Mínimo recomendado

Para o fluxo padrão, crie um token com analysis:write e analysis:read. Webhooks são configurados por um admin na UI, então o remetente externo geralmente não precisa de webhooks:write.

Validade do token

Expiração, acesso permanente e rotação

Cada chave API tem sua própria validade. Um token pode ser permanente, expirar automaticamente ou ser revogado manualmente.

Token permanente

expiresAt está vazio. O token permanece ativo até um admin revogá-lo. Use apenas para integrações backend-to-backend confiáveis com processo de rotação.

Token com expiração

expiresAt está definido. Após essa data a API retorna 401 e novas requisições não são aceitas. Use para testes, contratados ou acesso temporário.

Token revogado

revokedAt é definido imediatamente quando um admin revoga a chave. A revogação é instantânea e irreversível; crie uma nova chave.

Rotação

Crie uma nova chave, implante no sistema externo, confirme que last used foi atualizado e então revogue a chave antiga. Isso evita downtime.

Referência da API

Criar uma análise

A requisição armazena o arquivo de origem e inicia o processamento em background. Seu cliente não deve esperar a transcrição ou avaliação terminar nesta requisição.

Criar análise

Retorna 202 Accepted e enfileira o processamento.

POST/api/v1/analyses

Requisição

POST /api/v1/analyses
Authorization: Bearer ct_live_...
Content-Type: application/json

{
  "fileUrl": "https://example.com/calls/call-123.mp3",
  "agentId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "queueId": "7a7bf5cc-5e34-4f4g-b98f-96g3g9433ed2",
  "externalId": "crm-call-123",
  "idempotencyKey": "crm-call-123",
  "metadata": {
    "customerId": "cust_42",
    "source": "crm"
  }
}

Resposta

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "queued",
  "externalId": "crm-call-123"
}

Campo

Tipo

Obrigatoriedade

Descrição

fileUrl

string

Obrigatório

URL HTTPS do arquivo de áudio a analisar. Tamanho máximo: 20 MB.

fileName

string

Opcional

Nome exibido no Call Trace. Se omitido, usa o último segmento do caminho de fileUrl.

agentId

uuid

Obrigatório

Agente associado à análise. Deve existir na sua empresa.

queueId

uuid

Obrigatório

Fila com o script usado na avaliação. Deve ter uma versão ativa do script.

language

string

Opcional

Idioma da transcrição. Padrão auto quando omitido.

externalId

string

Opcional

Seu identificador de CRM, helpdesk ou telefonia.

idempotencyKey

string

Opcional

Deduplica tentativas do seu sistema.

metadata

object

Opcional

Pequeno objeto JSON retornado em payloads de status e webhook.

Requisitos de URL de arquivo

fileUrl deve usar HTTPS. Privados, localhost e faixas de IP internas são rejeitados, incluindo redirecionamentos para redes privadas. Tamanho máximo do arquivo: 20 MB. Os arquivos são baixados com timeouts e verificação de content-type antes do processamento.

Referência da API

Ler status e resultados

Use este endpoint quando seu sistema precisar reconciliar estado ou recuperar após entregas de webhook perdidas.

Obter análise

Retorna o status mais recente do job e os campos de resultado disponíveis.

GET/api/v1/analyses/{analysisId}

{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "completed",
  "externalId": "crm-call-123",
  "call": {
    "durationSeconds": 184,
    "agentId": "agent-uuid",
    "queueId": "queue-uuid"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 },
      { "name": "Need discovery", "score": 18, "maxScore": 20 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}

queued

A requisição foi aceita e aguarda processamento.

processing

O arquivo está sendo baixado, transcrito e avaliado.

completed

A avaliação, transcrição e resumo da chamada estão disponíveis.

failed

O processamento falhou após tentativas. Detalhes são retornados em error.

Referência da API

Listar análises

Pesquise por status, externalId, agent, queue ou intervalo de datas. Use para reconciliação back-office e ferramentas de suporte.

Listar análises

Retorna análises paginadas da empresa de integração.

GET/api/v1/analyses

GET /api/v1/analyses?status=completed&externalId=crm-call-123
Authorization: Bearer ct_live_...

Webhooks

Payload de webhook

Configure endpoints de webhook em Admin > Integrações. Os payloads incluem as informações necessárias para armazenar o resultado da avaliação no seu sistema.

analysis.createdanalysis.completedanalysis.failed

{
  "deliveryId": "whd_01jz8n0f8ck2bk0smq7h2x1t0r",
  "event": "analysis.completed",
  "occurredAt": "2026-06-19T12:00:00.000Z",
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "externalId": "crm-call-123",
  "call": {
    "status": "completed",
    "durationSeconds": 184,
    "recordingUrl": "https://storage.example.com/audio/call-123.mp3"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}

O texto do script não é incluído por padrão. Use deliveryId para deduplicação e analysisId mais event ao armazenar transições de estado.

Webhooks

Entrega e tentativas

O Call Trace armazena cada tentativa de entrega e repete entregas falhas para que resultados não se percam em timeout ou indisponibilidade temporária do cliente.

Sucesso

Qualquer resposta 2xx marca a entrega como concluída.

Política de tentativas

Tentativa inicial mais 3 repetições com backoff, por exemplo 10 segundos, 1 minuto e 5 minutos.

Histórico

Cada tentativa armazena status, código de resposta, mensagem de erro, timestamps e snapshot do payload.

Webhooks

Webhook secret

Cada webhook endpoint recebe um secret. O Call Trace o envia em cada entrega para que você rejeite solicitações de fontes desconhecidas.

Por que verificar o secret

A URL do webhook é acessível pela internet. Compare o cabeçalho X-CallTrace-Secret com o secret salvo ao criar o endpoint. Se não coincidir, retorne 401 e ignore o payload.

O que chega em cada entrega

POST /your/webhook-handler

X-CallTrace-Secret: whsec_8Lk3...your-endpoint-secret

X-CallTrace-Delivery: whd_01jz8n0f8ck2bk0smq7h2x1t0r

X-CallTrace-Event: analysis.completed

X-CallTrace-Timestamp: 2026-06-19T12:00:00.000Z

{ "event": "analysis.completed", "analysisId": "6f6af4bb-..." }

X-CallTrace-Secret

O secret do endpoint. Compare este valor com CALL_TRACE_WEBHOOK_SECRET no seu servidor.

X-CallTrace-Delivery

ID único da entrega. Use-o para ignorar retries duplicados do mesmo evento.

X-CallTrace-Event

Tipo de evento, por exemplo analysis.completed.

X-CallTrace-Timestamp

Quando o Call Trace enviou a solicitação. Útil para logs e suporte.

Como verificar

Leia X-CallTrace-Secret dos cabeçalhos da solicitação e compare com o secret exibido uma vez em Admin > Integrações ao criar o webhook. Armazene o secret em uma variável de ambiente e rejeite divergências antes de processar o JSON.

Exemplo em Node.js

const secret = request.headers.get("x-calltrace-secret");

if (secret !== process.env.CALL_TRACE_WEBHOOK_SECRET) {
  return new Response("Unauthorized", { status: 401 });
}

const payload = await request.json();

Exemplos

Criar uma análise na sua linguagem

Todos os exemplos usam o mesmo endpoint estável e esperam a chave API em CALL_TRACE_API_KEY.

const response = await fetch("https://your-domain.com/api/v1/analyses", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CALL_TRACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    fileUrl: "https://example.com/calls/call-123.mp3",
    fileName: "call-123.mp3",
    language: "auto",
    externalId: "crm-call-123",
    idempotencyKey: "crm-call-123"
  })
});

const analysis = await response.json();
console.log(analysis.analysisId);

Erros

Tratamento de erros

Use idempotency keys para tentativas seguras. Erros de validação são retornados de forma síncrona. Erros de processamento são retornados pelo endpoint de status e webhooks analysis.failed.

400

JSON inválido, fileUrl ausente, content type não suportado ou metadata inválida.

401

Chave API ausente, expirada, revogada ou malformada.

403

A chave API não inclui o escopo necessário.

409

A mesma idempotency key já foi usada para outro payload.

422

A URL do arquivo está bloqueada, privada, não é HTTPS, é grande demais ou inacessível.

500

Erro temporário do servidor. Tente novamente com a mesma idempotency key.

Documentação da API Call Trace

Crie uma chave API

Envie uma URL de arquivo

Receba o resultado

Verifique o secret

Crie um token no painel admin

Abra Integrações

Nomeie a chave

Escolha os escopos

Defina a validade

Copie uma vez

Formato do token

Use uma chave de integração com escopos

Cabeçalho

Escopos

O que cada escopo permite

Expiração, acesso permanente e rotação

Token permanente

Token com expiração

Token revogado

Rotação

Criar uma análise

Criar análise

Ler status e resultados

Obter análise

Listar análises

Listar análises

Payload de webhook

Entrega e tentativas

Sucesso

Política de tentativas

Histórico

Webhook secret

Por que verificar o secret

Criar uma análise na sua linguagem

Tratamento de erros