Prijeđi na glavni sadržaj

Lokalni REST API

AI Softphone ima REST API za CTI integraciju: program na istom računalu može upućivati pozive i upravljati njima, čitati kontakte, povijest poziva i SIP račune te pratiti pozive u tijeku. Bez SDK-a, bez posrednika u oblaku i bez slušatelja izloženog mreži. Zahtjevi 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 web-sučelju koje odgovara samo ovom računalu — i nije dostupan iz uredske mreže, VPN-a ni s drugog računala.

Koristite API kad vaš program treba podatke iz telefona ili mora upravljati pozivom. Koristite webhookove kad mora reagirati na pozive dok se događaju, bez prozivanja. Većina integracija koristi oboje; međusobno su neovisni.

Uključivanje​

Otvorite Postavke → Integracija i idite na Lokalno upravljanje.

  1. Uključite Dopusti drugim programima na ovom računalu da upravljaju telefonom. Poslužitelj se odmah pokreće.
  2. Zadržite zadani Port, 8377, osim ako ga već koristi drugi program.
  3. Po želji postavite Token. Nakon spremanja polje prikazuje Spremljeno — pišite da to zamijenite.
  4. Pod Pristup odaberite skupine koje želite otvoriti: Kontakti, Povijest poziva, Pozivi i upravljanje njima, Računi, Postavke, Brojači (metrike). Isključena skupina ne filtrira se, nego se uopće ne poslužuje.
  5. Provjerite: curl http://127.0.0.1:8377/accounts. Ako je odgovor JSON, API radi.

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

Vlastita stranica API-ja​

Otvori vlastitu stranicu API-ja otvara http://127.0.0.1:8377 u pregledniku. Adresa odgovara popisom svega što poslužuje, na engleskom; adrese koje nešto čitaju poveznice su koje možete slijediti.

Pristup i token​

Što program smije raditi ovisi o tome mijenja li spremljene podatke, a ne o tome čita li:

  • Bez tokena bilo koji program na računalu smije čitati sve u uključenim skupinama i upravljati pozivima: uputiti, javiti se, spustiti, staviti na čekanje, nastaviti, proslijediti i slati DTMF.
  • S tokenom u zaglavlju Authorization smije koristiti i krajnje točke koje mijenjaju ono što je spremljeno. Bez tokena te se krajnje točke ne navode na vlastitoj stranici API-ja i odgovaraju s 401. Ako token uopće nije postavljen, ništa ne može promijeniti spremljeno.

Token se čuva u spremniku ključeva računala, ne u datoteci postavki, i /settings ga nikada ne vraća.

oprez

Bez tokena bilo koji program koji radi na ovom računalu može upravljati telefonom, uključujući javljanje na pozive. Na osobnoj radnoj stanici to je obično prihvatljivo. Na zajedničkom ili upravljanom računalu postavite token i postupajte s njim kao s bilo kojom drugom lozinkom. Token štiti samo zahtjeve koji mijenjaju spremljene podatke, a ne pozive: ako druge programe želite držati podalje od poziva, isključite Pozivi i upravljanje njima pod Pristup.

Krajnje točke​

Osnovna adresa je http://127.0.0.1:8377. Krajnje točke u nastavku ne trebaju token.

MetodaPutanjaŠto radi
GET/metricsBrojači, u formatu Prometheus.
GET/uiPopis snimki, kao HTML stranica.
GET/ui/recordings/{id}Snimka s prijepisom, kao HTML stranica.
GET/ui/recordings/{id}/audioZvuk za gornju stranicu.
GET/contactsKontakti.
GET/contacts/{id}Jedan kontakt.
GET/historyZapisnik poziva, od najnovijih. Prihvaća ?limit=, ?missed=true i ?declined=true.
GET/callsPozivi u tijeku.
POST/callsUpućuje poziv: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerJavlja se na poziv.
POST/calls/{id}/hangupSpušta poziv.
POST/calls/{id}/holdStavlja poziv na čekanje.
POST/calls/{id}/resumeVraća ga s čekanja.
POST/calls/{id}/dtmfŠalje tonove: {"digits": "..."}.
POST/calls/{id}/transferProsljeđuje poziv: {"target": "..."}.
GET/accountsSIP računi i stanje njihove registracije. Nikada lozinka.
GET/settingsCijela konfiguracija, bez tajni.
GET/taxonomyKategorije, oznake i upozoravajući signali, s njihovim kodovima.

