Pāriet uz galveno saturu

Vietējais REST API

AI Softphone ir REST API CTI integrācijai: programma tajā pašā datorā var veikt un vadīt zvanus, lasīt kontaktus, zvanu vēsturi un SIP kontus un uzraudzīt notiekošos zvanus. Nav SDK, nav starpnieka mākonī un nav tīklam atvērta klausītāja. Pieprasījumi un atbildes ir JSON, tāpēc pietiek ar curl vai jebkuru HTTP klientu.

Pēc instalēšanas API ir izslēgts; nekas neklausās, līdz jūs to ieslēdzat. Pēc tam tas klausās tikai atgriezeniskās cilpas saskarnē — neliela tīmekļa saskarne, kas atbild tikai šim datoram — un nav sasniedzams no biroja tīkla, VPN vai cita datora.

Izmantojiet API, kad jūsu programmai vajadzīgi dati no tālruņa vai tai jāvada zvans. Izmantojiet tīmekļa āķus, kad tai jāreaģē uz zvaniem to norises laikā, nepārtraukti nevaicājot. Lielākā daļa integrāciju izmanto abus; tie ir neatkarīgi viens no otra.

Tā ieslēgšana​

Atveriet Iestatījumi → Integrācija un dodieties uz Vietējā vadība.

  1. Ieslēdziet Ļaut citām šī datora programmām vadīt telefonu. Serveris startē uzreiz.
  2. Paturiet noklusējuma Ports, 8377, ja vien cita programma to jau neizmanto.
  3. Pēc izvēles iestatiet Pilnvaru. Pēc saglabāšanas laukā redzams Saglabāts — rakstiet, lai to aizstātu.
  4. Sadaļā Piekļuve izvēlieties atveramās grupas: Kontakti, Zvanu vēsture, Zvani un to vadība, Konti, Iestatījumi, Skaitītāji (metrikas). Izslēgta grupa netiek filtrēta, bet netiek piedāvāta vispār.
  5. Pārbaudiet: curl http://127.0.0.1:8377/accounts. Ja atbilde ir JSON, API darbojas.

Atsevišķs pakalpojums netiek instalēts, un restartēšana nav vajadzīga. Programmas daļu, kas to dara, var izslēgt sadaļā Moduļi (Integrācija).

Paša API lapa​

Atvērt paša API lapu atver http://127.0.0.1:8377 pārlūkā. Adrese atbild ar sarakstu angļu valodā ar visu, ko tā piedāvā; adreses, kas kaut ko nolasa, ir saites, kurām var sekot.

Piekļuve un pilnvara​

Tas, ko programma drīkst darīt, ir atkarīgs no tā, vai tā maina saglabātos datus, nevis no tā, vai tā lasa:

  • Bez pilnvaras jebkura datora programma drīkst lasīt visu ieslēgtajās grupās un vadīt zvanus: veikt, atbildēt, nolikt klausuli, aizturēt, turpināt, pāradresēt un sūtīt DTMF.
  • Ar pilnvaru galvenē Authorization tā drīkst izmantot arī galapunktus, kas maina saglabāto. Bez pilnvaras šie galapunkti netiek uzskaitīti paša API lapā un atbild ar 401. Ja pilnvara nav iestatīta vispār, saglabāto nevar mainīt nekas.

Pilnvara tiek glabāta datora atslēgu saišķī, nevis iestatījumu failā, un /settings to nekad neatgriež.

uzmanību

Bez pilnvaras jebkura šajā datorā darbojoša programma var vadīt tālruni, ieskaitot atbildēšanu uz zvaniem. Personiskā darbstacijā tas parasti ir pieņemami. Koplietojamā vai pārvaldītā datorā iestatiet pilnvaru un apejieties ar to kā ar jebkuru citu paroli. Pilnvara aizsargā tikai pieprasījumus, kas maina saglabātos datus, nevis zvanus: lai citas programmas nevarētu piekļūt zvaniem, sadaļā Piekļuve izslēdziet Zvani un to vadība.

Galapunkti​

Bāzes adrese ir http://127.0.0.1:8377. Zemāk esošajiem galapunktiem pilnvara nav vajadzīga.

