Integraciones

API Reference

La API REST de VoiceAgent te permite gestionar agentes, iniciar llamadas y consultar analíticas desde cualquier lenguaje o plataforma.

Autenticación

Todas las peticiones a la API deben incluir tu API Key como Bearer Token en la cabeceraAuthorization. Puedes encontrar tu API Key en el dashboard bajo Configuración → API Keys.

Authorization: Bearer va_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Entornos: Live vs. Test

Las API Keys con prefijo va_live_ operan en producción y generan llamadas reales. Las keys con prefijo va_test_ operan en entorno sandbox, simulan llamadas sin coste y sin contactar números reales.

URL base

https://usvoiceagent.com/api

Cabeceras comunes

Cabecera	Valor	Requerida
`Authorization`	Bearer {API_KEY}	Sí
`Content-Type`	application/json	Para POST/PATCH/PUT
`Accept`	application/json	No (recomendada)
`X-Idempotency-Key`	UUID v4	No (recomendada para POST)

Agentes

GET

/api/agents

Devuelve la lista de todos los agentes en tu cuenta, ordenados por fecha de creación descendente.

Query parameters

Parámetro	Tipo	Default	Descripción
`limit`	number	20	Número de resultados (max: 100)
`offset`	number	0	Desplazamiento para paginación
`status`	string	—	"active" \| "paused" \| "all"

// Response 200 OK
{
  "data": [
    {
      "id": "agent_xxxxxxxxxxxx",
      "name": "Recepción Central",
      "status": "active",
      "voice": "es-ES-ElviraNeural",
      "language": "es-ES",
      "phoneNumber": "+12125551234",
      "totalCallsToday": 47,
      "totalMinutesToday": 312,
      "createdAt": "2025-04-01T08:00:00Z",
      "updatedAt": "2025-05-20T14:30:00Z"
    }
  ],
  "total": 3,
  "limit": 20,
  "offset": 0
}

POST

/api/agents

Crea un nuevo agente en tu cuenta.

// Request body
{
  "name": "Soporte Técnico",
  "greeting": "Hola, soy el asistente de soporte de TuEmpresa. ¿En qué puedo ayudarte?",
  "systemPrompt": "Eres un agente de soporte técnico especializado en software de contabilidad. Responde siempre en español, de forma clara y concisa. Si no puedes resolver el problema, usa la herramienta transfer_call.",
  "voice": "es-ES-AlvaroNeural",
  "language": "es-ES",
  "phoneNumber": "+12125551234",
  "tools": ["transfer_call", "send_sms"],
  "settings": {
    "maxDurationSeconds": 600,
    "silenceTimeoutSeconds": 8,
    "interruptible": true
  }
}

// Response 201 Created
{
  "id": "agent_yyyyyyyyyyyy",
  "name": "Soporte Técnico",
  "status": "active",
  "createdAt": "2025-05-21T10:00:00Z"
}

PATCH

/api/agents/{agentId}

Actualiza campos específicos de un agente existente. Solo se actualizan los campos incluidos en el body.

// Request body (solo los campos a actualizar)
{
  "greeting": "Nuevo saludo actualizado",
  "status": "paused"
}

// Response 200 OK
{
  "id": "agent_xxxxxxxxxxxx",
  "name": "Soporte Técnico",
  "status": "paused",
  "updatedAt": "2025-05-21T11:00:00Z"
}

Llamadas

GET

/api/calls

Devuelve el historial de llamadas con filtros opcionales por agente, fecha, estado y dirección.

// GET /api/calls?agentId=agent_xx&startDate=2025-05-01&endDate=2025-05-21&limit=50

// Response 200 OK
{
  "data": [
    {
      "id": "call_abc123def456",
      "agentId": "agent_xxxxxxxxxxxx",
      "direction": "inbound",
      "status": "completed",
      "from": "+34600123456",
      "to": "+12125551234",
      "durationSeconds": 342,
      "startedAt": "2025-05-21T10:30:05Z",
      "endedAt": "2025-05-21T10:35:47Z",
      "endReason": "user_hangup",
      "hasTranscript": true,
      "hasRecording": false,
      "sentiment": "positive",
      "intentDetected": "horario_consulta"
    }
  ],
  "total": 1247,
  "limit": 50,
  "offset": 0
}

GET

/api/calls/{callId}

Devuelve los detalles completos de una llamada, incluyendo la transcripción completa si está disponible.

