API de Voz Finn

Finn Voice API

O Finn API é a mesma superfície que o nosso painel usa. Crie agentes de voz, inicie campanhas, insira análises — todas programáticas.

Este guia leva você à sua primeira chamada ao vivo API em ~5 minutos.

Início rápido (3 passos)

1. Pegue uma tecla API

Dashboard → Configurações → Integrações → API Chaves → Gerar chave.

Terás dois níveis principais:

• fnn_test_* — caixa de areia. Sem faturamento, sem discagens reais. Utilização para o desenvolvimento.
• fnn_live_* — produção. Chamadas reais, dinheiro a sério.

Chaves são org-scoped e herdar limites de taxa do seu plano + quotas.

2. Definir variáveis de ambiente

export FINN_API_KEY=fnn_test_xxxxxxxxxxxxxxxxxxxx
export FINN_BASE_URL=https://stage-api.hirefinn.ai/v1

Para a produção, a conversão para:

export FINN_BASE_URL=https://api.hirefinn.ai/v1

3. Faça sua primeira chamada

Liste as suas barbatanas:

curl $FINN_BASE_URL/finns \
  -H "Authorization: Bearer $FINN_API_KEY"

Resposta esperada:

{
  "data": [
    {
      "id": "fn_abc123",
      "name": "MBBS Callflow",
      "voice_id": "voice_warm_indian_f",
      "language": "en-IN",
      "created_at": "2026-04-12T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "has_more": false
  }
}

Feito. Estás a falar com o API.

URL base

& Ambiente; URL Não, não, não Produção Estágio

Todos os parâmetros são versionados em /v1. Quebrando o navio muda sob um novo prefixo caminho (/v2, /v3); campos aditivos rolar para a versão atual.

Autenticação

Cada pedido precisa de uma chave API no cabeçalho Authorization:

Authorization: Bearer fnn_live_xxxxxxxxxxxxxxxxxxxx

Gestão de chaves

• ** Gerar** em Painel → Configurações → Integrações → API Chaves.
• Rotate — mesma tela. Chave antiga revogada imediatamente após confirmação.
• Revoke — instant. Todas as solicitações em voo usando a chave revogada falha com 401.
• Scope — chaves são org-scoped. Use chaves separadas por ambiente, por serviço.

Boas práticas

• Armazenar chaves em variáveis de ambiente ou um gerenciador secreto. Nunca se comprometa com a fonte.
• Utilizar fnn_test_* para IC e dev local. Credenciais de produção nunca devem ver um laptop desenvolvedor.
• Rodar trimestralmente mesmo sem um incidente.
• Auditoria que a chave criou que recurso através do campo created_by_key_id na maioria dos recursos.

Exemplos de códigos

Atingir o mesmo objectivo em 3 línguas.

cURL

curl https://api.hirefinn.ai/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria — Dental Reminders",
    "voice_id": "voice_warm_indian_f",
    "language": "en-IN",
    "system_prompt": "You are Aria, a friendly...",
    "welcome_message": "Hi, this is Aria from Smile Dental..."
  }'

Nó / TipoScript

import { Finn } from "@finn-voice/sdk";

const finn = new Finn({ apiKey: process.env.FINN_API_KEY });

const agent = await finn.finns.create({
  name: "Aria — Dental Reminders",
  voice_id: "voice_warm_indian_f",
  language: "en-IN",
  system_prompt: "You are Aria, a friendly...",
  welcome_message: "Hi, this is Aria from Smile Dental...",
});

console.log(agent.id);

Python

from finn_voice import Finn

finn = Finn(api_key=os.environ["FINN_API_KEY"])

agent = finn.finns.create(
    name="Aria — Dental Reminders",
    voice_id="voice_warm_indian_f",
    language="en-IN",
    system_prompt="You are Aria, a friendly...",
    welcome_message="Hi, this is Aria from Smile Dental...",
)

print(agent.id)

Formato de resposta

Cada resposta bem sucedida envolve carga útil em um envelope consistente.

Recurso único

{
  "data": {
    "id": "fn_abc123",
    "name": "MBBS Callflow",
    "created_at": "2026-04-12T10:30:00Z"
  }
}

Lista

{
  "data": [ /* array of resources */ ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 312,
    "has_more": true
  }
}

Horários

Todas as datas são ISO-8601 UTC (2026-05-22T14:30:00Z).

IDs

Os IDs de recursos são prefixados por tipo para grep-ability:

Prefixo Não, não, não fn_ Finn (agente vocal) O que é isso □ dep_ □ Implantação Chamada Número de telefone assinatura

Paginação

Os objectivos da lista aceitam:

?page=2&per_page=100

• page defaults to 1.
• per_page defaults to 50, max 200.
• A resposta inclui pagination.has_more — quando true, incremento page e re-fetch.

Paginação do cursor para os objectivos de alta cardinalidade (chamadas, transcrições):

?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMlQxMjowMDowMFoifQ&per_page=100

Cursor é opaco — passe-o de volta como-é para buscar a próxima página.

Filtrar e ordenar

A maioria dos endpoints da lista suporta:

?filter[status]=active&filter[call_type]=outbound&sort=-created_at

• filter[field]=value — correspondência exacta. Alguns campos aceitam arrays: filter[status]=active,paused.
• sort=field — ascendente. Prefixo com - para descer. Múltiplo separado por vírgulas: sort=-created_at,name.

Idempotência

Envie um cabeçalho Idempotency-Key único em POST solicitações que criam recursos. Finn deduplica pedidos repetidos dentro de 24 horas.

curl https://api.hirefinn.ai/v1/deployments \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Idempotency-Key: campaign-may-cohort-3-attempt-1" \
  -d '{ "finn_id": "fn_abc123", ... }'

