API de voz de Finn

Finn Voice API

El Finn API es la misma superficie que utiliza nuestro dashboard. Construir agentes de voz, campañas de lanzamiento, análisis ingerentes — todo programáticamente.

Este guía te lleva a tu primera llamada en directo en 5 minutos.

-..

Quickstart (3 pasos)

1. Tomar una tecla API

Dashboard → Configuración → Integraciones → API Llaves → Generar llave.

Tendrás dos niveles clave:

• fnn_test_* — sandbox. Sin facturación de portaaviones, sin diales reales. Uso para el desarrollo.
• fnn_live_* — producción. Llamadas reales, dinero real.

Las claves son org-scoped y heredan los límites de tarifas + cuotas de su plan.

2. Establecer variables de entorno

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

Para la producción, cambiar a:

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

3. Haga su primera llamada

Lista tus pinzones:

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

Respuesta prevista:

{
  "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
  }
}

Hecho. Estás hablando con el API.

-..

Base URL

← Medio ambiente TENIDO URL ANTE Silencio.. Silencio en la producción Silencio

Todos los puntos finales están versionados bajo /v1. Los cambios de ruptura se envían bajo un nuevo prefijo de ruta (/v2, /v3, /v3); los campos aditivos entran en la versión actual.

-..

Autenticación

Cada solicitud necesita una tecla API en el encabezado Authorization:

Authorization: Bearer fnn_live_xxxxxxxxxxxxxxxxxxxx

Gestión clave

• Generado en Dashboard → Configuración → Integración → API Claves.
• Rotación — la misma pantalla. La vieja llave revocó inmediatamente en confirmación.
• Revocación — instantánea. Todas las solicitudes en vuelo usando la llave revocada fallan con 401.
• Scope - las teclas son org-scoped. Use llaves separadas por medio ambiente, por servicio.

Buenas prácticas

• Almacene claves en variables ambientales o un gestor secreto. Nunca se comprometa a la fuente.
• Use fnn_test_* para CI y dev local. Las credenciales de producción nunca deben ver un ordenador portátil desarrollador.
• Gira trimestralmente incluso sin incidentes.
• Auditoría que creó qué recurso a través del campo created_by_key_id sobre la mayoría de los recursos.

-..

Ejemplos de código

Golpea el mismo punto final en 3 idiomas.

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..."
  }'

Nodo / 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 respuesta

Cada respuesta exitosa envuelve la carga útil en un sobre consistente.

Recursos únicos

{
  "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
  }
}

Timestamps

Todos los horarios son ISO-8601 UTC (2026-05-22T14:30:00Z).

IDs

Los ID de recursos son prefijados por tipo para la capacidad de grep:

Silencio Silencio Silencio Silencio.. silencio fn_ silencio Finn (agente de voz) Silencioso Silencio dep_ Silencio Silencio Silencio ph_ Silencio Número de teléfono silencio whk_ silencio Webhook subscripción

-..

Pagination

List endpoints accept:

?page=2&per_page=100

• page predeterminados a 1.
• per_page defaults to 50, max 200.
• La respuesta incluye pagination.has_more —cuando true, aumento page y re-tracción.

Número de cursor para terminales de alta cardiopatía (llamas, transcripciones):

?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMlQxMjowMDowMFoifQ&per_page=100

Cursor es opaco — pasar de nuevo como-es para buscar la siguiente página.

-..

Filtración " clasificación

La mayoría de los endpoints de lista soportan:

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

• filter[field]=value - coincidencia exacta. Algunos campos aceptan arrays: filter[status]=active,paused.
• sort=field - ascendente. Prefijo con - para descender. Comma-separate multiple: sort=-created_at,name.

-..

Idempotencia

Enviar un encabezado Idempotency-Key único en las solicitudes POST que crean recursos. Finn deduplica las solicitudes retrigidas 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", ... }'

Si vuelves a entrar con la misma llave, obtienes la respuesta caché de la primera llamada — ningún recurso duplicado creado.

-..

Errores

JSON sobre:

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

Incluya request_id en cualquier ticket de soporte - es como rastreamos su llamada a través de nuestros registros.

Códigos de estado

TENIDO ESTADO TENIDO Significado ANTERIENTE Retry Silencio.. TEN 400 Silencio Validation error — payload shape wrong TEN No TEN Silencio 401 Silencio API clave faltante / invalid TENIDO No TEN Silencio 403 Silencio Escondido a diferentes org / plan tier Silencio Silencio 404 Silencio Recursos no encontrados Silencio 409 Silencio Conflicto (nombre duplicado, teléfono ya vinculado) Silencio 422 Silencio Rechazar el dominio del negocio (cumplimiento, cuota) Silencio 429 Silencio Tarifa limitada Silencio Sí - respeto Retry-After Silencio Silencio 5xx Silencio Servidor lado Silencio Sí — retrocedimiento exponencial Silencio

Códigos comunes de error

