FalaAI API — Manual de uso, campos e fluxos

Visao geral

A FalaAI API e um conjunto de APIs independentes. Voce nao precisa transcrever com a FalaAI para diagnosticar ou auditar: se voce ja tem o texto, envie direto para a analise (BYOT).

• Chave: todas as rotas exigem Authorization: Bearer fai_<sua_chave>, exceto GET/HEAD /v1/health e GET /api/version.
• Zero-storage (LGPD): audio/texto/resultado sao processados em memoria e descartados.
• Idiomas: transcricao em 31 idiomas; diagnostico em 21 locales; auditoria e relatorio HTML em 3 (pt/en/es).

Autenticacao

Para que serve: como provar quem voce e em cada chamada.

• Chave: toda rota exige o header Authorization: Bearer fai_<sua_chave> — exceto GET/HEAD /v1/health e GET /api/version (publicas, sem chave).
• Como obter: crie a conta e gere a API Key no Dashboard. A chave aparece uma unica vez (show-once) — guarde-a com seguranca.
• Escopos: cada chave tem escopos — transcribe, diagnostic, auditoria, whatsapp, alerts, billing, invoices (ou * para todos). Rota sem o escopo exigido → 403 insufficient_scope.
• JWT: alem da chave fai_, a API aceita JWT de sessao nas mesmas rotas.

Erros de autenticacao

Campos obrigatorios — resumo rapido

Se voce so quer fazer funcionar, estes sao os campos que a API exige em cada endpoint:

GET /v1/health publico

Para que serve: apenas dizer se o servidor esta de pe e qual a versao/uptime/estado do banco. Nao analisa nada.

flowchart LR
  A[Monitor / uptime / curl] -->|GET /v1/health| B{{FalaAI API}}
  B -->|200| C[status, version, uptime, database]
  A2[Checagem leve] -->|HEAD /v1/health| B
  B -->|200 sem corpo| D[apenas o codigo HTTP]
  classDef pub fill:#dcfce7,stroke:#16a34a,color:#14532d
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  class A,A2,C,D pub
  class B api
  

Campos

Nenhum.

Requisição (exemplo cURL)

carregando...

Resposta — campos

HEAD /v1/health = mesmo 200 sem corpo.

Exemplo de resposta (JSON)

carregando...

Fluxos possiveis

• Uptime/monitor (a cada 1 min) com alerta se != 200.
• Health check de deploy (mais barato): HEAD.
• Ler a versao da API para log.

GET /api/version publico

Para que serve: identificar a versao do contrato em uso (fixar compatibilidade do seu cliente).

flowchart LR
  A[Seu cliente / CI] -->|GET /api/version| B{{FalaAI API}}
  B --> C[versao do contrato]
  C --> D[Fixar/validar compatibilidade]
  classDef pub fill:#dcfce7,stroke:#16a34a,color:#14532d
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  class A,C,D pub
  class B api
  

Campos

Nenhum.

Resposta

POST /v1/audio/transcriptions multipart/form-data

Para que serve: transformar audio em texto com separacao de quem falou (diarizacao), timestamps e eventos de audio.

Campos

Requisição (exemplo cURL)

carregando...

Resposta — campos

Exemplo de resposta (JSON)

carregando...

Fluxo

flowchart TD
  S([Voce tem o audio?]) -->|sim| U[Escolher o arquivo: mp3, mp4, m4a, wav, flac, ogg, opus, webm, aac... ate 1GB / 3h]
  U --> T[POST /v1/audio/transcriptions + file]
  T --> R[Resposta: text, dialog, audio_events, duration_seconds, usage]
  R --> D1[Usar em Diagnostic]
  R --> A1[Usar em Risk Audit]
  R --> DB[(Seu banco / CRM / BI)]
  S -->|nao, ja tenho texto| B[Pular: ir direto para Diagnostic ou Risk Audit]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class S,U,B in
  class T api
  class R,D1,A1,DB out
  

Fluxos possiveis

• Audio → transcricao → diagnostico (resumo, motivo, acao, topico, sentimento).
• Audio → transcricao → auditoria de risco (score + violacoes + relatorio).
• Audio → transcricao → (diagnostico + auditoria) na mesma conversa.
• Lote: repetir por arquivo em fila e consolidar por conta/equipe.

POST /v1/analyze/diagnostic application/json

Para que serve: diagnosticar a conversa — 5 analises em uma chamada.

Campos

Requisição (exemplo cURL)

carregando...

Resposta — campos

Exemplo de resposta (JSON)

carregando...

Fluxo

flowchart TD
  I{Como voce tem a conversa?} -->|transcricao simples| X[text = transcricao corrida + language]
  I -->|com quem falou| Y[dialog = falas com falante e tempos + language + duration_seconds]
  X --> P[POST /v1/analyze/diagnostic]
  Y --> P
  P --> R[summary, contact_reason, action_taken, topic, sentiment]
  R --> O1[Dashboard de qualidade / CX]
  R --> O2[CRM / ticket / ERP]
  R --> O3[BI / warehouse]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class I,X,Y in
  class P api
  class R,O1,O2,O3 out
  

Fluxos possiveis

• Ja tenho transcricao (Whisper/Deepgram/proprio) → so diagnosticar (BYOT).
• Audio → transcricao → diagnostico (pipeline completo).
• Diagnostico + auditoria na mesma conversa.
• Lote por conversa e agregacao por periodo/equipe (client_reference_id para rastrear).

POST /v1/analyze/riskAudit application/json

Para que serve: auditar risco/compliance (COPC CX, ISO 18295-1, LGPD): score, deteccoes/violacoes, evidencias e relatorio HTML auditavel.

