Métodos /rpc: llamadas con clave API
/rpc es la API JSON-RPC 2.0 sobre la que funciona el panel. Tu backend la llama con una clave API del proyecto: un POST por llamada, sin sesión. Abajo están los métodos que más necesita una integración; cada uno existe también como herramienta MCP, y la sección «API» muestra el nombre en /rpc bajo cada método.
POST https://apiagent.ringostat.com/rpc
X-API-Key: <TU_CLAVE_API>
Content-Type: application/json
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStats",
"params":{ "projectID":217, "campaignID":799 } }
→ 200 { "jsonrpc":"2.0", "id":1, "result":{ … } }
→ 200 { "jsonrpc":"2.0", "id":1,
"error":{ "code":-32603, "message":"Internal error",
"data":"unauthorized access to project" } }Envía tú el projectID: una clave solo abre su propio proyecto y la mayoría de los métodos no lo rellenan (addNumbers y uploadNumbersCSV sí). Un error del método llega con HTTP 200 y error.code -32603; el motivo está en error.data. Un método desconocido es -32601. Sin clave o con una no válida, HTTP 401 con respuesta de texto; más de 60 solicitudes por segundo desde una IP y clave, HTTP 429 durante un minuto. Una solicitud admite hasta 20 MB y una página de lista hasta 1000 filas; no se admiten lotes (un array de solicitudes).
getProjects — el proyecto de la clave: ID, nombre, saldo en USD y límite de llamadas simultáneas. De aquí sale tu projectID.
{ "jsonrpc":"2.0", "id":1, "method":"getProjects",
"params":{} }
→ "result": { "projects":[ { "ID":217, "Name":"My project",
"CurrentBalance":34.44, "MaxConcurrentCalls":3, … } ] }getCampaignStatus — las campañas del proyecto con sus ajustes y contadores de números (stats). El resultado es un array, también para un solo campaignID. Sin limit devuelve todas las campañas: en un proyecto grande pagina con limit y offset (hasta 1000) y pide fields: "summary". Una campaña llama cuando started es true y paused e isArchived son false.
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStatus",
"params":{ "projectID":217, "campaignID":799 } }
→ "result": [ { "id":799, "name":"Order confirmation", "type":"aisdr",
"started":true, "paused":false, "isArchived":false,
"stats":{ "total":120, "pending":80, "completed":31, "failed":4, … }, … } ]uploadCampaign — crea una campaña (sin campaignID) o cambia varios de sus campos (con campaignID: las claves enviadas sobrescriben, el resto se mantiene). type: simple («Informational Call»), aisdr («Voice Agent») o multi_question_dtmf («Interactive Survey»). Una campaña nueva está activa desde el principio y llama en cuanto se añaden números, así que créala con "pause": true. retryDelay va en minutos.
{ "jsonrpc":"2.0", "id":1, "method":"uploadCampaign",
"params":{ "projectID":217, "name":"Order confirmation",
"type":"aisdr", "language":"en-US", "timezone":"Europe/Kyiv",
"pause":true } }
→ "result": { "id":799, "started":true, "paused":true, … }
# cambiar varios campos de una campaña existente
{ … "method":"uploadCampaign",
"params":{ "projectID":217, "campaignID":799, "simultaneousCalls":3 } }updateCampaignField — cambia un solo campo. Iniciar y detener: campo paused (false / true); archivar (isArchived: true) exige la campaña en pausa. Iniciar (paused: false) pasa la comprobación de cumplimiento, que puede tardar unos segundos o denegarlo.
{ "jsonrpc":"2.0", "id":1, "method":"updateCampaignField",
"params":{ "projectID":217, "campaignID":799,
"field":"paused", "value":false } }
→ "result": { "message":"…", "campaign":{ "id":799, "paused":false, … } }addNumbers — añade números a la cola; el projectID se toma de la clave. phone en formato internacional; customFields llegan al bot y al webhook y sus valores deben ser textos; scheduledTime (segundos Unix) aplaza la llamada. Los números no válidos, bloqueados o duplicados se omiten y vuelven en rejected.
{ "jsonrpc":"2.0", "id":1, "method":"addNumbers",
"params":{ "campaignID":799, "numbers":[
{ "phone":"+14155550123", "customFields":{ "name":"John" } } ] } }
→ "result": { "message":"Successfully added 1 numbers to campaign 799",
"numbers":[ { "ID":1001, "PhoneNumber":"+14155550123", "Status":"pending", … } ],
"rejected":[] }uploadNumbersCSV — lo mismo desde texto CSV: una columna phone (escrita así), scheduledTime opcional y el resto de columnas como campos personalizados. Cada fila debe tener tantas columnas como la cabecera.
{ "jsonrpc":"2.0", "id":1, "method":"uploadNumbersCSV",
"params":{ "campaignID":799,
"csvContent":"phone,name\n+14155550123,John\n" } }
→ "result": { "message":"…", "count":1, "rejected":[] }removeNumber quita un número de la campaña (numberID, o phoneNumber: todas las filas con ese teléfono); un número en llamada no se quita. clearPendingNumbers detiene la cola: los números pending y retry pasan a abandoned y la campaña sigue funcionando.
{ "jsonrpc":"2.0", "id":1, "method":"removeNumber",
"params":{ "projectID":217, "campaignID":799, "numberID":1001 } }
→ "result": { "message":"Number removed successfully", … }
{ … "method":"clearPendingNumbers",
"params":{ "projectID":217, "campaignID":799 } }
→ "result": { "message":"…", "updatedCount":80, … }getCampaignStats — contadores de una campaña por estado, duración de las llamadas en segundos, respuestas DTMF y gasto (approxCostUSD es aproximado).
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStats",
"params":{ "projectID":217, "campaignID":799 } }
→ "result": { "campaignID":799,
"stats":{ "total":120, "completed":31, "failed":4, "voicemail":6, … },
"durationStats":{ "avgConnectedDuration":48, … },
"spend":{ "unitsConsumed":52000, "approxCostUSD":5.2, … } }getCampaignNumbers — el registro de llamadas: números con estado, horas (segundos Unix), campos personalizados, respuestas DTMF e informes de IA. Filtros: estado, fechas, búsqueda y duraciones; páginas con limit (50 por defecto, hasta 1000) y offset; total es el número antes de paginar. fields: "summary" omite los informes.
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignNumbers",
"params":{ "projectID":217, "campaignID":799,
"status":"completed", "limit":100, "offset":0 } }
→ "result": { "total":31, "limit":100, "offset":0,
"numbers":[ { "ID":1001, "PhoneNumber":"+14155550123", "Status":"completed",
"StartTime":1760437400, "Duration":56, "CustomFields":{ "name":"John" },
"StructuredReports":[ … ], … } ] }campaign.getCallDetail — una llamada: la fila del número, la transcripción, el informe de IA, la grabación y las entregas del webhook. El archivo de la grabación: GET /audio/recording/{number_id} en el mismo host, con la misma X-API-Key.
{ "jsonrpc":"2.0", "id":1, "method":"campaign.getCallDetail",
"params":{ "project_id":217, "number_id":1001 } }
→ "result": { "number":{ … },
"messages":{ "messages":[ { "role":"assistant", "content":"…" }, … ] },
"structured_report":{ … }, "recording":{ "duration_seconds":56, … },
"webhook":{ "attempts":[ … ] } }campaign.getStructuredReport — el informe de IA de una llamada (number_id) o el último de una campaña (campaign_id): outcome y detailed_report con los campos de los ajustes de informe de la campaña. Solo las llamadas del agente de IA tienen informe.
{ "jsonrpc":"2.0", "id":1, "method":"campaign.getStructuredReport",
"params":{ "number_id":1001 } }
→ "result": { "campaign_id":799, "number_id":1001,
"outcome":"…", "detailed_report":{ "summary":"…", … } }campaign.resendCallWebhook — vuelve a enviar el informe de una llamada terminada al webhook de la campaña (el creador de la clave debe ser administrador del proyecto). Es una solicitud real a tu endpoint: el resultado trae su statusCode y success.
{ "jsonrpc":"2.0", "id":1, "method":"campaign.resendCallWebhook",
"params":{ "project_id":217, "number_id":1001 } }
→ "result": { "statusCode":200, "success":true, "requestBody":"…", … }webCall.create — un token de un solo uso de llamada web para un visitante del sitio (guía «Llamadas web»). Solo funciona con una clave «Web calls only»: una clave completa se rechaza. clientIp es la IP pública del visitante; el token dura 20 segundos y sirve una vez, y el navegador se conecta con él a wsUrl. Un rechazo llega con su código en error.data.code (busy, rate_limited, insufficient_funds, etc.) y el estado HTTP correspondiente.
{ "jsonrpc":"2.0", "id":1, "method":"webCall.create",
"params":{ "campaignId":799, "clientIp":"203.0.113.7" } }
→ "result": { "token":"wct1.…",
"wsUrl":"wss://apiagent.ringostat.com/ws/web-call",
"expiresIn":20, "maxDurationSec":180, "callId":"…" }