Se você tentar novamente com a mesma chave, você obtém a resposta em cache da primeira chamada — nenhum recurso duplicado criado.

Erros

JSON envelope:

{
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "phone_number_id is required",
    "field": "phone_number_id",
    "request_id": "req_xy12abc"
  }
}

Incluir request_id em qualquer ticket de suporte — é como rastreamos sua chamada através de nossos logs.

Códigos de estatuto

Estado Quer dizer

Erro de validação – forma de carga incorreta

• 401 * API falta a chave / inválido * Não * □ 403 □ Âmbito de aplicação para diferentes níveis de org / plano O recurso não foi encontrado
• 409 * Conflito (nome duplicado, telefone já ligado) * Não * No

• Sim - respeito Retry-After Sim — backoff exponencial

Códigos de erro comuns

O código de quando Não, não, não Campo obrigatório ausente da carga útil O campo está presente, mas o valor é inválido O símbolo do portador está desaparecido • invalid_token • Token revogado ou malformado O Token não tem acesso a este recurso O limite do plano foi atingido Muitos pedidos por segundo O pedido foi rejeitado pelas regras de conformidade Não há créditos suficientes para lançar a implantação

Limites de taxa

O Plano RPS

Início 5 5.000 . Pró . . . Crescimento Empreendimento Negociado Negociado

Atingir o limite retorna 429 com cabeçalhos:

Retry-After: 12
X-RateLimit-Limit: 25
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716391823

Respeito Retry-After (segundos) ou recuar exponencialmente em 5xx.

Recursos num relance

Descrição do Endpoint

Finns, agentes de voz • Audiências • /v1/audiences • Listas de contactos Os números de telefone são: Empreendimentos Chamadas de chamadas individuais Vozes Vozes disponíveis Assinaturas de eventos Carteira

Webhooks

Inscreva-se nos eventos. Post'd para o seu URL com HMAC-SHA256 assinatura em X-Finn-Signature.

Registo

curl https://api.hirefinn.ai/v1/webhooks \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/finn-webhook",
    "events": ["call.completed", "deployment.completed"],
    "secret": "whsec_yourSecretHere"
  }'

Carga útil do evento

{
  "id": "evt_2H4abc",
  "type": "call.completed",
  "created_at": "2026-05-22T14:30:00Z",
  "data": {
    "call_id": "cal_xyz789",
    "deployment_id": "dep_xyz789",
    "duration_seconds": 142,
    "outcome": "qualified",
    "recording_url": "https://...",
    "transcript_url": "https://..."
  }
}

Verificação da assinatura (Node)

import crypto from "crypto";

function verify(req: Request, secret: string): boolean {
  const sig = req.headers.get("X-Finn-Signature") || "";
  const body = req.body;  // raw bytes!
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Catálogo de eventos

□ Evento □ Fogos quando Não, não, não O porta-aviões apanhou a chamada Chamada terminada (qualquer razão) Tradução quente para o ser humano A campanha começou a marcar

• deployment.paused * Pausa manual * O público está exausto O saldo caiu abaixo do limiar configurado Recarga bem-sucedida liquidada
• compliance.action_required * Revisão manual necessária *

Confiabilidade

• Repetições no 5xx / timeout: 5 tentativas ao longo de ~10 minutos com retrocesso exponencial.
• A ordem é o melhor esforço, não garantido — timestamps de uso + manipuladores idempotent.
• Use o log webhook do painel para reproduzir as entregas falhadas.

SDKs

Oficial:

• Node / TypeScript — npm install @finn-voice/sdk — totalmente dactilografado, tente novamente incorporado
• Python — pip install finn-voice — sync + assync clients

Comunidade (não apoiada):

• Go, Ruby, PHP — links no repo README

Todos os SDKs envolvem a superfície REST 1:1, lidam com repetições e tipos de navios para cada recurso.

OpenAPI spec

Espectro legível por máquina:

https://api.hirefinn.ai/openapi.json

Use-o para gerar clientes em qualquer idioma, validar órgãos de solicitação em CI ou importar para o Postman:

Postman → File → Import → Link → https://api.hirefinn.ai/openapi.json

Testando localmente

Para o desenvolvimento local do webhook:

# Forward Finn webhooks to your dev machine
ngrok http 3000

# Or use the Finn CLI's built-in tunnel
finn webhooks listen --forward-to http://localhost:3000/webhook

O CLI também escreve respostas API para que você possa escrever testes de integração sem uma chave ao vivo.

Versionamento

• ** Versionamento de caminho** — /v1, /v2. Quebrar as alterações obtém um novo prefixo.
• ** Janela do pôr-do-sol** — pelo menos 12 meses entre o anúncio de depreciação e remoção.
• Header opt-in para recursos beta:

X-Finn-Beta: enable=workflow-canvas-v2

Subscrever o Changelog para o calendário de depreciação.

Limites e quotas

Limite Não, não, não □ Implementações simultâneas máximas por plano (5 Iniciar → Empresa ilimitada)

• Tamanho máximo do público * 5M linhas * O comprimento do prompt do sistema Max .. 32K caracteres Comprimento máximo do URL do webhook O tamanho máximo da carga útil de Webhook Retenção de gravação de 90 dias padrão, configurável por plano • API vida útil da chave

Próximas etapas

1. Construir um agente — tente o Criando um Finn passar através de ponta a ponta via API.
2. ** Lançar uma campanha** — usar o documento Deploys como receita.
3. Seleciona o teu CRM — ver Integrações para padrões webhook.
4. Tune para custo — leia Wallet & AI Credits para entender o modelo de pulso-billing.

Preso? [email protected] — inclua o request_id da resposta de erro se tiver uma.