Campos

Requisição (exemplo cURL)

carregando...

Resposta — campos (dentro de response)

Exemplo de resposta (JSON)

carregando...

Fluxo

flowchart TD
  A{Ja tenho o dialog?} -->|sim| P[POST /v1/analyze/riskAudit + dialog + duration_seconds + language + response_language]
  A -->|so audio| T[POST /v1/audio/transcriptions] --> P
  P --> R[risk score, detections, verdict, summary, usage]
  R --> V1[Relatorio HTML auditavel]
  R --> V2[Auditoria 100% das conversas]
  R --> V3[Evidencia para juridico / disputa]
  R --> V4[Plano de acao por equipe]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class A,T in
  class P api
  class R,V1,V2,V3,V4 out
  

Fluxos possiveis

• Auditoria pontual: uma conversa → score + violacoes + relatorio.
• Auditoria em lote (100%): todas as conversas do dia/semana → ranking por risco.
• Auditoria + diagnostico para contexto (motivo/acao) junto do risco.
• Reverificacao depois de treinamento (compara score antes/depois).

POST /v1/whatsapp/extractConversations multipart/form-data

Para que serve: extrair e segmentar conversas de um export do WhatsApp (.zip/.txt) para depois diagnosticar ou auditar.

Campos

Requisição (exemplo cURL, por variante)

Preview (gratis)

carregando...

Janela unica (extracao)

carregando...

Varias janelas (extracao)

carregando...

Resposta — campos

Exemplo de resposta (JSON, por variante)

Preview (gratis)

carregando...

Janela unica (extracao)

carregando...

Varias janelas (extracao)

carregando...

Fluxo (com as 3 variantes)

flowchart TD
  U[Export do WhatsApp: .zip ou .txt] --> V{Escolher a variante}
  V -->|preview gratis| P1[dry_run=true: devolve ROTULOS e previas - nao extrai conversa]
  V -->|janela unica| P2[start + end definem 1 janela]
  V -->|varias janelas| P3[windows = JSON com varias janelas]
  P2 --> C[conversations: dialog, participantes, mensagens, duracao]
  P3 --> C
  C --> J[Usar como transcricao JSON no Playground]
  C --> D[POST /v1/analyze/diagnostic]
  C --> A[POST /v1/analyze/riskAudit]
  P1 --> L[Conferir volume/rotulos antes de gastar creditos]
  L --> V
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef prev fill:#fef9c3,stroke:#ca8a04,color:#713f12
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class U,V in
  class P1,P2,P3 api
  class L prev
  class C,J,D,A out
  

Fluxos possiveis

• Conferir antes (gratis): rodar dry_run=true para ver quantas conversas/rotulos existem e a estimativa de creditos.
• Extrair a conversa inteira (start+end) → diagnosticar/auditar.
• Extrair varias janelas (windows) → diagnosticar/auditar em lote.
• Atendimento por WhatsApp → conversa extraida → auditoria de risco (compliance).

Fluxos combinados (arvore de decisao)

flowchart TD
  S([O que voce tem em maos?]) --> A{Audio?}
  A -->|sim| T[Transcricao] --> Q{O que quer saber?}
  A -->|nao, tenho texto| Q
  A -->|nao, tenho export do WhatsApp| W[Extract WhatsApp] --> Q
  Q -->|resumo/motivo/acao/sentimento| D[Diagnostic]
  Q -->|risco/compliance/relatorio| R[Risk Audit]
  Q -->|os dois| D2[Diagnostic + Risk Audit]
  D --> FIM([JSON tipado para o seu sistema])
  R --> FIM
  D2 --> FIM
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#dcfce7,stroke:#16a34a,color:#14532d
  class S,W in
  class T,D,R,D2 api
  class Q,FIM out
  

Receitas prontas

Webhooks de alertas

Para que serve: receber avisos de assinatura/cobranca/creditos em um endpoint HTTPS seu, sem precisar consultar a API.

Endpoints

Eventos (10)

• subscription.created · avulso.completed · subscription.upgraded · subscription.downgraded · subscription.canceled
• credits.low · credits.exhausted · subscription.renewed · subscription.expired · payment.failed

Payload (exemplo)

{
  "event": "credits.low",
  "data": { "balance_monthly": 12, "balance_avulso": 0, "total": 12, "plan": "starter_api", "plan_name": "Starter API - 90K" },
  "timestamp": 1725470000.123
}

Entrega e seguranca

• Assinatura: todo disparo traz o header FalaAI-Signature: t=<unix>,v0=<hmac_sha256(secret, "<t>.<corpo cru>")>. Valide recomputando o HMAC com o seu secret e compare com v0; rejeite se o t estiver fora da janela de tolerancia (anti-replay).
• Retry: retry_enabled=false = 1 tentativa; true = ate 5 (backoff 2^attempt: 1s, 2s, 4s, 8s). Timeout HTTP de 10s por disparo; resposta < 500 conta como entregue; apos 5 falhas consecutivas a inscricao e auto-desativada (active=false).

Erros

Limites e erros comuns

• 401: chave ausente/invalida (Authorization: Bearer fai_...).
• 402 / creditos: saldo insuficiente para a operacao.
• 413 / limite: arquivo acima de 1 GB (ou audio acima de 3 h).
• 422: campo obrigatorio ausente ou formato invalido (ex.: auditoria sem dialog; WhatsApp sem timezone/date_format).
• Publico sem chave: somente GET/HEAD /v1/health e GET /api/version.

Contrato completo: Swagger · openapi.json · Quickstart · Playground