Mine põhisisu juurde

Kohalik REST API

AI Softphone'il on CTI-sidumiseks REST API: samas arvutis olev programm saab teha ja juhtida kõnesid, lugeda kontakte, kõnede ajalugu ja SIP-kontosid ning jälgida pooleliolevaid kõnesid. Pole SDK-d, pilves vahendajat ega võrku avatud kuulajat. Päringud ja vastused on JSON, nii et piisab curl-ist või mis tahes HTTP-kliendist.

API on pärast paigaldamist väljas; miski ei kuula, kuni te selle sisse lülitate. Seejärel kuulab see ainult tagasisilmuse liidesel — väike veebiliides, mis vastab ainult sellele arvutile — ning sellele ei pääse ligi kontorivõrgust, VPN-ist ega teisest masinast.

Kasutage API-t, kui teie programm vajab telefonilt andmeid või peab kõnet juhtima. Kasutage veebikonkse, kui see peab reageerima kõnedele nende toimumise ajal ilma pideva küsitlemiseta. Enamik sidumisi kasutab mõlemat; need on teineteisest sõltumatud.

Selle sisselülitamine​

Avage Seaded → Sidumine ja minge jaotisse Kohalik juhtimine.

  1. Lülitage sisse Luba teistel selle arvuti programmidel telefoni juhtida. Server käivitub kohe.
  2. Jätke vaikimisi Port, 8377, kui mõni teine programm seda juba ei kasuta.
  3. Soovi korral määrake Märgis. Pärast salvestamist näitab väli teksti Salvestatud — kirjutage, et see asendada.
  4. Valige jaotises Juurdepääs avatavad rühmad: Kontaktid, Kõnede ajalugu, Kõned ja nende juhtimine, Kontod, Seaded, Loendurid (mõõdikud). Väljalülitatud rühma ei filtreerita, vaid seda ei pakuta üldse.
  5. Proovige: curl http://127.0.0.1:8377/accounts. Kui vastus on JSON, API töötab.

Eraldi teenust ei paigaldata ja taaskäivitust pole vaja. Seda tegeva programmi osa saab välja lülitada jaotises Moodulid (Sidumine).

API enda leht​

Ava API enda leht avab brauseris aadressi http://127.0.0.1:8377. Aadress vastab ingliskeelse loendiga kõigest, mida see pakub; midagi lugevad aadressid on lingid, mida saab avada.

Juurdepääs ja märgis​

See, mida programm teha tohib, sõltub sellest, kas see muudab talletatud andmeid, mitte sellest, kas see loeb:

  • Ilma märgiseta võib iga arvutis olev programm lugeda kõike sisselülitatud rühmades ja juhtida kõnesid: helistada, vastata, lõpetada, ootele panna, jätkata, ümber suunata ja saata DTMF-i.
  • Märgisega päises Authorization võib see kasutada ka lõpp-punkte, mis muudavad talletatut. Ilma märgiseta neid lõpp-punkte API enda lehel ei loetleta ja need vastavad 401. Kui märgist pole üldse seatud, ei saa miski talletatut muuta.

Märgist hoitakse arvuti võtmehoidjas, mitte seadete failis, ja /settings ei tagasta seda kunagi.

ettevaatust

Ilma märgiseta saab iga selles arvutis töötav programm telefoni juhtida, sealhulgas kõnedele vastata. Isiklikus tööjaamas on see tavaliselt vastuvõetav. Jagatud või hallatud masinas määrake märgis ja käsitlege seda nagu iga teist parooli. Märgis kaitseb ainult päringuid, mis muudavad salvestatud andmeid, mitte kõnesid: kui soovite teisi programme kõnedest eemal hoida, lülitage jaotises Juurdepääs välja Kõned ja nende juhtimine.

Lõpp-punktid​

Baasaadress on http://127.0.0.1:8377. Allolevad lõpp-punktid ei vaja märgist.

