Pređi na glavni sadržaj

Lokalni REST API

AI Softphone ima REST API za CTI integraciju: program na istom računaru može da upućuje pozive i upravlja njima, čita kontakte, istoriju poziva i SIP naloge i prati pozive u toku. Bez SDK-a, bez posrednika u oblaku i bez slušaoca izloženog mreži. Zahtevi i odgovori su JSON, pa je dovoljan curl ili bilo koji HTTP klijent.

API je nakon instalacije isključen; ništa ne sluša dok ga ne uključite. Tada sluša samo na loopback sučelju — malom veb-sučelju koje odgovara samo ovom računaru — i nije dostupan iz kancelarijske mreže, VPN-a niti sa drugog računara.

Koristite API kada vaš program treba podatke iz telefona ili mora da upravlja pozivom. Koristite veb-kuke kada mora da reaguje na pozive dok se dešavaju, bez prozivanja. Većina integracija koristi oboje; međusobno su nezavisni.

Uključivanje​

Otvorite Podešavanja → Povezivanje i idite na Lokalno upravljanje.

  1. Uključite Dozvoli drugim programima na ovom računaru da upravljaju telefonom. Server se odmah pokreće.
  2. Zadržite podrazumevani Port, 8377, osim ako ga već koristi drugi program.
  3. Po želji podesite Žeton. Nakon čuvanja polje prikazuje Sačuvano — kucajte da zamenite.
  4. Pod Pristup izaberite grupe koje želite da otvorite: Kontakti, Istorija poziva, Pozivi i upravljanje njima, Nalozi, Podešavanja, Brojači (metrike). Isključena grupa se ne filtrira, nego se uopšte ne služi.
  5. Isprobajte: curl http://127.0.0.1:8377/accounts. Ako je odgovor JSON, API radi.

Ne instalira se zasebna usluga i nije potrebno ponovno pokretanje. Deo programa koji to radi može da se isključi u Modulima (Povezivanje).

Sopstvena stranica API-ja​

Otvori sopstvenu stranicu API-ja otvara http://127.0.0.1:8377 u pregledaču. Adresa odgovara spiskom svega što služi, na engleskom; adrese koje nešto čitaju su veze koje možete da pratite.

Pristup i žeton​

Šta program sme da radi zavisi od toga da li menja sačuvane podatke, a ne od toga da li čita:

  • Bez žetona bilo koji program na računaru sme da čita sve u uključenim grupama i da upravlja pozivima: da uputi, javi se, prekine, stavi na čekanje, nastavi, prosledi i šalje DTMF.
  • Sa žetonom u zaglavlju Authorization sme da koristi i krajnje tačke koje menjaju ono što je sačuvano. Bez žetona te krajnje tačke se ne navode na sopstvenoj stranici API-ja i odgovaraju sa 401. Ako žeton uopšte nije podešen, ništa ne može da promeni sačuvano.

Žeton se čuva u skladištu ključeva računara, ne u datoteci podešavanja, i /settings ga nikada ne vraća.

oprez

Bez žetona bilo koji program koji radi na ovom računaru može da upravlja telefonom, uključujući javljanje na pozive. Na ličnoj radnoj stanici to je obično prihvatljivo. Na zajedničkom ili upravljanom računaru podesite žeton i postupajte sa njim kao sa bilo kojom drugom lozinkom. Žeton štiti samo zahteve koji menjaju sačuvane podatke, a ne pozive: ako želite da druge programe držite dalje od poziva, isključite Pozivi i upravljanje njima pod Pristup.

Krajnje tačke​

Osnovna adresa je http://127.0.0.1:8377. Krajnje tačke u nastavku ne zahtevaju žeton.

MetodPutanjaŠta radi
GET/metricsBrojači, u formatu Prometheus.
GET/uiSpisak snimaka, kao HTML stranica.
GET/ui/recordings/{id}Snimak sa prepisom, kao HTML stranica.
GET/ui/recordings/{id}/audioZvuk za gornju stranicu.
GET/contactsKontakti.
GET/contacts/{id}Jedan kontakt.
GET/historyDnevnik poziva, od najnovijih. Prihvata ?limit=, ?missed=true i ?declined=true.
GET/callsPozivi u toku.
POST/callsUpućuje poziv: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerJavlja se na poziv.
POST/calls/{id}/hangupPrekida poziv.
POST/calls/{id}/holdStavlja poziv na čekanje.
POST/calls/{id}/resumeVraća ga sa čekanja.
POST/calls/{id}/dtmfŠalje tonove: {"digits": "..."}.
POST/calls/{id}/transferProsleđuje poziv: {"target": "..."}.
GET/accountsSIP nalozi i stanje njihove registracije. Nikada lozinka.
GET/settingsCela konfiguracija, bez tajni.
GET/taxonomyKategorije, oznake i upozorenja, sa njihovim kodovima.

Krajnje tačke kojima treba žeton​