// Response 200 OK
{
  "id": "call_abc123def456",
  "agentId": "agent_xxxxxxxxxxxx",
  "direction": "inbound",
  "status": "completed",
  "from": "+34600123456",
  "to": "+12125551234",
  "durationSeconds": 342,
  "startedAt": "2025-05-21T10:30:05Z",
  "endedAt": "2025-05-21T10:35:47Z",
  "transcript": [
    { "role": "agent", "text": "Hola, bienvenido...", "timestamp": "..." },
    { "role": "user", "text": "Quiero saber...", "timestamp": "...", "confidence": 0.97 }
  ],
  "summary": "El cliente preguntó por el horario de atención.",
  "sentiment": "positive",
  "recordingUrl": null,
  "metadata": {}
}

POST

/api/calls/outbound

Inicia una llamada saliente. Ver la sección de Llamadas salientes para el detalle completo de parámetros.

// Request body
{
  "agentId": "agent_xxxxxxxxxxxx",
  "to": "+34600123456",
  "from": "+12125551234",
  "metadata": { "customerId": "cust_789" },
  "overrides": {
    "greeting": "Hola, te llamamos de TuEmpresa...",
    "maxDurationSeconds": 180
  }
}

// Response 202 Accepted
{
  "callId": "call_newcall789",
  "status": "queued",
  "estimatedStartTime": "2025-05-21T10:30:05Z",
  "createdAt": "2025-05-21T10:30:00Z"
}

Analíticas

GET

/api/analytics

Devuelve métricas agregadas de uso para el período especificado.

// GET /api/analytics?period=last_30_days&agentId=agent_xx

// Response 200 OK
{
  "period": {
    "start": "2025-04-21T00:00:00Z",
    "end": "2025-05-21T23:59:59Z"
  },
  "summary": {
    "totalCalls": 1247,
    "totalMinutes": 8934,
    "inboundCalls": 982,
    "outboundCalls": 265,
    "completedCalls": 1190,
    "missedCalls": 57,
    "averageDurationSeconds": 430,
    "averageSentimentScore": 0.78
  },
  "minutesUsed": 8934,
  "minutesIncluded": 10000,
  "minutesRemaining": 1066,
  "dailyBreakdown": [
    {
      "date": "2025-05-21",
      "calls": 47,
      "minutes": 312,
      "averageDuration": 398
    }
  ],
  "topIntents": [
    { "intent": "horario_consulta", "count": 312, "percentage": 25.0 },
    { "intent": "cancelar_cita", "count": 187, "percentage": 15.0 },
    { "intent": "informacion_precios", "count": 143, "percentage": 11.5 }
  ]
}

Códigos de error

La API de VoiceAgent usa los códigos HTTP estándar. Todos los errores devuelven un objeto JSON con el formato:

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "No se encontró el agente con ID agent_xxxxxxxxxx",
    "status": 404,
    "requestId": "req_01HWXYZ999"
  }
}

HTTP Status	Error Code	Descripción
400	`VALIDATION_ERROR`	El body de la petición contiene campos inválidos o faltan campos requeridos
401	`UNAUTHORIZED`	API Key no proporcionada, inválida o revocada
403	`FORBIDDEN`	La API Key no tiene permisos para esta operación (ej. plan insuficiente)
404	`NOT_FOUND`	El recurso solicitado (agente, llamada) no existe en tu cuenta
409	`CONFLICT`	El recurso ya existe o hay un conflicto de estado (ej. agente ya pausado)
422	`UNPROCESSABLE`	La petición es sintácticamente correcta pero no puede procesarse (ej. número inválido)
429	`RATE_LIMITED`	Has superado el límite de peticiones. Revisa la cabecera Retry-After
500	`INTERNAL_ERROR`	Error interno del servidor. Contacta a soporte con el requestId
503	`SERVICE_UNAVAILABLE`	Servicio temporalmente no disponible. Reintenta en unos minutos

Rate limiting

La API incluye cabeceras de rate limit en todas las respuestas:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1716292800
Retry-After: 60   // Solo presente cuando HTTP 429

Los límites por defecto son 1.000 peticiones por hora para planes Starter y Business, y 10.000 peticiones por hora para Enterprise. Estos límites aplican a la API REST, no a las llamadas de voz.

SDKs oficiales

Para mayor comodidad, VoiceAgent ofrece SDKs oficiales que envuelven la API REST:

Node.js / TypeScript

Disponible

npm install @voiceagent/sdk

Python

Disponible

pip install voiceagent-sdk

PHP

Beta

composer require voiceagent/sdk

Ruby

Próximamente

gem install voiceagent

Anterior: Webhooks