MeetodTeeMida teeb
GET/metricsLoendurid Prometheuse vormingus.
GET/uiSalvestiste loend HTML-lehena.
GET/ui/recordings/{id}Salvestis koos ülestähendusega HTML-lehena.
GET/ui/recordings/{id}/audioÜlaltoodud lehe heli.
GET/contactsKontaktid.
GET/contacts/{id}Üks kontakt.
GET/historyKõnede ajalugu, uusim eespool. Aktsepteerib ?limit=, ?missed=true ja ?declined=true.
GET/callsPooleliolevad kõned.
POST/callsTeeb kõne: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerVastab kõnele.
POST/calls/{id}/hangupLõpetab kõne.
POST/calls/{id}/holdPaneb kõne ootele.
POST/calls/{id}/resumeVõtab selle ootelt maha.
POST/calls/{id}/dtmfSaadab toone: {"digits": "..."}.
POST/calls/{id}/transferSuunab kõne ümber: {"target": "..."}.
GET/accountsSIP-kontod ja nende registreerimisolek. Mitte kunagi parooli.
GET/settingsKogu konfiguratsioon ilma saladusteta.
GET/taxonomyKategooriad, sildid ja hoiatussignaalid koos koodidega.

Lõpp-punktid, mis vajavad märgist​

Need muudavad talletatut, seega peab iga päring kandma märgist päises Authorization. API enda leht näitab neid ainult päringule, mis seda kannab.

MeetodTeeMida teeb
POST/contactsLisab kontakti: {"name": "...", "number": "...", "account_id": "..."}; account_id ei ole kohustuslik.
PUT/contacts/{id}Asendab kontakti.
DELETE/contacts/{id}Eemaldab kontakti.
DELETE/history/{id}Unustab kõnelogist ühe kõne.
DELETE/historyUnustab kogu kõnelogi. Seda ei saa tagasi võtta.
PUT/accounts/{id}Asendab konto seaded. Parooli nende hulgas ei ole.
PUT/settingsAsendab seaded.

Iga identifikaator on telefoni väljastatud UUID: kõne id tuleb /calls kaudu või vastusest päringule POST /calls, konto id /accounts kaudu.

Väljanimed on snake_case-kujul ja lõpp näitab tüüpi: _id on viide UUID-le, _ts on hetk Unixi millisekundites (UTC), _s on kestus sekundites. Sama kehtib veebikonksude kohta; ainult /settings kasutab oma nimesid. REST API-s on need väärtused JSON-numbrid ja teadmata hetk on null.

Näide: kõne tegemine​

POST /calls teeb väljamineva kõne. Sisu on JSON, milles on valitav number ja soovi korral selle konto account_id, millelt helistada:

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

Vastus on uue kõne identifikaator:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number on kohustuslik. Ilma selleta on vastus 400 {"error":"a call needs a number"} ja midagi ei valita.
  • Number täiendatakse valitud kontol samamoodi, nagu valija seda teeb: 1020 saadetakse kujul sip:1020@pbx.example.com. POST /calls/{id}/transfer täiendab oma target samamoodi; siht, millel on juba skeem või @, saadetakse muutmata.
  • account_id on valikuline; võtke see GET /accounts kaudu. Ilma selleta läheb kõne välja peaaknas valitud kontolt.
  • Kasutage id teedes /calls/{id}/…: hangup, hold, resume, dtmf ja transfer. Selle kõne veebikonksudel on sama id.

Veebilehelt: klõpsa ja helista​

Leht, mis pöördub aadressi 127.0.0.1 poole, jõuab arvutini, kus brauser töötab — sama, kus töötab telefon —, nii et CRM-i klõpsa-ja-helista nupp ei vaja oma serverit:

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

Mida vastused sisaldavad​

Pooleliolevad kõned: GET /calls​