Krajnje točke kojima treba token​

One mijenjaju ono što je spremljeno, pa svaki zahtjev mora nositi token u zaglavlju Authorization. Vlastita stranica API-ja prikazuje ih samo zahtjevu koji ga nosi.

MetodaPutanjaŠto radi
POST/contactsDodaje kontakt: {"name": "...", "number": "...", "account_id": "..."}; account_id nije obavezan.
PUT/contacts/{id}Zamjenjuje kontakt.
DELETE/contacts/{id}Uklanja kontakt.
DELETE/history/{id}Zaboravlja jedan poziv iz zapisnika poziva.
DELETE/historyZaboravlja cijeli zapisnik poziva. To se ne može poništiti.
PUT/accounts/{id}Zamjenjuje postavke računa. Lozinka nije među njima.
PUT/settingsZamjenjuje postavke.

Svaki identifikator je UUID koji dodjeljuje telefon: id poziva dolazi iz /calls ili iz odgovora na POST /calls, id računa 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 vrijedi za webhookove; samo /settings ima vlastite nazive. U REST API-ju te su vrijednosti JSON brojevi, a nepoznat trenutak je null.

Primjer: upućivanje poziva​

POST /calls upućuje odlazni poziv. Tijelo je JSON s number koji treba nazvati i, po želji, account_id računa s kojeg 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 odabranom računu 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 shemu ili @ šalje se takav kakav jest.
  • account_id je neobavezan; uzmite ga iz GET /accounts. Bez njega poziv ide s računa odabranog u glavnom prozoru.
  • Koristite id u /calls/{id}/…: hangup, hold, resume, dtmf i transfer. Webhookovi ovog poziva nose isti id.

S web-stranice: klik za poziv​

Stranica koja zove 127.0.0.1 dolazi do računala na kojem radi preglednik — istog na kojem radi telefon —, pa gumb „klik za poziv” u CRM-u ne treba vlastiti poslužitelj:

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);
}

Što sadrže odgovori​

Pozivi u tijeku: 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. Kad vrijedi više od jednog, conference ima prednost pred hold, a hold pred onhold.
  • muted kaže je li mikrofon u pozivu utišan; utišavanje ne mijenja state.
  • seance_id je razgovor: pozivi povezani prosljeđivanjem, konzultacijom ili konferencijom dijele ga.
  • event_ts je trenutak kad je odgovor nastao. Usporedite ga s callstate_ts da vidite koliko je dugo poziv u svom stanju, bez oslanjanja na vlastiti sat.

Računi: GET /accounts​

Svaki račun ima svoj id (svugdje drugdje account_id), svoje postavke — transport (udp, tcp ili tls), port, registrar, outbound_proxy, expiry_s i druge —, je li enabled, i svoj state na centrali: registered dok je linija aktivna. Lozinke nikada nisu uključene.

Povijest poziva: GET /history​

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

PoljeZnačenje
idVlastiti identifikator stavke povijesti. To nije id poziva iz /calls i webhookova; 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 znamenke, za odlazni poziv; prazno za dolazni.
account, account_idLinija na kojoj je poziv bio.
reasonKako je završio: local-hangup, remote-hangup, cancelled…
answered_byno ako se javio čovjek; 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 uz liniju.

Snimke​

Snimke i prijepisi ne izdaju se kao JSON. API ih poslužuje kao HTML stranice, /ui i /ui/recordings/{id}: povezujte na te stranice iz svog CRM-a umjesto premještanja zvuka. Poveznica se otvara na računalu koje čuva snimku, a zvuk ga nikada ne napušta.

