Salt la conținutul principal

API REST local

AI Softphone are un API REST pentru integrare CTI: un program de pe același calculator poate efectua și controla apeluri, poate citi contactele, istoricul apelurilor și conturile SIP și poate urmări apelurile în curs. Fără SDK, fără intermediar în cloud și fără vreun serviciu expus în rețea. Cererile și răspunsurile sunt JSON, așa că curl sau orice client HTTP este suficient.

API-ul este oprit după instalare; nimic nu ascultă până când îl porniți. Apoi ascultă doar pe interfața de loopback — o mică interfață web care răspunde doar acestui calculator — și nu poate fi accesat din rețeaua biroului, printr-un VPN sau de pe alt calculator.

Folosiți API-ul când programul dumneavoastră are nevoie de date de la telefon sau trebuie să controleze un apel. Folosiți webhookurile când trebuie să reacționeze la apeluri pe măsură ce au loc, fără interogări repetate. Majoritatea integrărilor le folosesc pe amândouă; sunt independente unul de celălalt.

Pornirea lui​

Deschideți Setări → Integrare și mergeți la Comandă locală.

  1. Porniți Lasă alte programe de pe acest calculator să conducă telefonul. Serverul pornește imediat.
  2. Păstrați valoarea implicită pentru Port, 8377, dacă nu cumva o folosește deja alt program.
  3. Opțional, setați un Token. După salvare, câmpul afișează Salvat — scrieți ca să îl înlocuiți.
  4. La Acces, alegeți grupurile de deschis: Contacte, Istoricul apelurilor, Apelurile și comanda lor, Conturi, Setări, Contoare (indicatorii). Un grup oprit nu este filtrat, ci nu este servit deloc.
  5. Testați: curl http://127.0.0.1:8377/accounts. Dacă răspunsul este JSON, API-ul funcționează.

Nu se instalează niciun serviciu separat și nu este nevoie de repornire. Partea programului care face acest lucru poate fi oprită în Module (Integrare).

Pagina proprie a API-ului​

Deschide pagina proprie a API-ului deschide http://127.0.0.1:8377 într-un navigator. Adresa răspunde cu o listă a tot ce servește, în engleză; adresele care citesc ceva sunt linkuri pe care le puteți urma.

Accesul și tokenul​

Ce poate face un program depinde de faptul că modifică sau nu datele stocate, nu de faptul că citește:

  • Fără token, orice program de pe calculator poate citi tot din grupurile activate și poate controla apelurile: efectuare, răspuns, închidere, punere în așteptare, reluare, transfer și trimitere DTMF.
  • Cu tokenul în antetul Authorization, poate folosi și punctele finale care modifică ce este stocat. Fără token, aceste puncte finale nu sunt listate pe pagina proprie a API-ului și răspund cu 401. Dacă nu este setat niciun token, nimic nu poate modifica ce este stocat.

Tokenul este păstrat în depozitul de chei al calculatorului, nu în fișierul de setări, și nu este returnat niciodată de /settings.

atenție

Fără token, orice program care rulează pe acest calculator poate controla telefonul, inclusiv să răspundă la apeluri. Pe o stație de lucru personală, acest lucru este de obicei acceptabil. Pe un calculator partajat sau administrat, setați un token și tratați-l ca pe orice altă parolă. Tokenul protejează doar cererile care modifică datele salvate, nu și apelurile: ca să țineți alte programe departe de apeluri, opriți Apelurile și comanda lor la Acces.

Puncte finale​

Adresa de bază este http://127.0.0.1:8377. Punctele finale de mai jos nu au nevoie de token.

MetodăCaleCe face
GET/metricsContoarele, în format Prometheus.
GET/uiLista înregistrărilor, ca pagină HTML.
GET/ui/recordings/{id}O înregistrare cu transcrierea ei, ca pagină HTML.
GET/ui/recordings/{id}/audioSunetul pentru pagina de mai sus.
GET/contactsContactele.
GET/contacts/{id}Un singur contact.
GET/historyIstoricul apelurilor, cele mai noi primele. Acceptă ?limit=, ?missed=true și ?declined=true.
GET/callsApelurile în curs.
POST/callsEfectuează un apel: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerRăspunde la un apel.
POST/calls/{id}/hangupÎnchide un apel.
POST/calls/{id}/holdPune un apel în așteptare.
POST/calls/{id}/resumeÎl scoate din așteptare.
POST/calls/{id}/dtmfTrimite tonuri: {"digits": "..."}.
POST/calls/{id}/transferTransferă apelul: {"target": "..."}.
GET/accountsConturile SIP și starea înregistrării lor. Niciodată parola.
GET/settingsÎntreaga configurație, fără secrete.
GET/taxonomyCategorii, etichete și semnale de alarmă, cu codurile lor.

Puncte finale care cer tokenul​

Ele modifică ce este stocat, așa că fiecare cerere trebuie să poarte tokenul în antetul Authorization. Pagina proprie a API-ului le arată doar unei cereri care îl poartă.

