Skoči na glavno vsebino

Krajevni REST API

AI Softphone ima REST API za integracijo CTI: program na istem računalniku lahko opravlja in upravlja klice, bere stike, zgodovino klicev in račune SIP ter spremlja klice v teku. Brez SDK, brez posrednika v oblaku in brez poslušalca, izpostavljenega omrežju. Zahteve in odgovori so JSON, zato zadošča curl ali kateri koli odjemalec HTTP.

API je po namestitvi izklopljen; nič ne posluša, dokler ga ne vklopite. Nato posluša le na povratnem vmesniku — majhnem spletnem vmesniku, ki odgovarja le temu računalniku — in ni dosegljiv iz pisarniškega omrežja, VPN ali z drugega računalnika.

API uporabite, ko vaš program potrebuje podatke iz telefona ali mora upravljati klic. Webhooke uporabite, ko se mora na klice odzivati sproti, brez poizvedovanja. Večina integracij uporablja oboje; neodvisni sta drug od drugega.

Vklop​

Odprite Nastavitve → Integracija in pojdite na Krajevno upravljanje.

  1. Vklopite Dovoli drugim programom na tem računalniku upravljati telefon. Strežnik se zažene takoj.
  2. Obdržite privzeta Vrata, 8377, razen če jih že uporablja drug program.
  3. Po želji nastavite Žeton. Ko je shranjen, polje pokaže Shranjeno — pišite, da to zamenjate.
  4. Pod Dostop izberite skupine, ki jih želite odpreti: Stiki, Zgodovina klicev, Klici in njihovo upravljanje, Računi, Nastavitve, Števci (meritve). Izklopljena skupina se ne filtrira, temveč se sploh ne streže.
  5. Preizkusite: curl http://127.0.0.1:8377/accounts. Če je odgovor JSON, API deluje.

Nobena ločena storitev se ne namesti in ponovni zagon ni potreben. Del programa, ki to počne, je mogoče izklopiti v Modulih (Integracija).

Lastna stran API-ja​

Odpri lastno stran API-ja odpre http://127.0.0.1:8377 v brskalniku. Naslov odgovori s seznamom vsega, kar streže, v angleščini; naslovi, ki kaj berejo, so povezave, ki jim lahko sledite.

Dostop in žeton​

Kaj program sme, je odvisno od tega, ali spreminja shranjene podatke, ne od tega, ali bere:

  • Brez žetona lahko kateri koli program na računalniku bere vse v vklopljenih skupinah in upravlja klice: opravi, sprejme, odloži, zadrži, nadaljuje, preusmeri in pošlje DTMF.
  • Z žetonom v glavi Authorization lahko uporablja tudi končne točke, ki spreminjajo, kar je shranjeno. Brez žetona te končne točke niso navedene na lastni strani API-ja in odgovorijo z 401. Če žeton sploh ni nastavljen, shranjenega ne more spremeniti nič.

Žeton se hrani v shrambi ključev računalnika, ne v datoteki z nastavitvami, in ga /settings nikoli ne vrne.

previdno

Brez žetona lahko kateri koli program, ki teče na tem računalniku, upravlja telefon, vključno s sprejemanjem klicev. Na osebni delovni postaji je to običajno sprejemljivo. Na skupnem ali upravljanem računalniku nastavite žeton in z njim ravnajte kot s katerim koli drugim geslom. Žeton ščiti samo zahteve, ki spreminjajo shranjene podatke, ne pa klicev: če želite druge programe držati stran od klicev, pod Dostop izklopite Klici in njihovo upravljanje.

Končne točke​

Osnovni naslov je http://127.0.0.1:8377. Spodnje končne točke ne potrebujejo žetona.

MetodaPotKaj naredi
GET/metricsŠtevci v formatu Prometheus.
GET/uiSeznam posnetkov kot stran HTML.
GET/ui/recordings/{id}Posnetek s prepisom kot stran HTML.
GET/ui/recordings/{id}/audioZvok za zgornjo stran.
GET/contactsStiki.
GET/contacts/{id}En stik.
GET/historyDnevnik klicev, od najnovejših. Sprejme ?limit=, ?missed=true in ?declined=true.
GET/callsKlici v teku.
POST/callsOpravi klic: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerSprejme klic.
POST/calls/{id}/hangupOdloži klic.
POST/calls/{id}/holdZadrži klic.
POST/calls/{id}/resumeGa nadaljuje.
POST/calls/{id}/dtmfPošlje tone: {"digits": "..."}.
POST/calls/{id}/transferPreusmeri klic: {"target": "..."}.
GET/accountsRačuni SIP in stanje njihove registracije. Nikoli geslo.
GET/settingsCelotna konfiguracija, brez skrivnosti.
GET/taxonomyKategorije, oznake in opozorilni znaki z njihovimi kodami.

Končne točke, ki potrebujejo žeton​

