API para Desarrolladores | QuivAel Automation

🚀 Inicio Rápido

Haz tu primera llamada a la API en menos de 2 minutos.

Terminal — Instalación

# Instalar el SDK de JavaScript
$ npm install @quivael/sdk

# Inicializar cliente
import { QuivAel } from '@quivael/sdk';

const client = new QuivAel({
  apiKey: 'qv_tu_api_key'
});

// Crear un agente de voz
const agent = await client.agents.create({
  name: 'Agente Clara',
  language: 'es-ES',
  personality: 'profesional y empática'
});

// Iniciar una llamada
const call = await client.calls.start({
  agentId: agent.id,
  to: '+59897057945'
});

console.log(call.status); // "connected"

🔑 Autenticación

Todas las peticiones requieren un token de API en el header Authorization.

Autenticación OAuth 2.0

Authorization: Bearer qv_sk_xxxxxxxxxxxxx

# También soportamos OAuth 2.0 para apps de terceros
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=your_client_id
&client_secret=your_client_secret
&code=auth_code_here

POST/v1/agents

Crea un nuevo agente de voz IA con personalidad y configuración personalizadas.

Parámetro	Tipo	Descripción
`name` requerido	string	Nombre identificador del agente
`language` requerido	string	Código BCP-47 (ej: es-ES, en-US)
`personality`	string	Descripción de la personalidad del agente
`voice_id`	string	ID de voz clonada. Omitir para voz por defecto.
`knowledge_base`	string[]	IDs de documentos de la base de conocimiento

Respuesta — 201 Created

{
  "id": "ag_clara_02",
  "name": "Agente Clara",
  "language": "es-ES",
  "status": "active",
  "created_at": "2025-02-15T10:30:00Z"
}

GET/v1/agents

Obtiene la lista de todos los agentes configurados en tu cuenta.

Parámetro	Tipo	Descripción
`limit`	integer	Máximo de resultados (default: 20, max: 100)
`offset`	integer	Paginación
`status`	string	Filtrar por estado: active, paused, archived

POST/v1/calls

Inicia una nueva llamada de voz usando un agente específico.

Parámetro	Tipo	Descripción
`agent_id` requerido	string	ID del agente a utilizar
`to` requerido	string	Número de teléfono E.164
`context`	object	Datos de contexto para la conversación
`webhook_url`	string	URL para recibir eventos de la llamada
`record`	boolean	Grabar la llamada (default: false)

GET/v1/calls/{call_id}

Obtiene el estado actual y metadatos de una llamada.

🔗 Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tus agentes.

call.started

Cuando una llamada se conecta exitosamente

call.ended

Cuando una llamada finaliza con transcripción

call.escalated

Cuando el agente escala a un humano

sentiment.alert

Cuando se detecta sentimiento negativo

⏱️ Rate Limits

Límites de peticiones según tu plan actual.

Plan	Peticiones/min	Llamadas concurrentes	Webhooks
Starter	60	5	10
Professional	300	50	100
Enterprise	Ilimitadas	Ilimitadas	Ilimitadas

Integra Agentes de Voz IA en Cualquier Aplicación

JavaScript

Python

PHP

cURL