Методи /rpc: виклики з API-ключем
/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 рядків; пакетні запити (масив запитів) не підтримуються.
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":"…" }