Spreminjajo, kar je shranjeno, zato mora vsaka zahteva nositi žeton v glavi Authorization. Lastna stran API-ja jih pokaže le zahtevi, ki ga nosi.

MetodaPotKaj naredi
POST/contactsDoda stik: {"name": "...", "number": "...", "account_id": "..."}; account_id ni obvezen.
PUT/contacts/{id}Zamenja stik.
DELETE/contacts/{id}Odstrani stik.
DELETE/history/{id}Pozabi en klic iz dnevnika klicev.
DELETE/historyPozabi ves dnevnik klicev. Tega ni mogoče razveljaviti.
PUT/accounts/{id}Zamenja nastavitve računa. Gesla med njimi ni.
PUT/settingsZamenja nastavitve.

Vsak identifikator je UUID, ki ga dodeli telefon: id klica pride iz /calls ali iz odgovora na POST /calls, id računa iz /accounts.

Imena polj so v snake_case, končnica pa pove vrsto: _id je sklic na UUID, _ts je trenutek v milisekundah Unix (UTC), _s je trajanje v sekundah. Enako velja za webhooke; le /settings ima svoja imena. V REST API-ju so te vrednosti števila JSON, neznan trenutek pa je null.

Primer: opravljanje klica​

POST /calls opravi odhodni klic. Telo je JSON s number, ki naj se pokliče, in po želji z account_id računa, s katerega naj se kliče:

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 novega klica:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number je obvezen. Brez njega je odgovor 400 {"error":"a call needs a number"} in nič se ne pokliče.
  • Številka se na izbranem računu dopolni tako, kot jo dopolni polje za klicanje: 1020 se pošlje kot sip:1020@pbx.example.com. POST /calls/{id}/transfer svoj target dopolni enako; cilj, ki že ima shemo ali @, se pošlje, kakršen je.
  • account_id je neobvezen; vzemite ga iz GET /accounts. Brez njega gre klic z računa, izbranega v glavnem oknu.
  • Uporabite id v /calls/{id}/…: hangup, hold, resume, dtmf in transfer. Webhooki tega klica nosijo isti id.

S spletne strani: klik za klic​

Stran, ki kliče 127.0.0.1, doseže računalnik, na katerem teče brskalnik — isti, na katerem teče telefon —, zato gumb »klik za klic« v CRM ne potrebuje lastnega strežnika:

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

Kaj vsebujejo odgovori​

Klici v teku: GET /calls​

Vsak klic ima svoj id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts in callstate_ts.

  • state je dialing, ringing-out, ringing-in, active, hold (zadržal ta telefon), onhold (zadržala druga stran), conference ali ended. Ko velja več kot eno, ima conference prednost pred hold, hold pa pred onhold.
  • muted pove, ali je mikrofon v klicu utišan; utišanje ne spremeni state.
  • seance_id je pogovor: klici, povezani s preusmeritvijo, posvetom ali konferenco, ga imajo skupnega.
  • event_ts je trenutek, ko je bil odgovor narejen. Primerjajte ga s callstate_ts, da vidite, kako dolgo je klic v svojem stanju, ne da bi se zanašali na svojo uro.

Računi: GET /accounts​

Vsak račun ima svoj id (povsod drugje account_id), svoje nastavitve — transport (udp, tcp ali tls), port, registrar, outbound_proxy, expiry_s in druge —, ali je enabled, in svoj state na centrali: registered, dokler je linija aktivna. Gesla niso nikoli vključena.

Zgodovina klicev: GET /history​

Od najnovejših, 100 vnosov, razen če ?limit= pravi drugače. ?missed=true vrne le zgrešene klice, ?declined=true le klice, ki jih je ta telefon zavrnil.

PoljePomen
idLastni identifikator vnosa zgodovine. To ni id klica iz /calls in webhookov; povezuje ju seance_id.
outcomeGlavna razvrstitev: answered, missed, declined ali failed.
answeredtrue ali false.
duration_s0 za klic, ki ni bil nikoli vzpostavljen.
number, uriDruga stran, kot številka in kot naslov SIP.
nameIz Stikov, če je številka znana, drugače prazno. Ujemajte po number, ne po tem.
dialedPoklicane števke, pri odhodnem klicu; pri dohodnem prazno.
account, account_idLinija, na kateri je bil klic.
reasonKako se je končal: local-hangup, remote-hangup, cancelled…
answered_byno, če ga je sprejel človek; drugače to, kar je sprejelo klic.

Stiki: GET /contacts​

Vsak stik ima svoj id, name, number in linijo, ki ji pripada, account_id in account; prazen account pomeni, da stik ni vezan na linijo.

Posnetki​

Posnetki in prepisi se ne izdajajo kot JSON. API jih streže kot strani HTML, /ui in /ui/recordings/{id}: iz svojega CRM povezujte na te strani, namesto da premikate zvok. Povezava se odpre na računalniku, ki hrani posnetek, zvok pa ga nikoli ne zapusti.

Taksonomija in nastavitve​