← Código Silencioso Silencio.. Silencio missing_field Silencio Campo obligatorio ausente de la carga útil Silencio invalid_field Silencio Campo presente pero valor inválido Silencio not_authenticated Silencio Bearer token missing Silencio invalid_token Silencio Token revocado o malformado Silencio forbidden_scope Silencio Token no tiene acceso a este recurso Silencio quota_exceeded confidencialidad Plan limit hit Silencio rate_limited Silencio Demasiadas solicitudes por segundo Silencio compliance_block Silencio Solicitud rechazada por reglas de cumplimiento Silencio wallet_insufficient Silencio No hay suficientes créditos para la implementación de lanzamiento

-..

Tasa límite

Silencio Silencio Silencio Silencio Silencio.. Silencioso Principio Silencio 5 Silencio 5,000 Silencio Silencio Silencio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Silencio Silencio Silencio Silencios en la empresa

Contratar el límite devuelve 429 con cabeceras:

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

Respeto Retry-After (segundos) o retroceder exponencialmente en 5xx.

-..

Recursos de un vistazo

Silencio Recurso Silencio Endpoint Silencio Descripción Silencio.. Silenciosos Finns TENIDO Audiencias TENIDO /v1/audiences TENIDO Listas de contactos Silencio Números de teléfono Silencio /v1/phone-numbers Silencio Propietario + alquilado DIDs ← Deployments Silencio Calls Silencio /v1/calls Silencio Registros de llamadas individuales Silencio Voces Silencioso /v1/voices Silencio Voces TTS disponibles Silencio Webhooks Silencio /v1/webhooks Silencio Suscripciones al evento tención Wallet Silencio /v1/wallet/{orgId} Silencioso Saldo + transacciones

-..

Webhooks

Suscribete a los eventos. POST'd a su URL con firma HMAC-SHA256 en X-Finn-Signature.

Registro

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 de pago del 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://..."
  }
}

Firma verificadora (Nodo)

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 TENIDO Fuegos cuando TENIDO Silencio.. Silencio call.started Silencio Carrier recogió la llamada Silencio call.completed Silencio Call terminó (cualquier motivo) Silencio call.transferred Silencio traslado al ser humano Silencio deployment.started Silencio Campaña comenzó a marcar Silencio deployment.paused Silencio Pausa manual Silencio deployment.completed Silencioso Audience exhausto Silencio wallet.low_balance Silencio Saldo caído debajo del umbral configurado Silencio wallet.topup_complete Silencio Recarga exitosa resuelta Silencio compliance.action_required Silencio Manual review needed Silencio

Confiabilidad

• Retries on 5xx / timeout: 5 intentos de ~10 minutos con retroceso exponencial.
• El orden es el mejor esfuerzo, no garantizado — use timetamps + manipuladores idempotent.
• Utilice el registro webhook del dashboard para reproducir entregas fallidas.

-..

SDKs

Oficial:

• Nodo / TipoScript — npm install @finn-voice/sdk — completamente escrito, retry incorporado
• Python — pip install finn-voice — sync + async clients

Comunidad (sin apoyo):

• Go, Ruby, PHP — links en el repo README

Todos los SDKs envuelven la superficie de REST 1:1, manipulan los camiones y tipos de naves para cada recurso.

-..

OpenAPI spec

Espectáculo legible a máquina vive en:

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

Úsalo para generar clientes en cualquier idioma, validar los cuerpos de solicitud en CI, o importar en Postman:

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

-..

Probando localmente

Para el desarrollo local 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

El CLI también teje respuestas API para que puedas escribir pruebas de integración sin una clave en vivo.

-..

Versión

• Path versioning — /v1, /v2. Los cambios de ruptura consiguen un nuevo prefijo.
• ** ventana de lanzamiento** — al menos 12 meses entre el anuncio de deprecación y la eliminación.
• Header opt-in para características beta:

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

Suscríbete al Changelog para el calendario de deprecación.

-..

Límites " cuotas

Silencio Silencio Silencio Silencio.. Silencio Max despliegues concurrentes Silencio Per plan (5 Starter → Ilimitado Enterprise) Silencio Max audiencia tamaño Silencio 5M hileras Silencio Max sistema de longitud rápida Silencio 32K caracteres Silencio Silencio Max webhook longitud URL ← 2048 caracteres Silencio Silencio Webhook payload max size ← 1 MB Silencio Grabación de retención Silencio 90 días predeterminado, configurable por plan ← API vida clave ← Indefinido (recogido manualmente)

-..

Siguientes pasos

1. Construir un agente — probar el Crear un Finn0 walkthrough end-to-end via API.
2. Launch a campaign — use the Deployments doc as a receta.
3. Wire your CRM — see Integrations for webhook patterns.
4. Tune for cost — read Wallet & AI Credits para entender el modelo de pulsación.

¿Atascado? [email protected] - incluir el request_id de la respuesta del error si usted tiene uno.