Ringostat
Вхід

Методи /rpc: виклики з API-ключем

~8 хв · Основні JSON-RPC-методи для бекенду: проекти, кампанії, номери, результати.

/rpc — JSON-RPC 2.0 API, на якому працює кабінет. Ваш бекенд викликає його з API-ключем проекту: один POST на виклик, без сесії. Нижче — методи, які найчастіше потрібні інтеграції; кожен є і як MCP-інструмент, а в розділі «API» під кожним методом показано його назву на /rpc.

POST https://apiagent.ringostat.com/rpc
X-API-Key: <ВАШ_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" } }

Передавайте projectID самі: ключ відкриває лише свій проект, а більшість методів його не підставляє (addNumbers і uploadNumbersCSV підставляють). Помилка методу приходить з HTTP 200 і error.code -32603, причина — в error.data. Невідомий метод — -32601. Без ключа або з недійсним — HTTP 401 з текстовою відповіддю; понад 60 запитів на секунду з однієї IP і ключа — HTTP 429 на хвилину. Запит — до 20 МБ, сторінка списку — до 1000 рядків; пакетні запити (масив запитів) не підтримуються.

Пишіть імена параметрів точно як у прикладах: /rpc їх не перетворює, MCP — перетворює. Де назви на /rpc відрізняються від MCP-інструмента, сторінка API показує їх під методом («інші імена параметрів»): наприклад, campaign.getCallDetail, campaign.getStructuredReport і campaign.resendCallWebhook приймають project_id і number_id, updateProject — project_id, integrations.list і shareProject — projectId. Рядки номерів у відповідях — у PascalCase (PhoneNumber, Status).

getProjects — проект ключа: ID, назва, баланс у USD і ліміт одночасних дзвінків. Звідси береться ваш projectID.

{ "jsonrpc":"2.0", "id":1, "method":"getProjects",
  "params":{} }

→ "result": { "projects":[ { "ID":217, "Name":"My project",
    "CurrentBalance":34.44, "MaxConcurrentCalls":3, … } ] }

getCampaignStatus — кампанії проекту з налаштуваннями й лічильниками номерів (stats). Результат — масив, навіть для одного campaignID. Без limit повертаються всі кампанії: у великому проекті гортайте limit і offset (до 1000) і просіть fields: "summary". Кампанія дзвонить, коли started — true, а paused і isArchived — 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 — створює кампанію (без campaignID) або змінює кілька її полів (з campaignID: передані ключі перезаписуються, решта лишається). type: simple («Інформаційний дзвінок»), aisdr («Голосовий агент») або multi_question_dtmf («Інтерактивне опитування»). Нова кампанія одразу активна й дзвонить, щойно додано номери, тому створюйте її з "pause": true. retryDelay — у хвилинах.

{ "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, … }

# змінити кілька полів наявної кампанії
{ … "method":"uploadCampaign",
  "params":{ "projectID":217, "campaignID":799, "simultaneousCalls":3 } }

updateCampaignField — змінює одне поле. Запуск і зупинка — поле paused (false / true); архівувати (isArchived: true) можна лише кампанію на паузі. Запуск (paused: false) проходить перевірку відповідності, яка може тривати кілька секунд або відмовити.

{ "jsonrpc":"2.0", "id":1, "method":"updateCampaignField",
  "params":{ "projectID":217, "campaignID":799,
    "field":"paused", "value":false } }

→ "result": { "message":"…", "campaign":{ "id":799, "paused":false, … } }

addNumbers — додає номери в чергу; projectID береться з ключа. phone — у міжнародному форматі; customFields передаються боту й у вебхук, їхні значення — рядки; scheduledTime (Unix-секунди) відкладає дзвінок. Некоректні, заблоковані номери й дублікати пропускаються й повертаються в 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 — те саме з CSV-тексту: колонка phone (саме так), необов'язкова scheduledTime, решта колонок стають кастомними полями. У кожному рядку стільки колонок, скільки в заголовку.

{ "jsonrpc":"2.0", "id":1, "method":"uploadNumbersCSV",
  "params":{ "campaignID":799,
    "csvContent":"phone,name\n+14155550123,John\n" } }

→ "result": { "message":"…", "count":1, "rejected":[] }

removeNumber видаляє номер з кампанії (numberID або phoneNumber — тоді всі рядки з цим номером); номер, з яким триває розмова, не видаляється. clearPendingNumbers зупиняє чергу: номери pending і retry стають abandoned, а сама кампанія працює далі.

{ "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 — лічильники однієї кампанії за статусами, тривалість дзвінків у секундах, відповіді DTMF і витрати (approxCostUSD — приблизно).

{ "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 — журнал дзвінків: номери зі статусом, часом (Unix-секунди), кастомними полями, відповідями DTMF і звітами AI. Фільтри: статус, дати, пошук, тривалість; сторінки — limit (за замовчуванням 50, до 1000) і offset, total — кількість до розбиття на сторінки. fields: "summary" прибирає звіти.

{ "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 — один дзвінок: рядок номера, стенограма, звіт AI, запис і доставки вебхука. Файл запису — GET /audio/recording/{number_id} на тому самому хості з тим самим 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 — звіт AI одного дзвінка (number_id) або останній звіт кампанії (campaign_id): outcome і detailed_report з полями з налаштувань звіту кампанії. Звіти є лише в дзвінках AI-агента.

{ "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 — ще раз надсилає звіт завершеного дзвінка у вебхук кампанії (творець ключа має бути адміністратором проекту). Це справжній запит на ваш endpoint: у результаті — його statusCode і success.

{ "jsonrpc":"2.0", "id":1, "method":"campaign.resendCallWebhook",
  "params":{ "project_id":217, "number_id":1001 } }

→ "result": { "statusCode":200, "success":true, "requestBody":"…", … }

webCall.create — одноразовий токен веб-дзвінка для відвідувача сайту (гайд «Веб-дзвінки»). Працює лише з ключем «Лише веб-дзвінки»: повний ключ отримає відмову. clientIp — публічна IP-адреса відвідувача; токен діє 20 секунд і один раз, браузер підключається з ним до wsUrl. Відмова приходить з кодом у error.data.code (busy, rate_limited, insufficient_funds тощо) і відповідним HTTP-статусом.

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