MetodeCeļšKo dara
GET/metricsSkaitītāji Prometheus formātā.
GET/uiIerakstu saraksts kā HTML lapa.
GET/ui/recordings/{id}Ieraksts ar atšifrējumu kā HTML lapa.
GET/ui/recordings/{id}/audioIepriekšējās lapas skaņa.
GET/contactsKontakti.
GET/contacts/{id}Viens kontakts.
GET/historyZvanu vēsture, jaunākie pirmie. Pieņem ?limit=, ?missed=true un ?declined=true.
GET/callsNotiekošie zvani.
POST/callsVeic zvanu: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerAtbild uz zvanu.
POST/calls/{id}/hangupPārtrauc zvanu.
POST/calls/{id}/holdAiztur zvanu.
POST/calls/{id}/resumeAtsāk to.
POST/calls/{id}/dtmfSūta toņus: {"digits": "..."}.
POST/calls/{id}/transferPāradresē zvanu: {"target": "..."}.
GET/accountsSIP konti un to reģistrācijas stāvoklis. Nekad parole.
GET/settingsVisa konfigurācija bez noslēpumiem.
GET/taxonomyKategorijas, birkas un brīdinājuma signāli ar to kodiem.

Galapunkti, kam vajag pilnvaru​

Tie maina saglabāto, tāpēc katram pieprasījumam jānes pilnvara galvenē Authorization. Paša API lapa tos rāda tikai pieprasījumam, kas to nes.

MetodeCeļšKo dara
POST/contactsPievieno kontaktu: {"name": "...", "number": "...", "account_id": "..."}; account_id nav obligāts.
PUT/contacts/{id}Aizstāj kontaktu.
DELETE/contacts/{id}Noņem kontaktu.
DELETE/history/{id}Aizmirst vienu zvanu no zvanu žurnāla.
DELETE/historyAizmirst visu zvanu žurnālu. To nevar atsaukt.
PUT/accounts/{id}Aizstāj konta iestatījumus. Parole nav starp tiem.
PUT/settingsAizstāj iestatījumus.

Katrs identifikators ir tālruņa izsniegts UUID: zvana id nāk no /calls vai no atbildes uz POST /calls, konta id — no /accounts.

Lauku nosaukumi ir snake_case formā, un galotne norāda tipu: _id ir atsauce uz UUID, _ts ir brīdis Unix milisekundēs (UTC), _s ir ilgums sekundēs. Tas pats attiecas uz tīmekļa āķiem; tikai /settings izmanto savus nosaukumus. REST API šīs vērtības ir JSON skaitļi, un nezināms brīdis ir null.

Piemērs: zvana veikšana​

POST /calls veic izejošu zvanu. Saturs ir JSON ar sastādāmo number un pēc izvēles tā konta account_id, no kura zvanīt:

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

Atbilde ir jaunā zvana identifikators:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number ir obligāts. Bez tā atbilde ir 400 {"error":"a call needs a number"}, un nekas netiek sastādīts.
  • Numurs tiek papildināts izvēlētajā kontā tāpat, kā to papildina numura sastādītājs: 1020 tiek nosūtīts kā sip:1020@pbx.example.com. POST /calls/{id}/transfer papildina savu target tāpat; mērķis, kam jau ir shēma vai @, tiek nosūtīts nemainīts.
  • account_id nav obligāts; ņemiet to no GET /accounts. Bez tā zvans iziet no galvenajā logā izvēlētā konta.
  • Izmantojiet id ceļos /calls/{id}/…: hangup, hold, resume, dtmf un transfer. Šī zvana tīmekļa āķiem ir tas pats id.

No tīmekļa lapas: noklikšķini un zvani​

Lapa, kas vēršas pie 127.0.0.1, sasniedz datoru, kurā darbojas pārlūks — to pašu, kurā darbojas tālrunis —, tāpēc CRM pogai „noklikšķini un zvani” nav vajadzīgs savs serveris:

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

Ko satur atbildes​

Notiekošie zvani: GET /calls​