Taksonomija i postavke​

Svaka stavka /taxonomy ima stalan code, title i description na jeziku sučelja, kind (category, tag ili red_flag) i, za upozoravajuće signale, severity. Uparujte po code, nikada po title: naslovi dolaze na jeziku na koji je telefon postavljen. Stavka s retired: true zadržava se kako bi se stariji pozivi i dalje razrješavali; novim pozivima više se ne dodjeljuje. Učitajte taksonomiju jednom pri pokretanju da riječi telefona preslikate na vlastita polja.

/settings vraća konfiguraciju osim tajni: zvučne uređaje i glasnoće, prioritet kodeka, izgled i jezik, pokretanje, prečace, razinu dijagnostike i stanje obje integracije — korisno za alat podrške koji mora provjeriti radnu stanicu bez dijeljenja zaslona. api.disabled navodi isključene skupine pristupa, a webhooks.silenced isključene događaje; prazni popisi znače da je sve uključeno. Nikada ne uključuje SIP lozinku, token API-ja ni vrijednost zaglavlja webhooka.

Pogreške​

Svaka pogreška je JSON s jednim ključem error, namijenjena ljudima, a ne raščlanjivanju.

StatusTijeloZnačenje
404{"error":"no such endpoint"}Putanja ne postoji ili je njezina skupina pristupa isključena; oboje namjerno daje isti odgovor.
405{"error":"that endpoint does not take this method"}Putanja postoji, ali ne prima tu metodu: na primjer POST /settings umjesto PUT.
401{"error":"writing needs a token, and none is configured"}Krajnja točka koja mijenja spremljeno, na telefonu gdje je polje Token prazno. Ispunite ga u Lokalno upravljanje.
401{"error":"this endpoint needs the authorization token"}Krajnja točka koja mijenja spremljeno, bez ispravnog tokena.
404{"error":"no contact with that id"}Putanja je ispravna, identifikator nije.
400{"error":"no call with that id"}Poziv je 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 znamenki.
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"}Račun poziva uklonjen je tijekom poziva, pa se cilj ne može dopuniti. Centrali ništa nije poslano.

Odbijeni zahtjevi broje se u api_requests_refused_total, pa se integracija koja tiho ne uspijeva vidi u metrikama, a ne samo u vašim vlastitim zapisnicima.

Metrike​

GET /metrics vraća svaki brojač telefona, svaki s 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 netko javio.
calls_missed_totalDolazne pozive na koje se nitko nije javio.
calls_declined_totalPozive odbijene ovdje ili na drugoj strani.
calls_failed_totalPozive koji se nisu mogli uspostaviti.
registrations_succeeded_totalUspješne SIP registracije.
registrations_failed_totalSIP registracije odbijene ili istekle.
webhooks_delivered_totalWebhookove koje je primatelj prihvatio.
webhooks_failed_totalWebhookove odbijene ili neisporučene.
webhooks_dropped_totalWebhookove odbačene jer je red bio pun.
api_requests_totalZahtjeve koje je API obradio.
api_requests_refused_totalOdbijene zahtjeve: pogrešan token, isključena skupina ili nepoznata putanja.

Ažuriranje starije integracije​

Ranije inačice koristile su 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 webhooka at je event_ts. Pozivi i računi identificiraju se samo UUID-om: runtimeId i identifikatori poput call-3 ili account-2 više se ne vraćaju niti prihvaćaju.

Kad ne radi​

SimptomŠto provjeriti
Veza odbijena na 127.0.0.1:8377Lokalno upravljanje je isključeno, telefon ne radi ili je port promijenjen.
404 {"error":"no such endpoint"} za putanju s ove straniceNjezina skupina pristupa je isključena.
Čitanje radi, pisanje se odbija s 401Krajnjim točkama koje mijenjaju spremljene podatke treba token u zaglavlju Authorization, a na telefonu najprije treba ispuniti polje Token.
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 s registracijom ili samim pozivom otvorite Dijagnostiku.