MetodăCaleCe face
POST/contactsAdaugă un contact: {"name": "...", "number": "...", "account_id": "..."}; account_id este opțional.
PUT/contacts/{id}Înlocuiește un contact.
DELETE/contacts/{id}Elimină un contact.
DELETE/history/{id}Uită un apel din jurnalul de apeluri.
DELETE/historyUită tot jurnalul de apeluri. Nu se poate anula.
PUT/accounts/{id}Înlocuiește setările unui cont. Parola nu este printre ele.
PUT/settingsÎnlocuiește setările.

Fiecare identificator este un UUID emis de telefon: id al unui apel vine din /calls sau din răspunsul la POST /calls, id al unui cont din /accounts.

Numele câmpurilor sunt în snake_case, iar terminația indică tipul: _id este o referință la un UUID, _ts este un moment în milisecunde Unix (UTC), _s este o durată în secunde. La fel este și pentru webhookuri; doar /settings își păstrează propriile nume. În API-ul REST, aceste valori sunt numere JSON, iar un moment necunoscut este null.

Exemplu: efectuarea unui apel​

POST /calls efectuează un apel. Corpul este JSON, cu number de format și, opțional, account_id al contului de pe care se sună:

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

Răspunsul este identificatorul noului apel:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number este obligatoriu. Fără el, răspunsul este 400 {"error":"a call needs a number"} și nu se formează nimic.
  • Numărul este completat pe contul ales la fel cum îl completează tastatura de apelare: 1020 este trimis ca sip:1020@pbx.example.com. POST /calls/{id}/transfer își completează target în același fel; o țintă care are deja o schemă sau un @ este trimisă așa cum este.
  • account_id este opțional; luați-l din GET /accounts. Fără el, apelul pleacă de pe contul selectat în fereastra principală.
  • Folosiți id în /calls/{id}/…: hangup, hold, resume, dtmf și transfer. Webhookurile acestui apel poartă același id.

Dintr-o pagină web: clic pentru apel​

O pagină care apelează 127.0.0.1 ajunge la calculatorul pe care rulează navigatorul — același pe care rulează telefonul —, așa că un buton de tip clic pentru apel dintr-un CRM nu are nevoie de un server propriu:

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

Ce conțin răspunsurile​

Apeluri în curs: GET /calls​

Fiecare apel are id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts și callstate_ts.

  • state este dialing, ringing-out, ringing-in, active, hold (pus în așteptare de acest telefon), onhold (pus în așteptare de cealaltă parte), conference sau ended. Când se aplică mai multe, conference are prioritate față de hold, iar hold față de onhold.
  • muted spune dacă microfonul este oprit în apel; oprirea microfonului nu schimbă state.
  • seance_id este conversația: apelurile legate printr-un transfer, o consultare sau o conferință îl au în comun.
  • event_ts este momentul în care a fost creat răspunsul. Comparați-l cu callstate_ts ca să vedeți de cât timp se află apelul în starea lui, fără să vă bazați pe propriul ceas.

Conturi: GET /accounts​

Fiecare cont are id (adică account_id din toate celelalte locuri), setările lui — transport (udp, tcp sau tls), port, registrar, outbound_proxy, expiry_s și altele —, dacă este enabled și state la centrală: registered cât timp linia este activă. Parolele nu sunt incluse niciodată.

Istoricul apelurilor: GET /history​

Cele mai noi primele, 100 de intrări, dacă ?limit= nu spune altfel. ?missed=true returnează doar apelurile pierdute, ?declined=true doar apelurile respinse de acest telefon.

CâmpSemnificație
idIdentificatorul propriu al intrării din istoric. Nu este id al apelului din /calls și din webhookuri; seance_id le leagă pe cele două.
outcomeClasificarea principală: answered, missed, declined sau failed.
answeredtrue sau false.
duration_s0 pentru un apel care nu s-a conectat niciodată.
number, uriCealaltă parte, ca număr și ca adresă SIP.
nameDin Contacte, dacă numărul este cunoscut, altfel gol. Potriviți după number, nu după acest câmp.
dialedCifrele formate, pentru un apel efectuat; gol pentru unul primit.
account, account_idLinia pe care a fost apelul.
reasonCum s-a încheiat: local-hangup, remote-hangup, cancelled…
answered_byno dacă a răspuns o persoană; altfel, ce anume a răspuns la apel.

Contacte: GET /contacts​

Fiecare contact are id, name, number și linia căreia îi aparține, account_id și account; un account gol înseamnă că acel contact nu este legat de o linie.

Înregistrări​

Înregistrările și transcrierile nu sunt oferite ca JSON. API-ul le servește ca pagini HTML, /ui și /ui/recordings/{id}: puneți din CRM linkuri către aceste pagini în loc să mutați sunetul dintr-un loc în altul. Linkul se deschide pe calculatorul care păstrează înregistrarea, iar sunetul nu îl părăsește niciodată.