Vsak vnos /taxonomy ima stalno code, title in description v jeziku vmesnika, kind (category, tag ali red_flag) in pri opozorilnih znakih severity. Ujemajte po code, nikoli po title: naslovi pridejo v jeziku, na katerega je nastavljen telefon. Vnos z retired: true se ohrani, da se starejši klici še vedno razrešijo; novim klicem se ne dodeljuje več. Taksonomijo naložite enkrat ob zagonu, da besede telefona preslikate na svoja polja.

/settings vrne konfiguracijo razen skrivnosti: zvočne naprave in glasnosti, prednost kodekov, videz in jezik, zagon, bližnjice, raven diagnostike in stanje obeh integracij — uporabno za orodje podpore, ki mora preveriti delovno postajo brez deljenja zaslona. api.disabled navaja izklopljene skupine dostopa, webhooks.silenced pa izklopljene dogodke; prazni seznami pomenijo, da je vse vklopljeno. Nikoli ne vsebuje gesla SIP, žetona API-ja ali vrednosti glave webhooka.

Napake​

Vsaka napaka je JSON z enim samim ključem error, namenjena ljudem, ne razčlenjevanju.

StanjeTeloPomen
404{"error":"no such endpoint"}Pot ne obstaja ali je njena skupina dostopa izklopljena; oboje namerno da enak odgovor.
405{"error":"that endpoint does not take this method"}Pot obstaja, a te metode ne sprejme: na primer POST /settings namesto PUT.
401{"error":"writing needs a token, and none is configured"}Končna točka, ki spreminja shranjeno, na telefonu, kjer je polje Žeton prazno. Izpolnite ga v Krajevno upravljanje.
401{"error":"this endpoint needs the authorization token"}Končna točka, ki spreminja shranjeno, brez pravega žetona.
404{"error":"no contact with that id"}Pot je pravilna, identifikator ne.
400{"error":"no call with that id"}Klic se je končal ali ni nikoli obstajal.
400{"error":"a call needs a number"}POST /calls brez številke. Nič ni bilo poklicano.
400{"error":"no digits to send"}POST /calls/{id}/dtmf brez števk.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer brez cilja.
400{"error":"the account this call is on is no longer set up"}Račun klica je bil med klicem odstranjen, zato cilja ni mogoče dopolniti. Centrali ni bilo nič poslano.

Zavrnjene zahteve se štejejo v api_requests_refused_total, zato je integracija, ki tiho odpove, vidna v meritvah, ne le v vaših lastnih dnevnikih.

Meritve​

GET /metrics vrne vsak števec telefona, vsakega z besedilom pomoči. Zbirajte jih s Prometheusom ali jih berite ročno.

ŠtevecŠteje
calls_incoming_totalPrejete dohodne klice.
calls_outgoing_totalOpravljene odhodne klice.
calls_answered_totalKlice, ki so bili sprejeti.
calls_missed_totalDohodne klice, ki niso bili sprejeti.
calls_declined_totalKlice, zavrnjene tukaj ali z druge strani.
calls_failed_totalKlice, ki jih ni bilo mogoče vzpostaviti.
registrations_succeeded_totalUspešne registracije SIP.
registrations_failed_totalRegistracije SIP, zavrnjene ali s potekom časa.
webhooks_delivered_totalWebhooke, ki jih je prejemnik sprejel.
webhooks_failed_totalWebhooke, zavrnjene ali nedostavljene.
webhooks_dropped_totalWebhooke, zavržene, ker je bila vrsta polna.
api_requests_totalZahteve, ki jih je obdelal API.
api_requests_refused_totalZavrnjene zahteve: napačen žeton, izklopljena skupina ali neznana pot.

Posodobitev starejše integracije​

Prejšnje različice so uporabljale imena v camelCase in kratke identifikatorje. accountId je zdaj account_id, startedAt je callstart_ts, durationSeconds je duration_s, answeredBy je answered_by, polje webhooka at pa je event_ts. Klici in računi se identificirajo samo z UUID: runtimeId in identifikatorji, kot sta call-3 ali account-2, se ne vračajo in ne sprejemajo več.

Ko ne deluje​

SimptomKaj preveriti
Povezava zavrnjena na 127.0.0.1:8377Krajevno upravljanje je izklopljeno, telefon ne teče ali so bila vrata spremenjena.
404 {"error":"no such endpoint"} za pot s te straniNjena skupina dostopa je izklopljena.
Branje deluje, pisanje je zavrnjeno z 401Končne točke, ki spreminjajo shranjene podatke, potrebujejo žeton v glavi Authorization, na telefonu pa je treba najprej izpolniti polje Žeton.
Naslovi kategorij niso v angleščiniNaslovi sledijo jeziku vmesnika. Ujemajte po code iz /taxonomy.
Manjkajo accountId, startedAt ali atIntegracija je bila napisana za prejšnja imena; glejte zgoraj.

Pri težavi z registracijo ali samim klicem odprite Diagnostiko.