Ringostat
Zaloguj

Metody /rpc: wywołania z kluczem API

~8 min · Główne metody JSON-RPC dla backendu: projekty, kampanie, numery, wyniki.

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

Wpisuj nazwy parametrów dokładnie jak w przykładach: /rpc ich nie konwertuje, MCP — tak. Gdy nazwy na /rpc różnią się od narzędzia MCP, strona API podaje je pod metodą („inne nazwy parametrów”): na przykład campaign.getCallDetail, campaign.getStructuredReport i campaign.resendCallWebhook przyjmują project_id i number_id, updateProject — project_id, integrations.list i shareProject — projectId. Wiersze numerów w odpowiedziach są w PascalCase (PhoneNumber, Status).

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