Igal kõnel on id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts ja callstate_ts.

  • state on dialing, ringing-out, ringing-in, active, hold (selle telefoni poolt ootele pandud), onhold (teise osapoole poolt ootele pandud), conference või ended. Kui kehtib mitu, on conference tähtsam kui hold ja hold tähtsam kui onhold.
  • muted ütleb, kas mikrofon on kõnes vaigistatud; vaigistamine state väärtust ei muuda.
  • seance_id on vestlus: ümbersuunamise, konsultatsiooni või konverentsiga seotud kõned jagavad seda.
  • event_ts on vastuse koostamise hetk. Võrrelge seda callstate_ts väärtusega, et näha, kui kaua kõne on oma olekus olnud, ilma oma kellale toetumata.

Kontod: GET /accounts​

Igal kontol on id (mujal account_id), selle seaded — transport (udp, tcp või tls), port, registrar, outbound_proxy, expiry_s ja teised —, kas see on enabled, ning selle state keskjaamas: registered, kui liin töötab. Paroole ei kaasata kunagi.

Kõnede ajalugu: GET /history​

Uusim eespool, 100 kirjet, kui ?limit= ei ütle teisiti. ?missed=true tagastab ainult vastamata kõned, ?declined=true ainult selle telefoni poolt tagasi lükatud kõned.

VäliTähendus
idAjaloo kirje enda identifikaator. See ei ole /calls ja veebikonksude kõne id; seance_id seob need kaks.
outcomePõhiliigitus: answered, missed, declined või failed.
answeredtrue või false.
duration_s0 kõne puhul, mis ei saanud kunagi ühendust.
number, uriTeine osapool numbri ja SIP-aadressina.
nameKontaktidest, kui number on teada, muidu tühi. Siduge number järgi, mitte selle järgi.
dialedValitud numbrid väljamineva kõne puhul; sissetuleva puhul tühi.
account, account_idLiin, millel kõne oli.
reasonKuidas see lõppes: local-hangup, remote-hangup, cancelled…
answered_byno, kui vastas inimene; muul juhul see, mis kõnele vastas.

Kontaktid: GET /contacts​

Igal kontaktil on id, name, number ja liin, kuhu see kuulub, account_id ja account; tühi account tähendab, et kontakt ei ole liiniga seotud.

Salvestised​

Salvestisi ja ülestähendusi JSON-ina ei väljastata. API pakub neid HTML-lehtedena /ui ja /ui/recordings/{id}: linkige oma CRM-ist nendele lehtedele, selle asemel et heli liigutada. Link avaneb arvutis, kus salvestist hoitakse, ja heli ei lahku sealt kunagi.

Taksonoomia ja seaded​

Igal /taxonomy kirjel on püsiv code, kasutajaliidese keeles title ja description, kind (category, tag või red_flag) ning hoiatussignaalidel severity. Siduge code järgi, mitte kunagi title järgi: pealkirjad tulevad keeles, mis telefonis on määratud. Kirjet, millel on retired: true, hoitakse alles, et vanemaid kõnesid saaks endiselt lahendada; uutele kõnedele seda enam ei anta. Laadige taksonoomia käivitamisel üks kord, et siduda telefoni sõnad oma väljadega.

/settings tagastab konfiguratsiooni ilma saladusteta: heliseadmed ja helitugevused, koodekite prioriteet, välimus ja keel, käivitumine, otseteed, diagnostikatase ja mõlema sidumise olek — kasulik tugitööriistale, mis peab tööjaama kontrollima ilma ekraani jagamata. api.disabled loetleb väljalülitatud juurdepääsurühmad ja webhooks.silenced väljalülitatud sündmused; tühjad loendid tähendavad, et kõik on sees. See ei sisalda kunagi SIP-parooli, API märgist ega veebikonksu päise väärtust.

Vead​

Iga viga on JSON ühe võtmega error, mõeldud inimestele, mitte masinaga parsimiseks.

