API REST.
PARA BOTS
DE VOZ.
La API de Voztro permite gestionar bots, llamadas, conexiones, herramientas, webhooks y fuentes de conocimiento desde aplicaciones externas. Usa API key, respuestas JSON y paginación por cursor.
autenticaciónAPI KEY
API KEY
EN HEADER.
Genera claves desde el panel. Cada clave tiene permisos por recurso y puedes revocarla cuando quieras. Las peticiones usan Bearer token en el header Authorization.
# ejemplo de petición
curl -X GET \
https://api.voztro.com/v1/bots
-H 'Authorization: Bearer vzk_...'
-H 'Content-Type: application/json'
─── ENDPOINTS ───
Bots
GET/v1/botsLista todos los bots del usuario autenticado.
POST/v1/botsCrea un nuevo bot con configuración de voz, guión y herramientas.
GET/v1/bots/:idObtiene detalles, configuración, estado y últimas 10 llamadas del bot.
PATCH/v1/bots/:idActualiza nombre, voz, guión, horario, webhook, estado y más.
DELETE/v1/bots/:idElimina un bot y cancela su suscripción asociada si existe.
Knowledge
GET/v1/bots/:id/knowledgeLista todas las fuentes de conocimiento del bot.
POST/v1/bots/:id/knowledgeSube un archivo de conocimiento (PDF, TXT, CSV) al bot.
POST/v1/bots/:id/knowledge/searchBusca en las fuentes de conocimiento del bot por texto.
GET/v1/bots/:id/knowledge/:sourceIdObtiene el detalle de una fuente de conocimiento específica.
DELETE/v1/bots/:id/knowledge/:sourceIdElimina una fuente de conocimiento del bot.
Tools
GET/v1/bots/:id/toolsLista todas las herramientas configuradas en el bot.
POST/v1/bots/:id/toolsAgrega una herramienta al bot (webhook, conexión, calendar, transfer).
GET/v1/bots/:id/tools/:toolIdObtiene el detalle de una herramienta específica.
PATCH/v1/bots/:id/tools/:toolIdActualiza nombre, descripción, schema, handler o estado de la herramienta.
DELETE/v1/bots/:id/tools/:toolIdElimina una herramienta del bot.
POST/v1/bots/:id/tools/:toolId/testEjecuta una prueba de la herramienta con argumentos personalizados.
Calls
GET/v1/callsLista llamadas con filtros por fecha, bot y paginación cursor.
GET/v1/calls/:idObtiene detalle de llamada con metadatos y estado.
GET/v1/calls/:id/transcriptDescarga la transcripción completa de una llamada.
Connections
GET/v1/connectionsLista todas las conexiones configuradas del usuario.
POST/v1/connectionsCrea una conexión (Sheets, Shopify, Postgres, Webhook, etc.) con credenciales cifradas.
GET/v1/connections/:idObtiene el detalle de una conexión específica.
PATCH/v1/connections/:idActualiza nombre, configuración, secreto o estado de la conexión.
DELETE/v1/connections/:idElimina una conexión.
POST/v1/connections/:id/testPrueba la conexión: HEAD request para webhooks, verificación de secreto para APIs y BD.
Webhooks
GET/v1/webhooksLista webhooks configurados con URL y eventos suscritos.
POST/v1/webhooksCrea un endpoint de webhook con eventos personalizados y secreto SHA-256.
GET/v1/webhooks/:idObtiene detalle del webhook con historial de entregas.
PATCH/v1/webhooks/:idActualiza nombre, URL, eventos o estado del webhook.
DELETE/v1/webhooks/:idElimina un endpoint de webhook.
POST/v1/webhooks/:id/testEnvía un evento de prueba al endpoint para verificar la conexión.
Events & Logs
GET/v1/eventsLista historial de entregas de webhooks con filtro por tipo de evento y paginación.
GET/v1/requestsLista el log de todas las peticiones API realizadas con autenticación.
tipos de conexión9 TIPOS DE
9 TIPOS DE
CONEXIÓN.
Cada conexión cifra credenciales con AES-256. Las conexiones SQL son de solo lectura y se validan contra consultas permitidas.
WEBHOOKREST_APIPOSTGRES_READONLYMYSQL_READONLYGOOGLE_SHEETSAIRTABLENOTIONSHOPIFYHUBSPOT
eventos de webhook9 EVENTOS
9 EVENTOS
DISPONIBLES.
Cada webhook se suscribe a uno o más eventos. Los payloads van firmados con SHA-256 usando el secreto generado al crear el endpoint.
call.started
Una llamada entrante fue contestada por el bot.
call.ended
La llamada terminó normalmente.
call.failed
La llamada falló por error técnico.
tool.called
Una herramienta fue invocada durante la llamada.
tool.succeeded
La herramienta se ejecutó correctamente.
tool.failed
La herramienta falló durante la ejecución.
bot.balance_low
El saldo del bot está por debajo del umbral.
bot.disabled
El bot fue desactivado por falta de pago o saldo.
human_handoff.requested
El bot solicitó transferir la llamada a un humano.
historial y logs/V1/EVENTS
/V1/EVENTS
/V1/REQUESTS
/v1/events devuelve el historial paginado de entregas de webhook, con filtro por tipo de evento.
/v1/requests devuelve el log de todas las peticiones API autenticadas, útil para auditoría y depuración.
// respuesta paginada
{
"data": [...],
"pagination": {
"nextCursor": "abc123..."
}
}