One menjaju ono što je sačuvano, pa svaki zahtev mora da nosi žeton u zaglavlju Authorization. Sopstvena stranica API-ja ih prikazuje samo zahtevu koji ga nosi.

MetodPutanjaŠta radi
POST/contactsDodaje kontakt: {"name": "...", "number": "...", "account_id": "..."}; account_id nije obavezan.
PUT/contacts/{id}Zamenjuje kontakt.
DELETE/contacts/{id}Uklanja kontakt.
DELETE/history/{id}Zaboravlja jedan poziv iz dnevnika poziva.
DELETE/historyZaboravlja ceo dnevnik poziva. To se ne može opozvati.
PUT/accounts/{id}Zamenjuje podešavanja naloga. Lozinka nije među njima.
PUT/settingsZamenjuje podešavanja.

Svaki identifikator je UUID koji dodeljuje telefon: id poziva dolazi iz /calls ili iz odgovora na POST /calls, id naloga iz /accounts.

Nazivi polja su u snake_caseu, a završetak govori o vrsti: _id je referenca na UUID, _ts je trenutak u Unix milisekundama (UTC), _s je trajanje u sekundama. Isto važi za veb-kuke; samo /settings ima sopstvene nazive. U REST API-ju te vrednosti su JSON brojevi, a nepoznat trenutak je null.

Primer: upućivanje poziva​

POST /calls upućuje odlazni poziv. Telo je JSON sa number koji treba pozvati i, po želji, account_id naloga sa kog treba zvati:

curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'

Odgovor je identifikator novog poziva:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number je obavezan. Bez njega odgovor je 400 {"error":"a call needs a number"} i ništa se ne bira.
  • Broj se na izabranom nalogu dopunjuje kao što ga dopunjuje polje za biranje: 1020 se šalje kao sip:1020@pbx.example.com. POST /calls/{id}/transfer dopunjuje svoj target na isti način; cilj koji već ima šemu ili @ šalje se takav kakav jeste.
  • account_id je neobavezan; uzmite ga iz GET /accounts. Bez njega poziv ide sa naloga izabranog u glavnom prozoru.
  • Koristite id u /calls/{id}/…: hangup, hold, resume, dtmf i transfer. Veb-kuke ovog poziva nose isti id.

Sa veb-stranice: klik za poziv​

Stranica koja zove 127.0.0.1 dolazi do računara na kom radi pregledač — istog na kom radi telefon —, pa dugme „klik za poziv” u CRM-u ne treba sopstveni server:

async function dial(number) {
const r = await fetch("http://127.0.0.1:8377/calls", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ number }),
});
if (!r.ok) console.warn("softphone:", (await r.json()).error);
}

Šta sadrže odgovori​

Pozivi u toku: GET /calls​

Svaki poziv ima svoj id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts i callstate_ts.

  • state je dialing, ringing-out, ringing-in, active, hold (na čekanje stavio ovaj telefon), onhold (na čekanje stavila druga strana), conference ili ended. Kada važi više od jednog, conference ima prednost nad hold, a hold nad onhold.
  • muted kaže da li je mikrofon u pozivu isključen; isključivanje mikrofona ne menja state.
  • seance_id je razgovor: pozivi povezani prosleđivanjem, konsultacijom ili konferencijom dele ga.
  • event_ts je trenutak kada je odgovor nastao. Uporedite ga sa callstate_ts da vidite koliko je dugo poziv u svom stanju, bez oslanjanja na sopstveni sat.

Nalozi: GET /accounts​

Svaki nalog ima svoj id (svuda drugde account_id), svoja podešavanja — transport (udp, tcp ili tls), port, registrar, outbound_proxy, expiry_s i druga —, da li je enabled, i svoj state na centrali: registered dok je linija aktivna. Lozinke nikada nisu uključene.

Istorija poziva: GET /history​

Od najnovijih, 100 stavki osim ako ?limit= kaže drugačije. ?missed=true vraća samo propuštene pozive, ?declined=true samo pozive koje je ovaj telefon odbio.

PoljeZnačenje
idSopstveni identifikator stavke istorije. To nije id poziva iz /calls i veb-kuka; povezuje ih seance_id.
outcomeGlavna klasifikacija: answered, missed, declined ili failed.
answeredtrue ili false.
duration_s0 za poziv koji nikada nije uspostavljen.
number, uriDruga strana, kao broj i kao SIP adresa.
nameIz Kontakata ako je broj poznat, inače prazno. Uparujte po number, ne po ovome.
dialedBirane cifre, za odlazni poziv; prazno za dolazni.
account, account_idLinija na kojoj je poziv bio.
reasonKako se završio: local-hangup, remote-hangup, cancelled…
answered_byno ako se javio čovek; inače ono što se javilo na poziv.

Kontakti: GET /contacts​

Svaki kontakt ima svoj id, name, number i liniju kojoj pripada, account_id i account; prazan account znači da kontakt nije vezan za liniju.

Snimci​