OlekSisuTähendus
404{"error":"no such endpoint"}Teed ei ole või selle juurdepääsurühm on väljas; mõlemad annavad meelega sama vastuse.
405{"error":"that endpoint does not take this method"}Tee on olemas, aga seda meetodit ei võta: näiteks POST /settings PUT-i asemel.
401{"error":"writing needs a token, and none is configured"}Talletatut muutev lõpp-punkt telefonis, kus väli Märgis on tühi. Täitke see jaotises Kohalik juhtimine.
401{"error":"this endpoint needs the authorization token"}Talletatut muutev lõpp-punkt ilma õige märgiseta.
404{"error":"no contact with that id"}Tee on õige, identifikaator mitte.
400{"error":"no call with that id"}Kõne on lõppenud või seda pole kunagi olnud.
400{"error":"a call needs a number"}POST /calls ilma numbrita. Midagi ei valitud.
400{"error":"no digits to send"}POST /calls/{id}/dtmf ilma numbriteta.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer ilma sihita.
400{"error":"the account this call is on is no longer set up"}Kõne konto eemaldati kõne ajal, nii et sihti ei saa täiendada. Keskjaamale ei saadetud midagi.

Tagasi lükatud päringud loetakse loendurisse api_requests_refused_total, nii et vaikselt ebaõnnestuv sidumine paistab mõõdikutes, mitte ainult teie enda logides.

Mõõdikud​

GET /metrics tagastab iga telefoni loenduri koos abitekstiga. Koguge neid Prometheusega või lugege käsitsi.

LoendurLoendab
calls_incoming_totalVastu võetud sissetulevad kõned.
calls_outgoing_totalTehtud väljaminevad kõned.
calls_answered_totalKõned, millele vastati.
calls_missed_totalSissetulevad kõned, millele ei vastatud.
calls_declined_totalSiin või teise poole poolt tagasi lükatud kõned.
calls_failed_totalKõned, mida ei õnnestunud luua.
registrations_succeeded_totalÕnnestunud SIP-registreerimised.
registrations_failed_totalTagasi lükatud või aegunud SIP-registreerimised.
webhooks_delivered_totalVastuvõtja poolt aktsepteeritud veebikonksud.
webhooks_failed_totalTagasi lükatud või kohale toimetamata veebikonksud.
webhooks_dropped_totalVeebikonksud, mis jäeti välja, sest järjekord oli täis.
api_requests_totalAPI poolt töödeldud päringud.
api_requests_refused_totalTagasi lükatud päringud: vale märgis, rühm väljas või tundmatu tee.

Vanema sidumise uuendamine​

Varasemad versioonid kasutasid camelCase-nimesid ja lühikesi identifikaatoreid. accountId on nüüd account_id, startedAt on callstart_ts, durationSeconds on duration_s, answeredBy on answered_by ja veebikonksu väli at on event_ts. Kõnesid ja kontosid tuvastatakse ainult UUID järgi: runtimeId ja identifikaatoreid nagu call-3 või account-2 enam ei tagastata ega aktsepteerita.

Kui see ei tööta​

SümptomMida kontrollida
Ühendusest keelduti aadressil 127.0.0.1:8377Kohalik juhtimine on väljas, telefon ei tööta või porti on muudetud.
404 {"error":"no such endpoint"} selle lehe teeleSelle juurdepääsurühm on väljas.
Lugemine töötab, kirjutamine lükatakse tagasi koodiga 401Talletatud andmeid muutvad lõpp-punktid vajavad märgist päises Authorization ja telefonis tuleb esmalt täita väli Märgis.
Kategooriate pealkirjad ei ole inglise keelesPealkirjad järgivad kasutajaliidese keelt. Siduge /taxonomy välja code järgi.
accountId, startedAt või at puuduvadSidumine kirjutati varasemate nimede jaoks; vaadake ülalt.

Registreerimise või kõne enda probleemi korral avage Diagnostika.