Ugrás a fő tartalomra

Helyi REST API

Az AI Softphone CTI-integrációhoz REST API-val rendelkezik: egy ugyanazon a számítógépen futó program hívásokat indíthat és kezelhet, lekérdezheti a névjegyeket, a hívásnaplót és a SIP-fiókokat, és figyelheti a folyamatban lévő hívásokat. Nincs SDK, nincs felhőbeli közvetítő, és nincs a hálózat felé nyitott figyelő. A kérések és a válaszok JSON formátumúak, így a curl vagy bármely HTTP-kliens elegendő.

Az API a telepítés után ki van kapcsolva; semmi sem figyel, amíg be nem kapcsolja. Ezután is csak a loopback felületen figyel — egy kis webes felület, amely csak ennek a számítógépnek válaszol —, és nem érhető el az irodai hálózatról, VPN-ről vagy egy másik gépről.

Az API-t akkor használja, ha a programjának adatokra van szüksége a telefonból, vagy egy hívást kell vezérelnie. A webhookokat akkor használja, ha a hívásokra azok történése közben kell reagálnia, lekérdezgetés nélkül. A legtöbb integráció mindkettőt használja; egymástól függetlenek.

Bekapcsolás​

Nyissa meg a Beállítások → Integráció lapot, és lépjen a Helyi vezérlés részhez.

  1. Kapcsolja be A számítógép más programjai vezérelhessék a telefont lehetőséget. A kiszolgáló azonnal elindul.
  2. Tartsa meg az alapértelmezett Port értéket, a 8377-et, hacsak egy másik program már nem használja.
  3. Ha szeretné, állítson be egy Token értéket. Mentés után a mezőben az Elmentve — írjon, hogy lecserélje felirat látható.
  4. A Hozzáférés alatt válassza ki a megnyitandó csoportokat: Névjegyek, Hívásnapló, Hívások és azok kezelése, Fiókok, Beállítások, Számlálók (a mérőszámok). A kikapcsolt csoport nem szűrve van, hanem egyáltalán nem szolgálja ki a program.
  5. Próbálja ki: curl http://127.0.0.1:8377/accounts. Ha a válasz JSON, az API működik.

Nem kell külön szolgáltatást telepíteni, és újraindításra sincs szükség. A program ezt végző része a Modulok között kikapcsolható (Integráció).

Az API saját oldala​

Az API saját oldalának megnyitása böngészőben megnyitja a http://127.0.0.1:8377 címet. A cím angol nyelvű listával válaszol mindarról, amit kiszolgál; az olvasó címek követhető hivatkozások.

Hozzáférés és a token​

Hogy egy program mit tehet, az attól függ, hogy módosít-e tárolt adatokat, nem attól, hogy olvas-e:

  • Token nélkül a számítógép bármely programja mindent olvashat az engedélyezett csoportokban, és vezérelheti a hívásokat: indíthat, fogadhat, bonthat, tartásba tehet, folytathat, átadhat és DTMF-et küldhet.
  • A tokennel az Authorization fejlécben azokat a végpontokat is használhatja, amelyek a tárolt adatokat módosítják. Token nélkül ezek a végpontok nem szerepelnek az API saját oldalán, és 401-gyel válaszolnak. Ha egyáltalán nincs token beállítva, semmi sem módosíthatja a tárolt adatokat.

A tokent a számítógép kulcstartója őrzi, nem a beállításfájl, és a /settings soha nem adja vissza.

figyelem

Token nélkül a számítógépen futó bármely program vezérelheti a telefont, a hívások fogadását is beleértve. Egy személyes munkaállomáson ez általában elfogadható. Egy közös vagy központilag felügyelt gépen állítson be tokent, és kezelje úgy, mint bármely más jelszót. A token csak a tárolt adatokat módosító kéréseket védi, a hívásokat nem: ha más programokat távol szeretne tartani a hívásoktól, kapcsolja ki a(z) Hívások és azok kezelése csoportot a Hozzáférés alatt.

Végpontok​

Az alapcím http://127.0.0.1:8377. Az alábbi végpontokhoz nem kell token.