Snimci i prepisi se ne izdaju kao JSON. API ih služi kao HTML stranice, /ui i /ui/recordings/{id}: povezujte na te stranice iz svog CRM-a umesto premeštanja zvuka. Veza se otvara na računaru koji čuva snimak, a zvuk ga nikada ne napušta.

Taksonomija i podešavanja​

Svaka stavka /taxonomy ima stalan code, title i description na jeziku sučelja, kind (category, tag ili red_flag) i, za upozorenja, severity. Uparujte po code, nikada po title: naslovi dolaze na jeziku na koji je telefon podešen. Stavka sa retired: true zadržava se kako bi se stariji pozivi i dalje razrešavali; novim pozivima se više ne dodeljuje. Učitajte taksonomiju jednom pri pokretanju da reči telefona preslikate na sopstvena polja.

/settings vraća konfiguraciju osim tajni: zvučne uređaje i jačine, prioritet kodeka, izgled i jezik, pokretanje, prečice, nivo dijagnostike i stanje obe integracije — korisno za alat podrške koji mora da proveri radnu stanicu bez deljenja ekrana. api.disabled navodi isključene grupe pristupa, a webhooks.silenced isključene događaje; prazni spiskovi znače da je sve uključeno. Nikada ne uključuje SIP lozinku, žeton API-ja ni vrednost zaglavlja veb-kuke.

Greške​

Svaka greška je JSON sa jednim ključem error, namenjena ljudima, a ne raščlanjivanju.

StatusTeloZnačenje
404{"error":"no such endpoint"}Putanja ne postoji ili je njena grupa pristupa isključena; oboje namerno daje isti odgovor.
405{"error":"that endpoint does not take this method"}Putanja postoji, ali ne prima tu metodu: na primer POST /settings umesto PUT.
401{"error":"writing needs a token, and none is configured"}Krajnja tačka koja menja sačuvano, na telefonu gde je polje Žeton prazno. Popunite ga u Lokalno upravljanje.
401{"error":"this endpoint needs the authorization token"}Krajnja tačka koja menja sačuvano, bez ispravnog žetona.
404{"error":"no contact with that id"}Putanja je ispravna, identifikator nije.
400{"error":"no call with that id"}Poziv se završio ili nikada nije postojao.
400{"error":"a call needs a number"}POST /calls bez broja. Ništa nije birano.
400{"error":"no digits to send"}POST /calls/{id}/dtmf bez cifara.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer bez cilja.
400{"error":"the account this call is on is no longer set up"}Nalog poziva je uklonjen tokom poziva, pa cilj ne može da se dopuni. Centrali ništa nije poslato.

Odbijeni zahtevi broje se u api_requests_refused_total, pa se integracija koja tiho ne uspeva vidi u metrikama, a ne samo u vašim sopstvenim dnevnicima.

Metrike​

GET /metrics vraća svaki brojač telefona, svaki sa tekstom pomoći. Prikupljajte ih Prometheusom ili ih čitajte ručno.

BrojačBroji
calls_incoming_totalPrimljene dolazne pozive.
calls_outgoing_totalUpućene odlazne pozive.
calls_answered_totalPozive na koje se neko javio.
calls_missed_totalDolazne pozive na koje se niko nije javio.
calls_declined_totalPozive odbijene ovde ili na drugoj strani.
calls_failed_totalPozive koji nisu mogli da se uspostave.
registrations_succeeded_totalUspešne SIP registracije.
registrations_failed_totalSIP registracije odbijene ili istekle.
webhooks_delivered_totalVeb-kuke koje je primalac prihvatio.
webhooks_failed_totalVeb-kuke odbijene ili neisporučene.
webhooks_dropped_totalVeb-kuke odbačene jer je red bio pun.
api_requests_totalZahteve koje je API obradio.
api_requests_refused_totalOdbijene zahteve: pogrešan žeton, isključena grupa ili nepoznata putanja.

Ažuriranje starije integracije​

Ranije verzije su koristile nazive u camelCaseu i kratke identifikatore. accountId je sada account_id, startedAt je callstart_ts, durationSeconds je duration_s, answeredBy je answered_by, a polje veb-kuke at je event_ts. Pozivi i nalozi se identifikuju samo UUID-om: runtimeId i identifikatori kao što su call-3 ili account-2 više se ne vraćaju niti prihvataju.

Kada ne radi​

SimptomŠta proveriti
Veza odbijena na 127.0.0.1:8377Lokalno upravljanje je isključeno, telefon ne radi ili je port promenjen.
404 {"error":"no such endpoint"} za putanju sa ove straniceNjena grupa pristupa je isključena.
Čitanje radi, pisanje se odbija sa 401Krajnjim tačkama koje menjaju sačuvane podatke treba žeton u zaglavlju Authorization, a na telefonu najpre treba popuniti polje Žeton.
Naslovi kategorija nisu na engleskomNaslovi prate jezik sučelja. Uparujte po code iz /taxonomy.
Nedostaju accountId, startedAt ili atIntegracija je pisana za ranije nazive; pogledajte gore.

Za problem sa registracijom ili samim pozivom otvorite Dijagnostiku.