curl --request POST \
  --url https://api.ryvo.so/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "agent_8801kpabc123",
  "to": "+5215555550100"
}
'

{
  "id": "call_conv_01abcdef",
  "agent_id": "agent_8801kpabc123",
  "to": "+5215555550100",
  "status": "initiated",
  "created_at": "2026-04-30T18:32:11.123Z"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
  "primary_reason": "wallet",
  "reasons": [
    "wallet",
    "agent:pausado"
  ]
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
  "primary_reason": "wallet",
  "reasons": [
    "wallet",
    "agent:pausado"
  ]
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

Calls

Disparar una llamada saliente

Inicia una llamada saliente desde uno de tus agentes hacia un número en formato E.164. La llamada se factura en tu wallet al terminar (no al disparar) a la tarifa de voz por minuto de tu plan, prorrateada por segundo (ver Configuración → Plan en el portal). La API está disponible en los planes Pro, Scale y Enterprise.

Este endpoint marca con los agentes de voz operados sobre ElevenLabs; los agentes creados en el Constructor (Ryvo Engine) todavía no se pueden disparar por API.

Si tu wallet está vacío, tu suscripción está vencida o el agente está pausado, esta petición devuelve 402 o 422 y la llamada no se dispara.

Para evitar duplicados en reintentos, manda el header Idempotency-Key.

POST

calls

curl --request POST \
  --url https://api.ryvo.so/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "agent_8801kpabc123",
  "to": "+5215555550100"
}
'

{
  "id": "call_conv_01abcdef",
  "agent_id": "agent_8801kpabc123",
  "to": "+5215555550100",
  "status": "initiated",
  "created_at": "2026-04-30T18:32:11.123Z"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
  "primary_reason": "wallet",
  "reasons": [
    "wallet",
    "agent:pausado"
  ]
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
  "primary_reason": "wallet",
  "reasons": [
    "wallet",
    "agent:pausado"
  ]
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

Autorizaciones

Authorization

string

header

requerido

Autenticación con un token Bearer. El token se obtiene desde https://app.ryvo.so/developers y tiene el formato ryvo_live_<64 hex>.

Header: Authorization: Bearer ryvo_live_…

Encabezados

Idempotency-Key

string

Identificador único (1-255 caracteres ASCII imprimibles) para que reintentos del mismo request devuelvan la misma respuesta sin disparar una segunda llamada. Cache de 24 horas. Reusar la misma key con un body distinto devuelve 409 idempotency_conflict.

Maximum string length: 255

Ejemplo:

"lead-abc-2026-04-30-001"

Cuerpo

application/json

agent_id

string

requerido

ID del agente de ElevenLabs (lo ves en app.ryvo.so/agentes). Debe pertenecer a tu cuenta.

Ejemplo:

"agent_8801kpabc123"

string

requerido

Número destino en formato E.164.

Pattern: ^\+[1-9]\d{6,14}$

Ejemplo:

"+5215555550100"

metadata

object

Diccionario opcional de variables que se pasan al agente como dynamic_variables. Máximo 5KB. Las llaves deben tener ≤64 chars, y los valores deben ser string, número, booleano o null.

Show child attributes

Ejemplo:

{
  "lead_name": "Juan García",
  "deal_id": "OPP-2026-0042"
}

Respuesta

Llamada disparada

string

requerido

ID único de la llamada (call_<conversation_id>).

Ejemplo:

"call_conv_01abcdef"

agent_id

string

requerido

Ejemplo:

"agent_8801kpabc123"

string

requerido

Ejemplo:

"+5215555550100"

status

enum<string>

requerido

Estado al disparar. Para saber cómo terminó la llamada, escucha los webhooks call.completed / call.failed.

Opciones disponibles:

initiated

created_at

string<date-time>

requerido

Ejemplo:

"2026-04-30T18:32:11.123Z"