MódszerÚtvonalMit csinál
GET/metricsA számlálók Prometheus formátumban.
GET/uiA felvételek listája HTML-oldalként.
GET/ui/recordings/{id}Egy felvétel a leiratával, HTML-oldalként.
GET/ui/recordings/{id}/audioA fenti oldal hanganyaga.
GET/contactsA névjegyek.
GET/contacts/{id}Egyetlen névjegy.
GET/historyA hívásnapló, a legújabbal kezdve. Elfogadja a ?limit=, ?missed=true és ?declined=true paramétert.
GET/callsA folyamatban lévő hívások.
POST/callsHívást indít: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerFogad egy hívást.
POST/calls/{id}/hangupBont egy hívást.
POST/calls/{id}/holdTartásba tesz egy hívást.
POST/calls/{id}/resumeVisszaveszi a tartásból.
POST/calls/{id}/dtmfHangokat küld: {"digits": "..."}.
POST/calls/{id}/transferÁtadja a hívást: {"target": "..."}.
GET/accountsA SIP-fiókok és regisztrációs állapotuk. Jelszót soha.
GET/settingsA teljes konfiguráció, a titkos adatok nélkül.
GET/taxonomyKategóriák, címkék és figyelmeztető jelek, a kódjaikkal.

A tokent igénylő végpontok​

Ezek a tárolt adatokat módosítják, ezért minden kérésnek vinnie kell a tokent az Authorization fejlécben. Az API saját oldala csak olyan kérésnek mutatja őket, amely viszi.

MódszerÚtvonalMit csinál
POST/contactsHozzáad egy névjegyet: {"name": "...", "number": "...", "account_id": "..."}; az account_id nem kötelező.
PUT/contacts/{id}Lecserél egy névjegyet.
DELETE/contacts/{id}Eltávolít egy névjegyet.
DELETE/history/{id}Elfelejt egy hívást a hívásnaplóból.
DELETE/historyElfelejti az egész hívásnaplót. Nem vonható vissza.
PUT/accounts/{id}Lecseréli egy fiók beállításait. A jelszó nincs köztük.
PUT/settingsLecseréli a beállításokat.

Minden azonosító a telefon által kiadott UUID: a hívás id értéke a /calls végpontból vagy a POST /calls válaszából származik, a fiók id értéke a /accounts végpontból.

A mezőnevek snake_case formájúak, a végződésük pedig a típust jelzi: az _id egy UUID-ra mutató hivatkozás, a _ts egy időpont Unix-ezredmásodpercben (UTC), az _s másodpercben megadott hossz. Ugyanez érvényes a webhookokra is; csak a /settings használ saját neveket. A REST API-ban ezek az értékek JSON-számok, az ismeretlen időpont pedig null.

Példa: hívás indítása​

A POST /calls kimenő hívást indít. A törzs JSON, amely a tárcsázandó number értéket és — nem kötelezően — annak a fióknak az account_id azonosítóját tartalmazza, amelyről a hívás indul:

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

A válasz az új hívás azonosítója:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • A number kötelező. Nélküle a válasz 400 {"error":"a call needs a number"}, és semmi sem kerül tárcsázásra.
  • A számot a program a kiválasztott fiókon ugyanúgy egészíti ki, ahogyan a tárcsázó: az 1020 sip:1020@pbx.example.com formában megy ki. A POST /calls/{id}/transfer ugyanígy egészíti ki a target értékét; az a cél, amelyben már van séma vagy @, változatlanul megy ki.
  • Az account_id nem kötelező; a GET /accounts válaszából veheti. Nélküle a hívás a főablakban kiválasztott fiókon megy ki.
  • Az id értéket a /calls/{id}/… végpontokban használja: hangup, hold, resume, dtmf és transfer. A hívás webhookjai ugyanezt az id értéket hordozzák.

Weboldalról: kattintásos hívás​

Az a weboldal, amely a 127.0.0.1 címet hívja, azt a számítógépet éri el, amelyen a böngésző fut — ugyanazt, amelyen a telefon is —, így egy CRM-ben lévő kattintásos hívás gombhoz nem kell saját kiszolgáló:

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

Mit tartalmaznak a válaszok​

Folyamatban lévő hívások: GET /calls​

