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.
- Lülitage sisse Luba teistel selle arvuti programmidel telefoni juhtida. Server käivitub kohe.
- Jätke vaikimisi Port,
8377, kui mõni teine programm seda juba ei kasuta. - Soovi korral määrake Märgis. Pärast salvestamist näitab väli teksti Salvestatud — kirjutage, et see asendada.
- 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.
- 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
Authorizationvõib see kasutada ka lõpp-punkte, mis muudavad talletatut. Ilma märgiseta neid lõpp-punkte API enda lehel ei loetleta ja need vastavad401. 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.
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.
| Meetod | Tee | Mida teeb |
|---|---|---|
| GET | /metrics | Loendurid Prometheuse vormingus. |
| GET | /ui | Salvestiste loend HTML-lehena. |
| GET | /ui/recordings/{id} | Salvestis koos ülestähendusega HTML-lehena. |
| GET | /ui/recordings/{id}/audio | Ülaltoodud lehe heli. |
| GET | /contacts | Kontaktid. |
| GET | /contacts/{id} | Üks kontakt. |
| GET | /history | Kõnede ajalugu, uusim eespool. Aktsepteerib ?limit=, ?missed=true ja ?declined=true. |
| GET | /calls | Pooleliolevad kõned. |
| POST | /calls | Teeb kõne: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Vastab kõnele. |
| POST | /calls/{id}/hangup | Lõpetab kõne. |
| POST | /calls/{id}/hold | Paneb kõne ootele. |
| POST | /calls/{id}/resume | Võtab selle ootelt maha. |
| POST | /calls/{id}/dtmf | Saadab toone: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Suunab kõne ümber: {"target": "..."}. |
| GET | /accounts | SIP-kontod ja nende registreerimisolek. Mitte kunagi parooli. |
| GET | /settings | Kogu konfiguratsioon ilma saladusteta. |
| GET | /taxonomy | Kategooriad, 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.
| Meetod | Tee | Mida teeb |
|---|---|---|
| POST | /contacts | Lisab 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 | /history | Unustab kogu kõnelogi. Seda ei saa tagasi võtta. |
| PUT | /accounts/{id} | Asendab konto seaded. Parooli nende hulgas ei ole. |
| PUT | /settings | Asendab 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" }
numberon kohustuslik. Ilma selleta on vastus400 {"error":"a call needs a number"}ja midagi ei valita.- Number täiendatakse valitud kontol samamoodi, nagu valija seda teeb:
1020saadetakse kujulsip:1020@pbx.example.com.POST /calls/{id}/transfertäiendab omatargetsamamoodi; siht, millel on juba skeem või@, saadetakse muutmata. account_idon valikuline; võtke seeGET /accountskaudu. Ilma selleta läheb kõne välja peaaknas valitud kontolt.- Kasutage
idteedes/calls/{id}/…:hangup,hold,resume,dtmfjatransfer. Selle kõne veebikonksudel on samaid.
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.
stateondialing,ringing-out,ringing-in,active,hold(selle telefoni poolt ootele pandud),onhold(teise osapoole poolt ootele pandud),conferencevõiended. Kui kehtib mitu, onconferencetähtsam kuiholdjaholdtähtsam kuionhold.mutedütleb, kas mikrofon on kõnes vaigistatud; vaigistaminestateväärtust ei muuda.seance_idon vestlus: ümbersuunamise, konsultatsiooni või konverentsiga seotud kõned jagavad seda.event_tson vastuse koostamise hetk. Võrrelge sedacallstate_tsvää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äli | Tähendus |
|---|---|
id | Ajaloo kirje enda identifikaator. See ei ole /calls ja veebikonksude kõne id; seance_id seob need kaks. |
outcome | Põhiliigitus: answered, missed, declined või failed. |
answered | true või false. |
duration_s | 0 kõne puhul, mis ei saanud kunagi ühendust. |
number, uri | Teine osapool numbri ja SIP-aadressina. |
name | Kontaktidest, kui number on teada, muidu tühi. Siduge number järgi, mitte selle järgi. |
dialed | Valitud numbrid väljamineva kõne puhul; sissetuleva puhul tühi. |
account, account_id | Liin, millel kõne oli. |
reason | Kuidas see lõppes: local-hangup, remote-hangup, cancelled… |
answered_by | no, 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.
| Olek | Sisu | Tä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.
| Loendur | Loendab |
|---|---|
calls_incoming_total | Vastu võetud sissetulevad kõned. |
calls_outgoing_total | Tehtud väljaminevad kõned. |
calls_answered_total | Kõned, millele vastati. |
calls_missed_total | Sissetulevad kõned, millele ei vastatud. |
calls_declined_total | Siin või teise poole poolt tagasi lükatud kõned. |
calls_failed_total | Kõned, mida ei õnnestunud luua. |
registrations_succeeded_total | Õnnestunud SIP-registreerimised. |
registrations_failed_total | Tagasi lükatud või aegunud SIP-registreerimised. |
webhooks_delivered_total | Vastuvõtja poolt aktsepteeritud veebikonksud. |
webhooks_failed_total | Tagasi lükatud või kohale toimetamata veebikonksud. |
webhooks_dropped_total | Veebikonksud, mis jäeti välja, sest järjekord oli täis. |
api_requests_total | API poolt töödeldud päringud. |
api_requests_refused_total | Tagasi 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ümptom | Mida kontrollida |
|---|---|
Ühendusest keelduti aadressil 127.0.0.1:8377 | Kohalik juhtimine on väljas, telefon ei tööta või porti on muudetud. |
404 {"error":"no such endpoint"} selle lehe teele | Selle juurdepääsurühm on väljas. |
Lugemine töötab, kirjutamine lükatakse tagasi koodiga 401 | Talletatud 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 keeles | Pealkirjad järgivad kasutajaliidese keelt. Siduge /taxonomy välja code järgi. |
accountId, startedAt või at puuduvad | Sidumine kirjutati varasemate nimede jaoks; vaadake ülalt. |
Registreerimise või kõne enda probleemi korral avage Diagnostika.