Metody /rpc: wywołania z kluczem API
/rpc to API JSON-RPC 2.0, na którym działa panel. Twój backend wywołuje je z kluczem API projektu: jeden POST na wywołanie, bez sesji. Poniżej metody, których integracja potrzebuje najczęściej; każda istnieje też jako narzędzie MCP, a sekcja „API” pokazuje nazwę na /rpc pod każdą metodą.
POST https://apiagent.ringostat.com/rpc
X-API-Key: <TWÓJ_KLUCZ_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" } }Wysyłaj projectID sam: klucz otwiera tylko swój projekt, a większość metod go nie uzupełnia (addNumbers i uploadNumbersCSV uzupełniają). Błąd metody przychodzi z HTTP 200 i error.code -32603, powód jest w error.data. Nieznana metoda to -32601. Bez klucza lub z nieważnym — HTTP 401 z odpowiedzią tekstową; ponad 60 zapytań na sekundę z jednego IP i klucza — HTTP 429 na minutę. Zapytanie ma do 20 MB, strona listy do 1000 wierszy; zapytania zbiorcze (tablica zapytań) nie są obsługiwane.
getProjects — projekt klucza: ID, nazwa, saldo w USD i limit jednoczesnych połączeń. Stąd weźmiesz projectID.
{ "jsonrpc":"2.0", "id":1, "method":"getProjects",
"params":{} }
→ "result": { "projects":[ { "ID":217, "Name":"My project",
"CurrentBalance":34.44, "MaxConcurrentCalls":3, … } ] }getCampaignStatus — kampanie projektu z ustawieniami i licznikami numerów (stats). Wynik to tablica, także dla jednego campaignID. Bez limit zwraca wszystkie kampanie: w dużym projekcie stronicuj przez limit i offset (do 1000) i proś o fields: "summary". Kampania dzwoni, gdy started to true, a paused i isArchived to 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 — tworzy kampanię (bez campaignID) albo zmienia kilka jej pól (z campaignID: wysłane klucze nadpisują, reszta zostaje). type: simple („Połączenie informacyjne”), aisdr („Agent głosowy”) albo multi_question_dtmf („Ankieta interaktywna”). Nowa kampania jest od razu aktywna i dzwoni, gdy tylko dodasz numery, więc twórz ją z "pause": true. retryDelay podaje się w minutach.
{ "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, … }
# zmiana kilku pól istniejącej kampanii
{ … "method":"uploadCampaign",
"params":{ "projectID":217, "campaignID":799, "simultaneousCalls":3 } }updateCampaignField — zmienia jedno pole. Start i stop — pole paused (false / true); archiwizacja (isArchived: true) wymaga kampanii na pauzie. Start (paused: false) przechodzi kontrolę zgodności, która może potrwać kilka sekund albo odmówić.
{ "jsonrpc":"2.0", "id":1, "method":"updateCampaignField",
"params":{ "projectID":217, "campaignID":799,
"field":"paused", "value":false } }
→ "result": { "message":"…", "campaign":{ "id":799, "paused":false, … } }addNumbers — dodaje numery do kolejki; projectID jest brany z klucza. phone w formacie międzynarodowym; customFields trafiają do bota i do webhooka, a ich wartości to teksty; scheduledTime (sekundy Unix) odkłada połączenie. Błędne, zablokowane i zduplikowane numery są pomijane i wracają w 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 — to samo z tekstu CSV: kolumna phone (dokładnie tak), opcjonalna scheduledTime, pozostałe kolumny stają się polami własnymi. Każdy wiersz ma tyle kolumn co nagłówek.
{ "jsonrpc":"2.0", "id":1, "method":"uploadNumbersCSV",
"params":{ "campaignID":799,
"csvContent":"phone,name\n+14155550123,John\n" } }
→ "result": { "message":"…", "count":1, "rejected":[] }removeNumber usuwa numer z kampanii (numberID albo phoneNumber — wtedy wszystkie wiersze z tym numerem); numeru w trakcie rozmowy nie usunie. clearPendingNumbers zatrzymuje kolejkę: numery pending i retry stają się abandoned, a sama kampania działa dalej.
{ "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 — liczniki jednej kampanii według statusów, czasy połączeń w sekundach, odpowiedzi DTMF i koszty (approxCostUSD jest przybliżony).
{ "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 — dziennik połączeń: numery ze statusem, czasami (sekundy Unix), polami własnymi, odpowiedziami DTMF i raportami AI. Filtry: status, daty, wyszukiwanie, czasy trwania; strony przez limit (domyślnie 50, do 1000) i offset, total to liczba przed podziałem na strony. fields: "summary" pomija raporty.
{ "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 — jedno połączenie: wiersz numeru, transkrypcja, raport AI, nagranie i dostarczenia webhooka. Plik nagrania: GET /audio/recording/{number_id} na tym samym hoście, z tym samym 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 — raport AI jednego połączenia (number_id) albo ostatni raport kampanii (campaign_id): outcome i detailed_report z polami z ustawień raportu kampanii. Raporty mają tylko połączenia agenta 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 — ponownie wysyła raport zakończonego połączenia do webhooka kampanii (twórca klucza musi być administratorem projektu). To prawdziwe zapytanie do Twojego endpointu: wynik zawiera jego statusCode i success.
{ "jsonrpc":"2.0", "id":1, "method":"campaign.resendCallWebhook",
"params":{ "project_id":217, "number_id":1001 } }
→ "result": { "statusCode":200, "success":true, "requestBody":"…", … }webCall.create — jednorazowy token połączenia web dla odwiedzającego stronę (przewodnik „Połączenia web”). Działa tylko z kluczem „Tylko połączenia webowe”: pełny klucz zostanie odrzucony. clientIp to publiczny adres IP odwiedzającego; token działa 20 sekund i tylko raz, a przeglądarka łączy się z nim z wsUrl. Odmowa przychodzi z kodem w error.data.code (busy, rate_limited, insufficient_funds itp.) i odpowiednim statusem 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":"…" }