Minden hívásnak van id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts és callstate_ts mezője.

  • A state értéke dialing, ringing-out, ringing-in, active, hold (ez a telefon tette tartásba), onhold (a másik fél tette tartásba), conference vagy ended. Ha több is érvényes, a conference elsőbbséget élvez a hold előtt, a hold pedig az onhold előtt.
  • A muted megmondja, hogy a mikrofon némítva van-e a hívásban; a némítás nem változtatja meg a state értékét.
  • A seance_id a beszélgetés: az átadással, konzultációval vagy konferenciával összekapcsolt hívások osztoznak rajta.
  • Az event_ts a válasz elkészítésének időpontja. Vesse össze a callstate_ts értékkel, hogy lássa, mióta van a hívás az adott állapotban, anélkül hogy a saját órájára hagyatkozna.

Fiókok: GET /accounts​

Minden fióknak megvan az id azonosítója (máshol account_id), a beállításai — transport (udp, tcp vagy tls), port, registrar, outbound_proxy, expiry_s és mások —, az, hogy enabled-e, valamint a state állapota az alközponton: registered, amíg a vonal él. Jelszavakat soha nem tartalmaz.

Hívásnapló: GET /history​

A legújabbal kezdve, 100 bejegyzés, hacsak a ?limit= mást nem mond. A ?missed=true csak a nem fogadott hívásokat adja vissza, a ?declined=true csak azokat, amelyeket ez a telefon elutasított.

MezőJelentés
idA naplóbejegyzés saját azonosítója. Nem azonos a /calls és a webhookok hívás-id értékével; a kettőt a seance_id kapcsolja össze.
outcomeA fő besorolás: answered, missed, declined vagy failed.
answeredtrue vagy false.
duration_s0 olyan hívásnál, amely nem jött létre.
number, uriA másik fél számként és SIP-címként.
nameA Névjegyekből, ha a szám ismert, egyébként üres. Az illesztést a number alapján végezze, ne ez alapján.
dialedA tárcsázott számjegyek kimenő hívásnál; bejövő hívásnál üres.
account, account_idA vonal, amelyen a hívás zajlott.
reasonHogyan ért véget: local-hangup, remote-hangup, cancelled…
answered_byno, ha egy személy fogadta; egyébként az, ami a hívást fogadta.

Névjegyek: GET /contacts​

Minden névjegynek van id, name és number mezője, valamint a vonal, amelyhez tartozik: account_id és account; az üres account azt jelenti, hogy a névjegy nincs vonalhoz kötve.

Felvételek​

A felvételeket és a leiratokat a program nem adja ki JSON-ként. Az API HTML-oldalakként szolgálja ki őket, /ui és /ui/recordings/{id}: a CRM-ből ezekre az oldalakra hivatkozzon ahelyett, hogy hanganyagot mozgatna. A hivatkozás azon a számítógépen nyílik meg, amely a felvételt őrzi, és a hang soha nem hagyja el.

Taxonómia és beállítások​

A /taxonomy minden bejegyzésének van egy állandó code értéke, egy title és egy description értéke a felület nyelvén, egy kind értéke (category, tag vagy red_flag), a figyelmeztető jeleknek pedig severity értéke is. Az illesztést a code alapján végezze, soha ne a title alapján: a címek azon a nyelven érkeznek, amelyre a telefon be van állítva. A retired: true jelölésű bejegyzés azért marad meg, hogy a régebbi hívások továbbra is feloldhatók legyenek; új hívásokhoz már nem kerül hozzárendelésre. Indításkor egyszer töltse be a taxonómiát, hogy a telefon szavait a saját mezőihez rendelje.

A /settings a titkos adatok kivételével visszaadja a konfigurációt: hangeszközök és hangerők, kodekprioritás, megjelenés és nyelv, indulás, gyorsbillentyűk, a diagnosztikai szint és mindkét integráció állapota — hasznos egy olyan támogatási eszköznek, amelynek képernyőmegosztás nélkül kell ellenőriznie egy munkaállomást. Az api.disabled a kikapcsolt hozzáférési csoportokat, a webhooks.silenced a kikapcsolt eseményeket sorolja fel; az üres lista azt jelenti, hogy minden be van kapcsolva. Soha nem tartalmazza a SIP-jelszót, az API tokenjét vagy a webhook fejlécértékét.