Katram zvanam ir id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts un callstate_ts.

  • state ir dialing, ringing-out, ringing-in, active, hold (aizturējis šis tālrunis), onhold (aizturējusi otra puse), conference vai ended. Ja attiecas vairāki, conference ir prioritārs pār hold, un hold — pār onhold.
  • muted norāda, vai mikrofons zvanā ir apklusināts; apklusināšana nemaina state.
  • seance_id ir saruna: zvani, kas saistīti ar pāradresāciju, konsultāciju vai konferenci, to koplieto.
  • event_ts ir atbildes sagatavošanas brīdis. Salīdziniet to ar callstate_ts, lai redzētu, cik ilgi zvans ir savā stāvoklī, nepaļaujoties uz savu pulksteni.

Konti: GET /accounts​

Katram kontam ir id (visur citur account_id), tā iestatījumi — transport (udp, tcp vai tls), port, registrar, outbound_proxy, expiry_s un citi —, vai tas ir enabled, un tā state centrālē: registered, kamēr līnija darbojas. Paroles nekad netiek iekļautas.

Zvanu vēsture: GET /history​

Jaunākie pirmie, 100 ieraksti, ja vien ?limit= nenosaka citādi. ?missed=true atgriež tikai neatbildētos zvanus, ?declined=true — tikai šī tālruņa noraidītos.

LauksNozīme
idVēstures ieraksta paša identifikators. Tas nav /calls un tīmekļa āķu zvana id; seance_id saista abus.
outcomeGalvenā klasifikācija: answered, missed, declined vai failed.
answeredtrue vai false.
duration_s0 zvanam, kas nekad netika savienots.
number, uriOtra puse kā numurs un kā SIP adrese.
nameNo Kontaktiem, ja numurs ir zināms, citādi tukšs. Sasaistiet pēc number, nevis pēc šī.
dialedSastādītie cipari izejošam zvanam; ienākošam — tukšs.
account, account_idLīnija, kurā notika zvans.
reasonKā tas beidzās: local-hangup, remote-hangup, cancelled…
answered_byno, ja atbildēja cilvēks; citādi tas, kas atbildēja uz zvanu.

Kontakti: GET /contacts​

Katram kontaktam ir id, name, number un līnija, kam tas pieder, account_id un account; tukšs account nozīmē, ka kontakts nav piesaistīts līnijai.

Ieraksti​

Ieraksti un atšifrējumi netiek izsniegti kā JSON. API tos piedāvā kā HTML lapas /ui un /ui/recordings/{id}: no sava CRM saistiet uz šīm lapām, nevis pārvietojiet skaņu. Saite atveras datorā, kas glabā ierakstu, un skaņa to nekad neatstāj.

Taksonomija un iestatījumi​

Katram /taxonomy ierakstam ir nemainīgs code, title un description saskarnes valodā, kind (category, tag vai red_flag) un brīdinājuma signāliem — severity. Sasaistiet pēc code, nekad pēc title: virsraksti nāk valodā, kas iestatīta tālrunī. Ieraksts ar retired: true tiek paturēts, lai vecākus zvanus joprojām varētu atrisināt; jauniem zvaniem tas vairs netiek piešķirts. Ielādējiet taksonomiju vienreiz startēšanas laikā, lai sasaistītu tālruņa vārdus ar saviem laukiem.

/settings atgriež konfigurāciju bez noslēpumiem: skaņas ierīces un skaļumus, kodeku prioritāti, izskatu un valodu, startēšanu, saīsnes, diagnostikas līmeni un abu integrāciju stāvokli — noderīgi atbalsta rīkam, kam jāpārbauda darbstacija bez ekrāna kopīgošanas. api.disabled uzskaita izslēgtās piekļuves grupas, un webhooks.silenced — izslēgtos notikumus; tukši saraksti nozīmē, ka viss ir ieslēgts. Tas nekad neietver SIP paroli, API pilnvaru vai tīmekļa āķa galvenes vērtību.

Kļūdas​

Katra kļūda ir JSON ar vienu atslēgu error, paredzēta cilvēkiem, nevis mašīnparsēšanai.

