Vietinis REST API
AI Softphone turi REST API CTI integracijai: tame pačiame kompiuteryje esanti programa gali atlikti ir valdyti skambučius, skaityti kontaktus, skambučių istoriją ir SIP paskyras bei stebėti vykstančius skambučius. Jokio SDK, jokio tarpininko debesyje ir jokio tinklui atverto klausytojo. Užklausos ir atsakymai yra JSON, todėl užtenka curl ar bet kurio HTTP kliento.
Įdiegus API yra išjungtas; niekas nesiklauso, kol jo neįjungiate. Tada jis klausosi tik grįžtamojo ryšio sąsajoje — nedidelė žiniatinklio sąsaja, kuri atsako tik šiam kompiuteriui — ir nėra pasiekiamas iš biuro tinklo, VPN ar kito kompiuterio.
Naudokite API, kai jūsų programai reikia duomenų iš telefono arba ji turi valdyti skambutį. Naudokite žiniatinklio kablius, kai ji turi reaguoti į skambučius jiems vykstant, nuolat neklausinėdama. Dauguma integracijų naudoja abu; jie nepriklauso vienas nuo kito.
Jo įjungimas
Atverkite Nustatymai → Integracija ir eikite į Vietinis valdymas.
- Įjunkite Leisti kitoms šio kompiuterio programoms valdyti telefoną. Serveris paleidžiamas iškart.
- Palikite numatytąjį Prievadas,
8377, nebent jį jau naudoja kita programa. - Pasirinktinai nustatykite Prieigos raktą. Išsaugojus lauke rodoma Įrašyta — rašykite, kad tai pakeistumėte.
- Skiltyje Prieiga pasirinkite atveriamas grupes: Kontaktai, Skambučių istorija, Skambučiai ir jų valdymas, Paskyros, Nustatymai, Skaitikliai (metrikos). Išjungta grupė nefiltruojama, bet visai neteikiama.
- Patikrinkite:
curl http://127.0.0.1:8377/accounts. Jei atsakymas yra JSON, API veikia.
Atskira paslauga neįdiegiama ir paleisti iš naujo nereikia. Programos dalį, kuri tai daro, galima išjungti skiltyje Moduliai (Integracija).
Paties API puslapis
Atverti paties API puslapį atveria http://127.0.0.1:8377 naršyklėje. Adresas atsako sąrašu anglų kalba su viskuo, ką jis teikia; adresai, kurie ką nors nuskaito, yra nuorodos, kuriomis galima sekti.
Prieiga ir prieigos raktas
Ką programa gali daryti, priklauso nuo to, ar ji keičia išsaugotus duomenis, o ne nuo to, ar ji skaito:
- Be prieigos rakto bet kuri kompiuterio programa gali skaityti viską įjungtose grupėse ir valdyti skambučius: skambinti, atsiliepti, padėti ragelį, sulaikyti, tęsti, peradresuoti ir siųsti DTMF.
- Su prieigos raktu antraštėje
Authorizationji taip pat gali naudoti galinius taškus, kurie keičia tai, kas išsaugota. Be prieigos rakto šie galiniai taškai nepateikiami paties API puslapyje ir atsako401. Jei prieigos raktas visai nenustatytas, niekas negali pakeisti to, kas išsaugota.
Prieigos raktas laikomas kompiuterio raktų pakete, o ne nustatymų faile, ir /settings jo niekada negrąžina.
Be prieigos rakto bet kuri šiame kompiuteryje veikianti programa gali valdyti telefoną, įskaitant atsiliepimą į skambučius. Asmeniniame darbo vietos kompiuteryje tai paprastai priimtina. Bendrai naudojamame ar administruojamame kompiuteryje nustatykite prieigos raktą ir elkitės su juo kaip su bet kuriuo kitu slaptažodžiu. Prieigos raktas saugo tik užklausas, kurios keičia saugomus duomenis, bet ne skambučius: jei norite, kad kitos programos negalėtų valdyti skambučių, skiltyje Prieiga išjunkite Skambučiai ir jų valdymas.
Galiniai taškai
Bazinis adresas yra http://127.0.0.1:8377. Toliau nurodytiems galiniams taškams prieigos rakto nereikia.
| Metodas | Kelias | Ką daro |
|---|---|---|
| GET | /metrics | Skaitikliai Prometheus formatu. |
| GET | /ui | Įrašų sąrašas kaip HTML puslapis. |
| GET | /ui/recordings/{id} | Įrašas su iššifruotu tekstu kaip HTML puslapis. |
| GET | /ui/recordings/{id}/audio | Aukščiau esančio puslapio garsas. |
| GET | /contacts | Kontaktai. |
| GET | /contacts/{id} | Vienas kontaktas. |
| GET | /history | Skambučių istorija, naujausi pirmi. Priima ?limit=, ?missed=true ir ?declined=true. |
| GET | /calls | Vykstantys skambučiai. |
| POST | /calls | Atlieka skambutį: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Atsiliepia į skambutį. |
| POST | /calls/{id}/hangup | Baigia skambutį. |
| POST | /calls/{id}/hold | Sulaiko skambutį. |
| POST | /calls/{id}/resume | Atnaujina jį. |
| POST | /calls/{id}/dtmf | Siunčia tonus: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Peradresuoja skambutį: {"target": "..."}. |
| GET | /accounts | SIP paskyros ir jų registracijos būsena. Niekada slaptažodis. |
| GET | /settings | Visa konfigūracija be paslapčių. |
| GET | /taxonomy | Kategorijos, žymos ir įspėjamieji signalai su jų kodais. |
Galiniai taškai, kuriems reikia prieigos rakto
Jie keičia tai, kas išsaugota, todėl kiekviena užklausa turi nešti prieigos raktą antraštėje Authorization. Paties API puslapis juos rodo tik užklausai, kuri jį neša.
| Metodas | Kelias | Ką daro |
|---|---|---|
| POST | /contacts | Prideda kontaktą: {"name": "...", "number": "...", "account_id": "..."}; account_id neprivalomas. |
| PUT | /contacts/{id} | Pakeičia kontaktą. |
| DELETE | /contacts/{id} | Pašalina kontaktą. |
| DELETE | /history/{id} | Pamiršta vieną skambutį iš skambučių žurnalo. |
| DELETE | /history | Pamiršta visą skambučių žurnalą. To atšaukti negalima. |
| PUT | /accounts/{id} | Pakeičia paskyros nustatymus. Slaptažodžio tarp jų nėra. |
| PUT | /settings | Pakeičia nustatymus. |
Kiekvienas identifikatorius yra telefono išduotas UUID: skambučio id gaunamas iš /calls arba iš atsakymo į POST /calls, paskyros id — iš /accounts.
Laukų pavadinimai yra snake_case formos, o galūnė nurodo tipą: _id yra nuoroda į UUID, _ts yra akimirka Unix milisekundėmis (UTC), _s yra trukmė sekundėmis. Tas pats galioja žiniatinklio kabliams; tik /settings naudoja savo pavadinimus. REST API šios reikšmės yra JSON skaičiai, o nežinoma akimirka yra null.
Pavyzdys: skambučio atlikimas
POST /calls atlieka išeinantį skambutį. Turinys yra JSON su renkamu number ir pasirinktinai paskyros, iš kurios skambinti, account_id:
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
Atsakymas yra naujo skambučio identifikatorius:
{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
numberyra privalomas. Be jo atsakymas yra400 {"error":"a call needs a number"}, ir niekas nerenkama.- Numeris papildomas pasirinktoje paskyroje taip pat, kaip jį papildo numerio rinkiklis:
1020siunčiamas kaipsip:1020@pbx.example.com.POST /calls/{id}/transferpapildo savotargettaip pat; tikslas, kuris jau turi schemą ar@, siunčiamas toks, koks yra. account_idnebūtinas; paimkite jį išGET /accounts. Be jo skambutis išeina per pagrindiniame lange pasirinktą paskyrą.- Naudokite
idkeliuose/calls/{id}/…:hangup,hold,resume,dtmfirtransfer. Šio skambučio žiniatinklio kabliai turi tą patįid.
Iš tinklalapio: spustelėk ir skambink
Puslapis, kuris kreipiasi į 127.0.0.1, pasiekia kompiuterį, kuriame veikia naršyklė — tą patį, kuriame veikia telefonas —, todėl CRM mygtukui „spustelėk ir skambink“ nereikia savo serverio:
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);
}
Ką apima atsakymai
Vykstantys skambučiai: GET /calls
Kiekvienas skambutis turi id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts ir callstate_ts.
stateyradialing,ringing-out,ringing-in,active,hold(sulaikė šis telefonas),onhold(sulaikė kita pusė),conferencearbaended. Kai tinka kelios,conferenceviršesnė užhold, ohold— užonhold.mutednurodo, ar skambutyje mikrofonas nutildytas; nutildymas nekeičiastate.seance_idyra pokalbis: skambučiai, susieti peradresavimu, konsultacija ar konferencija, jį dalijasi.event_tsyra atsakymo parengimo akimirka. Palyginkite ją sucallstate_ts, kad pamatytumėte, kiek laiko skambutis yra savo būsenoje, nesiremdami savo laikrodžiu.
Paskyros: GET /accounts
Kiekviena paskyra turi savo id (visur kitur account_id), nustatymus — transport (udp, tcp arba tls), port, registrar, outbound_proxy, expiry_s ir kitus —, ar ji enabled, ir savo state stotelėje: registered, kol linija veikia. Slaptažodžiai niekada neįtraukiami.
Skambučių istorija: GET /history
Naujausi pirmi, 100 įrašų, nebent ?limit= nurodo kitaip. ?missed=true grąžina tik praleistus skambučius, ?declined=true — tik šio telefono atmestus.
| Laukas | Reikšmė |
|---|---|
id | Paties istorijos įrašo identifikatorius. Tai ne /calls ir žiniatinklio kablių skambučio id; seance_id juos susieja. |
outcome | Pagrindinė klasifikacija: answered, missed, declined arba failed. |
answered | true arba false. |
duration_s | 0 skambučiui, kuris niekada nebuvo sujungtas. |
number, uri | Kita pusė kaip numeris ir kaip SIP adresas. |
name | Iš Kontaktų, jei numeris žinomas, kitaip tuščia. Siekite pagal number, ne pagal šį. |
dialed | Surinkti skaitmenys išeinančiam skambučiui; įeinančiam — tuščia. |
account, account_id | Linija, kuria vyko skambutis. |
reason | Kaip jis baigėsi: local-hangup, remote-hangup, cancelled… |
answered_by | no, jei atsiliepė žmogus; kitaip tai, kas atsiliepė į skambutį. |
Kontaktai: GET /contacts
Kiekvienas kontaktas turi savo id, name, number ir liniją, kuriai priklauso, account_id ir account; tuščias account reiškia, kad kontaktas nesusietas su linija.
Įrašai
Įrašai ir iššifruoti tekstai neišduodami kaip JSON. API juos teikia kaip HTML puslapius /ui ir /ui/recordings/{id}: iš savo CRM dėkite nuorodas į šiuos puslapius, užuot perkėlę garsą. Nuoroda atsiveria kompiuteryje, kuris laiko įrašą, ir garsas niekada jo nepalieka.
Taksonomija ir nustatymai
Kiekvienas /taxonomy įrašas turi pastovų code, title ir description sąsajos kalba, kind (category, tag arba red_flag) ir įspėjamiesiems signalams — severity. Siekite pagal code, niekada pagal title: pavadinimai pateikiami ta kalba, kuri nustatyta telefone. Įrašas su retired: true paliekamas, kad senesnius skambučius vis dar būtų galima susieti; naujiems skambučiams jis nebepriskiriamas. Įkelkite taksonomiją vieną kartą paleidimo metu, kad susietumėte telefono žodžius su savo laukais.
/settings grąžina konfigūraciją be paslapčių: garso įrenginius ir garsumus, kodekų prioritetą, išvaizdą ir kalbą, paleidimą, sparčiuosius klavišus, diagnostikos lygį ir abiejų integracijų būseną — naudinga pagalbos įrankiui, kuris turi patikrinti darbo vietos kompiuterį nebendrinant ekrano. api.disabled pateikia išjungtas prieigos grupes, o webhooks.silenced — išjungtus įvykius; tušti sąrašai reiškia, kad viskas įjungta. Jame niekada nėra SIP slaptažodžio, API prieigos rakto ar žiniatinklio kablio antraštės reikšmės.
Klaidos
Kiekviena klaida yra JSON su vienu raktu error, skirta žmonėms, o ne mašininiam nagrinėjimui.
| Būsena | Turinys | Reikšmė |
|---|---|---|
| 404 | {"error":"no such endpoint"} | Kelio nėra arba jo prieigos grupė išjungta; abu atvejai tyčia duoda tą patį atsakymą. |
| 405 | {"error":"that endpoint does not take this method"} | Kelias yra, bet šio metodo nepriima: pavyzdžiui, POST /settings vietoj PUT. |
| 401 | {"error":"writing needs a token, and none is configured"} | Išsaugotą turinį keičiantis galinis taškas telefone, kuriame laukas Prieigos raktas tuščias. Užpildykite jį skiltyje Vietinis valdymas. |
| 401 | {"error":"this endpoint needs the authorization token"} | Išsaugotą turinį keičiantis galinis taškas be teisingo prieigos rakto. |
| 404 | {"error":"no contact with that id"} | Kelias teisingas, identifikatorius ne. |
| 400 | {"error":"no call with that id"} | Skambutis baigėsi arba niekada neegzistavo. |
| 400 | {"error":"a call needs a number"} | POST /calls be numerio. Niekas nebuvo surinkta. |
| 400 | {"error":"no digits to send"} | POST /calls/{id}/dtmf be skaitmenų. |
| 400 | {"error":"a transfer needs a target"} | POST /calls/{id}/transfer be tikslo. |
| 400 | {"error":"the account this call is on is no longer set up"} | Skambučio paskyra pašalinta skambučio metu, todėl tikslo papildyti negalima. Stotelei nieko neišsiųsta. |
Atmestos užklausos skaičiuojamos api_requests_refused_total, todėl tyliai nepavykstanti integracija matoma metrikose, o ne tik jūsų žurnaluose.
Metrikos
GET /metrics grąžina kiekvieną telefono skaitiklį, kiekvieną su pagalbos tekstu. Rinkite juos su Prometheus arba skaitykite rankomis.
| Skaitiklis | Skaičiuoja |
|---|---|
calls_incoming_total | Gautus įeinančius skambučius. |
calls_outgoing_total | Atliktus išeinančius skambučius. |
calls_answered_total | Skambučius, į kuriuos atsiliepta. |
calls_missed_total | Įeinančius skambučius, į kuriuos neatsiliepta. |
calls_declined_total | Skambučius, atmestus čia ar kitoje pusėje. |
calls_failed_total | Skambučius, kurių nepavyko sudaryti. |
registrations_succeeded_total | Sėkmingas SIP registracijas. |
registrations_failed_total | Atmestas arba laiku nebaigtas SIP registracijas. |
webhooks_delivered_total | Gavėjo priimtus žiniatinklio kablius. |
webhooks_failed_total | Atmestus arba nepristatytus žiniatinklio kablius. |
webhooks_dropped_total | Žiniatinklio kablius, atmestus dėl pilnos eilės. |
api_requests_total | API apdorotas užklausas. |
api_requests_refused_total | Atmestas užklausas: neteisingas prieigos raktas, išjungta grupė ar nežinomas kelias. |
Senesnės integracijos atnaujinimas
Ankstesnės versijos naudojo camelCase pavadinimus ir trumpus identifikatorius. accountId dabar yra account_id, startedAt yra callstart_ts, durationSeconds yra duration_s, answeredBy yra answered_by, o žiniatinklio kablio laukas at yra event_ts. Skambučiai ir paskyros identifikuojami tik pagal UUID: runtimeId ir identifikatoriai, tokie kaip call-3 ar account-2, nebegrąžinami ir nepriimami.
Kai neveikia
| Simptomas | Ką patikrinti |
|---|---|
Ryšys atmestas adresu 127.0.0.1:8377 | Vietinis valdymas išjungtas, telefonas neveikia arba prievadas pakeistas. |
404 {"error":"no such endpoint"} šio puslapio keliui | Jo prieigos grupė išjungta. |
Skaitymas veikia, rašymas atmetamas su 401 | Išsaugotus duomenis keičiantiems galiniams taškams reikia prieigos rakto antraštėje Authorization, o telefone pirmiausia reikia užpildyti lauką Prieigos raktas. |
| Kategorijų pavadinimai ne anglų kalba | Pavadinimai seka sąsajos kalbą. Siekite pagal code iš /taxonomy. |
Trūksta accountId, startedAt arba at | Integracija parašyta ankstesniems pavadinimams; žr. aukščiau. |
Jei problema susijusi su registracija ar pačiu skambučiu, atverkite Diagnostika.