Hibák​

Minden hiba JSON egyetlen error kulccsal, amely embereknek szól, nem gépi feldolgozásra.

ÁllapotkódTörzsJelentés
404{"error":"no such endpoint"}Az útvonal nem létezik, vagy a hozzáférési csoportja ki van kapcsolva; szándékosan mindkettő ugyanazt a választ adja.
405{"error":"that endpoint does not take this method"}Az útvonal létezik, de ezt a módszert nem fogadja: például POST /settings a PUT helyett.
401{"error":"writing needs a token, and none is configured"}Tárolt adatot módosító végpont olyan telefonon, ahol a Token mező üres. Töltse ki a Helyi vezérlés részben.
401{"error":"this endpoint needs the authorization token"}Tárolt adatot módosító végpont a helyes token nélkül.
404{"error":"no contact with that id"}Az útvonal helyes, az azonosító nem.
400{"error":"no call with that id"}A hívás véget ért, vagy sosem létezett.
400{"error":"a call needs a number"}POST /calls szám nélkül. Semmi sem került tárcsázásra.
400{"error":"no digits to send"}POST /calls/{id}/dtmf számjegyek nélkül.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer cél nélkül.
400{"error":"the account this call is on is no longer set up"}A hívás fiókját a hívás közben eltávolították, így a cél nem egészíthető ki. Semmi sem ment ki az alközpontnak.

Az elutasított kéréseket az api_requests_refused_total számolja, így a csendben hibázó integráció a mérőszámokban is látszik, nem csak a saját naplóiban.

Mérőszámok​

A GET /metrics a telefon összes számlálóját visszaadja, mindegyiket egy súgószöveggel. Gyűjtse be Prometheusszal, vagy olvassa el kézzel.

SzámlálóMit számol
calls_incoming_totalA beérkezett bejövő hívásokat.
calls_outgoing_totalAz indított kimenő hívásokat.
calls_answered_totalA fogadott hívásokat.
calls_missed_totalA nem fogadott bejövő hívásokat.
calls_declined_totalAz itt vagy a túloldalon elutasított hívásokat.
calls_failed_totalA fel nem építhető hívásokat.
registrations_succeeded_totalA sikeres SIP-regisztrációkat.
registrations_failed_totalAz elutasított vagy időtúllépéssel végződött SIP-regisztrációkat.
webhooks_delivered_totalA fogadó által elfogadott webhookokat.
webhooks_failed_totalAz elutasított vagy nem kézbesített webhookokat.
webhooks_dropped_totalA megtelt várólista miatt eldobott webhookokat.
api_requests_totalAz API által kezelt kéréseket.
api_requests_refused_totalAz elutasított kéréseket: hibás token, kikapcsolt csoport vagy ismeretlen útvonal.

Régebbi integráció frissítése​

A korábbi verziók camelCase neveket és rövid azonosítókat használtak. Az accountId helyett most account_id, a startedAt helyett callstart_ts, a durationSeconds helyett duration_s, az answeredBy helyett answered_by áll, a webhook at mezője pedig event_ts lett. A hívásokat és a fiókokat csak UUID azonosítja: a runtimeId és az olyan azonosítók, mint a call-3 vagy az account-2, már nem kerülnek visszaadásra, és nem is fogadja el őket a program.

Ha nem működik​

TünetMit ellenőrizzen
Elutasított kapcsolat a 127.0.0.1:8377 címenA helyi vezérlés ki van kapcsolva, a telefon nem fut, vagy a portot módosították.
404 {"error":"no such endpoint"} egy ezen az oldalon szereplő útvonalraA hozzáférési csoportja ki van kapcsolva.
Az olvasás működik, az írást 401-gyel elutasítjaA tárolt adatokat módosító végpontoknak kell a token az Authorization fejlécben, és a telefonon előbb ki kell tölteni a Token mezőt.
A kategóriák címei nem angolul vannakA címek a felület nyelvét követik. Az illesztést a /taxonomy code értéke alapján végezze.
Hiányzik az accountId, a startedAt vagy az atAz integrációt a korábbi nevekre írták; lásd fent.

Ha magával a regisztrációval vagy egy hívással van probléma, nyissa meg a Diagnosztikát.