StatussSatursNozīme
404{"error":"no such endpoint"}Ceļš neeksistē, vai tā piekļuves grupa ir izslēgta; abi apzināti dod to pašu atbildi.
405{"error":"that endpoint does not take this method"}Ceļš pastāv, bet šo metodi nepieņem: piemēram, POST /settings PUT vietā.
401{"error":"writing needs a token, and none is configured"}Saglabāto mainošs galapunkts tālrunī, kurā lauks Pilnvara ir tukšs. Aizpildiet to sadaļā Vietējā vadība.
401{"error":"this endpoint needs the authorization token"}Saglabāto mainošs galapunkts bez pareizās pilnvaras.
404{"error":"no contact with that id"}Ceļš ir pareizs, identifikators nav.
400{"error":"no call with that id"}Zvans ir beidzies vai nekad nav pastāvējis.
400{"error":"a call needs a number"}POST /calls bez numura. Nekas netika sastādīts.
400{"error":"no digits to send"}POST /calls/{id}/dtmf bez cipariem.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer bez mērķa.
400{"error":"the account this call is on is no longer set up"}Zvana konts tika noņemts zvana laikā, tāpēc mērķi nevar papildināt. Centrālei nekas netika nosūtīts.

Noraidītie pieprasījumi tiek skaitīti api_requests_refused_total, tāpēc integrācija, kas klusi neizdodas, ir redzama metrikās, ne tikai jūsu žurnālos.

Metrikas​

GET /metrics atgriež katru tālruņa skaitītāju, katru ar palīdzības tekstu. Vāciet tos ar Prometheus vai lasiet manuāli.

SkaitītājsSkaita
calls_incoming_totalSaņemtos ienākošos zvanus.
calls_outgoing_totalVeiktos izejošos zvanus.
calls_answered_totalZvanus, uz kuriem atbildēja.
calls_missed_totalIenākošos zvanus, uz kuriem neatbildēja.
calls_declined_totalZvanus, kas noraidīti šeit vai otrā pusē.
calls_failed_totalZvanus, kurus neizdevās izveidot.
registrations_succeeded_totalVeiksmīgās SIP reģistrācijas.
registrations_failed_totalNoraidītās vai noilgušās SIP reģistrācijas.
webhooks_delivered_totalTīmekļa āķus, ko saņēmējs pieņēma.
webhooks_failed_totalNoraidītos vai nepiegādātos tīmekļa āķus.
webhooks_dropped_totalTīmekļa āķus, kas atmesti, jo rinda bija pilna.
api_requests_totalAPI apstrādātos pieprasījumus.
api_requests_refused_totalNoraidītos pieprasījumus: nepareiza pilnvara, izslēgta grupa vai nezināms ceļš.

Vecākas integrācijas atjaunināšana​

Agrākās versijās izmantoja camelCase nosaukumus un īsus identifikatorus. accountId tagad ir account_id, startedAt ir callstart_ts, durationSeconds ir duration_s, answeredBy ir answered_by, un tīmekļa āķa lauks at ir event_ts. Zvanus un kontus identificē tikai ar UUID: runtimeId un identifikatori, piemēram, call-3 vai account-2, vairs netiek atgriezti un pieņemti.

Kad tas nedarbojas​

SimptomsKo pārbaudīt
Savienojums atteikts adresē 127.0.0.1:8377Vietējā vadība ir izslēgta, tālrunis nedarbojas, vai ports ir mainīts.
404 {"error":"no such endpoint"} šīs lapas ceļamTā piekļuves grupa ir izslēgta.
Lasīšana darbojas, rakstīšana tiek noraidīta ar 401Galapunktiem, kas maina saglabātos datus, vajag pilnvaru galvenē Authorization, un tālrunī vispirms jāaizpilda lauks Pilnvara.
Kategoriju virsraksti nav angļu valodāVirsraksti seko saskarnes valodai. Sasaistiet pēc code no /taxonomy.
Trūkst accountId, startedAt vai atIntegrācija rakstīta agrākajiem nosaukumiem; skatiet augstāk.

Ja problēma ir ar reģistrāciju vai pašu zvanu, atveriet Diagnostika.