Taxonomie și setări​

Fiecare intrare din /taxonomy are un code constant, un title și o description în limba interfeței, un kind (category, tag sau red_flag) și, pentru semnalele de alarmă, o severity. Potriviți după code, niciodată după title: titlurile vin în limba setată în telefon. O intrare cu retired: true este păstrată pentru ca apelurile mai vechi să se rezolve în continuare; nu mai este dată apelurilor noi. Încărcați taxonomia o singură dată la pornire, ca să puneți în corespondență cuvintele telefonului cu propriile câmpuri.

/settings returnează configurația, cu excepția secretelor: dispozitivele audio și volumele, prioritatea codecurilor, aspectul și limba, pornirea, scurtăturile, nivelul de diagnostic și starea ambelor integrări — util pentru un instrument de asistență care trebuie să verifice o stație de lucru fără partajarea ecranului. api.disabled listează grupurile de acces oprite, iar webhooks.silenced evenimentele oprite; listele goale înseamnă că totul este pornit. Nu include niciodată parola SIP, tokenul API sau valoarea antetului webhookului.

Erori​

Fiecare eroare este un JSON cu o singură cheie, error, destinată oamenilor, nu analizei automate.

StareCorpSemnificație
404{"error":"no such endpoint"}Calea nu există sau grupul ei de acces este oprit; ambele dau intenționat același răspuns.
405{"error":"that endpoint does not take this method"}Calea există, dar nu acceptă această metodă: de exemplu POST /settings în loc de PUT.
401{"error":"writing needs a token, and none is configured"}Un punct final care modifică ce este stocat, pe un telefon unde câmpul Token este gol. Completați-l în Comandă locală.
401{"error":"this endpoint needs the authorization token"}Un punct final care modifică ce este stocat, fără tokenul corect.
404{"error":"no contact with that id"}Calea este corectă, identificatorul nu.
400{"error":"no call with that id"}Apelul s-a încheiat sau nu a existat niciodată.
400{"error":"a call needs a number"}POST /calls fără număr. Nu s-a format nimic.
400{"error":"no digits to send"}POST /calls/{id}/dtmf fără cifre.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer fără țintă.
400{"error":"the account this call is on is no longer set up"}Contul apelului a fost eliminat în timpul apelului, așa că ținta nu poate fi completată. Nu s-a trimis nimic centralei.

Cererile refuzate sunt numărate în api_requests_refused_total, așa că o integrare care eșuează în tăcere se vede în indicatori, nu doar în propriile jurnale.

Indicatori​

GET /metrics returnează fiecare contor al telefonului, fiecare cu un text de ajutor. Colectați-l cu Prometheus sau citiți-l manual.

ContorNumără
calls_incoming_totalApelurile primite.
calls_outgoing_totalApelurile efectuate.
calls_answered_totalApelurile la care s-a răspuns.
calls_missed_totalApelurile primite la care nu s-a răspuns.
calls_declined_totalApelurile respinse aici sau de cealaltă parte.
calls_failed_totalApelurile care nu au putut fi stabilite.
registrations_succeeded_totalÎnregistrările SIP reușite.
registrations_failed_totalÎnregistrările SIP refuzate sau expirate.
webhooks_delivered_totalWebhookurile acceptate de destinatar.
webhooks_failed_totalWebhookurile refuzate sau nelivrate.
webhooks_dropped_totalWebhookurile aruncate pentru că coada era plină.
api_requests_totalCererile tratate de API.
api_requests_refused_totalCererile refuzate: token greșit, grup oprit sau cale necunoscută.

Actualizarea unei integrări mai vechi​

Versiunile anterioare foloseau nume în camelCase și identificatori scurți. accountId este acum account_id, startedAt este callstart_ts, durationSeconds este duration_s, answeredBy este answered_by, iar câmpul de webhook at este event_ts. Apelurile și conturile sunt identificate doar prin UUID: runtimeId și identificatori precum call-3 sau account-2 nu mai sunt returnați și nici acceptați.

Când nu funcționează​

SimptomCe să verificați
Conexiune refuzată pe 127.0.0.1:8377Comanda locală este oprită, telefonul nu rulează sau portul a fost schimbat.
404 {"error":"no such endpoint"} pentru o cale de pe această paginăGrupul ei de acces este oprit.
Citirea merge, scrierea este refuzată cu 401Punctele finale care modifică datele stocate cer tokenul în antetul Authorization, iar pe telefon trebuie întâi completat câmpul Token.
Titlurile categoriilor nu sunt în englezăTitlurile urmează limba interfeței. Potriviți după code din /taxonomy.
Lipsesc accountId, startedAt sau atIntegrarea a fost scrisă pentru numele anterioare; vedeți mai sus.

Pentru o problemă cu înregistrarea la centrală sau cu un apel în sine, deschideți Diagnostic.