Ringostat
Entrar

Métodos /rpc: llamadas con clave API

~8 min · Los principales métodos JSON-RPC para un backend: proyectos, campañas, números y resultados.

/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).

Escribe los nombres de los parámetros tal como aparecen en los ejemplos: /rpc no los convierte, MCP sí. Cuando los nombres en /rpc difieren de la herramienta MCP, la página de la API los muestra bajo el método («otros nombres de parámetros»): por ejemplo, campaign.getCallDetail, campaign.getStructuredReport y campaign.resendCallWebhook reciben project_id y number_id; updateProject, project_id; integrations.list y shareProject, projectId. Las filas de números en las respuestas van en PascalCase (PhoneNumber, Status).

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":"…" }