Miestne REST API
AI Softphone má REST API na integráciu CTI: program na tom istom počítači môže uskutočňovať a ovládať hovory, čítať kontakty, históriu hovorov a SIP účty a sledovať prebiehajúce hovory. Bez SDK, bez cloudového sprostredkovateľa a bez načúvania vystaveného do siete. Požiadavky a odpovede sú JSON, takže stačí curl alebo akýkoľvek HTTP klient.
API je po inštalácii vypnuté; nič nenačúva, kým ho nezapnete. Potom načúva iba na rozhraní loopback — malé webové rozhranie, ktoré odpovedá iba tomuto počítaču — a nedá sa dosiahnuť z kancelárskej siete, VPN ani z iného počítača.
API použite, keď váš program potrebuje údaje z telefónu alebo musí ovládať hovor. Webhooky použite, keď musí reagovať na hovory priebežne, bez dopytovania. Väčšina integrácií používa oboje; sú od seba nezávislé.
Zapnutie
Otvorte Nastavenia → Integrácia a prejdite na Miestne ovládanie.
- Zapnite Nechať iné programy v tomto počítači ovládať telefón. Server sa spustí okamžite.
- Ponechajte predvolený Port,
8377, ak ho už nepoužíva iný program. - Voliteľne nastavte Token. Po uložení pole ukazuje Uložené — píšte, nech to nahradíte.
- V časti Prístup vyberte skupiny, ktoré chcete otvoriť: Kontakty, História hovorov, Hovory a ich ovládanie, Účty, Nastavenia, Počítadlá (metriky). Vypnutá skupina sa nefiltruje, ale vôbec sa neobsluhuje.
- Vyskúšajte to:
curl http://127.0.0.1:8377/accounts. Ak je odpoveďou JSON, API funguje.
Neinštaluje sa žiadna samostatná služba a nie je potrebný reštart. Časť programu, ktorá to robí, sa dá vypnúť v Moduloch (Integrácia).
Vlastná stránka API
Otvoriť vlastnú stránku API otvorí http://127.0.0.1:8377 v prehliadači. Adresa odpovie zoznamom všetkého, čo obsluhuje, v angličtine; adresy, ktoré niečo čítajú, sú odkazy, na ktoré sa dá kliknúť.
Prístup a token
Čo program smie robiť, závisí od toho, či mení uložené údaje, nie od toho, či číta:
- Bez tokenu môže ktorýkoľvek program v počítači čítať všetko v zapnutých skupinách a ovládať hovory: uskutočniť, prijať, zavesiť, podržať, obnoviť, prepojiť a poslať DTMF.
- S tokenom v hlavičke
Authorizationmôže používať aj koncové body, ktoré menia to, čo je uložené. Bez tokenu sa tieto koncové body neuvádzajú na vlastnej stránke API a odpovedajú401. Keď token nie je nastavený vôbec, uložené nemôže zmeniť nič.
Token sa uchováva v kľúčenke počítača, nie v súbore nastavení, a /settings ho nikdy nevracia.
Bez tokenu môže ktorýkoľvek program bežiaci v tomto počítači ovládať telefón, vrátane prijímania hovorov. Na osobnej pracovnej stanici je to zvyčajne prijateľné. Na zdieľanom alebo spravovanom počítači nastavte token a zaobchádzajte s ním ako s akýmkoľvek iným heslom. Token chráni iba požiadavky, ktoré menia uložené údaje, nie hovory: ak chcete ostatné programy k hovorom nepustiť, vypnite Hovory a ich ovládanie v časti Prístup.
Koncové body
Základná adresa je http://127.0.0.1:8377. Koncové body nižšie nepotrebujú token.
| Metóda | Cesta | Čo robí |
|---|---|---|
| GET | /metrics | Počítadlá vo formáte Prometheus. |
| GET | /ui | Zoznam nahrávok ako stránka HTML. |
| GET | /ui/recordings/{id} | Nahrávka s prepisom ako stránka HTML. |
| GET | /ui/recordings/{id}/audio | Zvuk pre stránku vyššie. |
| GET | /contacts | Kontakty. |
| GET | /contacts/{id} | Jeden kontakt. |
| GET | /history | Záznam hovorov, od najnovších. Prijíma ?limit=, ?missed=true a ?declined=true. |
| GET | /calls | Prebiehajúce hovory. |
| POST | /calls | Uskutoční hovor: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Prijme hovor. |
| POST | /calls/{id}/hangup | Zavesí hovor. |
| POST | /calls/{id}/hold | Podrží hovor. |
| POST | /calls/{id}/resume | Obnoví ho. |
| POST | /calls/{id}/dtmf | Pošle tóny: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Prepojí hovor: {"target": "..."}. |
| GET | /accounts | SIP účty a stav ich registrácie. Nikdy heslo. |
| GET | /settings | Celá konfigurácia, bez tajomstiev. |
| GET | /taxonomy | Kategórie, štítky a varovné signály s ich kódmi. |
Koncové body, ktoré potrebujú token
Menia to, čo je uložené, preto musí každá požiadavka niesť token v hlavičke Authorization. Vlastná stránka API ich ukazuje len požiadavke, ktorá ho nesie.
| Metóda | Cesta | Čo robí |
|---|---|---|
| POST | /contacts | Pridá kontakt: {"name": "...", "number": "...", "account_id": "..."}; account_id je nepovinné. |
| PUT | /contacts/{id} | Nahradí kontakt. |
| DELETE | /contacts/{id} | Odstráni kontakt. |
| DELETE | /history/{id} | Zabudne jeden hovor zo zoznamu hovorov. |
| DELETE | /history | Zabudne celý zoznam hovorov. Nedá sa to vrátiť. |
| PUT | /accounts/{id} | Nahradí nastavenia účtu. Heslo medzi nimi nie je. |
| PUT | /settings | Nahradí nastavenia. |
Každý identifikátor je UUID pridelené telefónom: id hovoru pochádza z /calls alebo z odpovede na POST /calls, id účtu z /accounts.
Názvy polí sú v snake_case a koncovka hovorí o type: _id je odkaz na UUID, _ts je okamih v unixových milisekundách (UTC), _s je dĺžka v sekundách. To isté platí pre webhooky; iba /settings má vlastné názvy. V REST API sú tieto hodnoty čísla JSON a neznámy okamih je null.
Príklad: uskutočnenie hovoru
POST /calls uskutoční odchádzajúci hovor. Telo je JSON s číslom number na vytočenie a voliteľne s account_id účtu, z ktorého volať:
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
Odpoveďou je identifikátor nového hovoru:
{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
numberje povinné. Bez neho je odpoveď400 {"error":"a call needs a number"}a nič sa nevytočí.- Číslo sa na vybranom účte doplní tak, ako ho dopĺňa pole na vytáčanie:
1020sa pošle akosip:1020@pbx.example.com.POST /calls/{id}/transferdopĺňa svojtargetrovnako; cieľ, ktorý už má schému alebo@, sa pošle tak, ako je. account_idje voliteľné; vezmite ho zGET /accounts. Bez neho hovor ide z účtu vybraného v hlavnom okne.- Použite
idv/calls/{id}/…:hangup,hold,resume,dtmfatransfer. Webhooky tohto hovoru nesú rovnakéid.
Z webovej stránky: kliknutím zavolať
Stránka, ktorá volá 127.0.0.1, sa dostane k počítaču, na ktorom beží prehliadač — tomu istému, na ktorom beží telefón —, takže tlačidlo „kliknutím zavolať“ v CRM nepotrebuje vlastný server:
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);
}
Čo obsahujú odpovede
Prebiehajúce hovory: GET /calls
Každý hovor má svoje id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts a callstate_ts.
statejedialing,ringing-out,ringing-in,active,hold(podržaný týmto telefónom),onhold(podržaný druhou stranou),conferencealeboended. Keď platí viac ako jeden,conferencemá prednosť predholdaholdpredonhold.mutedhovorí, či je mikrofón v hovore stlmený; stlmenie nemenístate.seance_idje rozhovor: hovory prepojené prepojením, konzultáciou alebo konferenciou ho majú spoločný.event_tsje chvíľa, keď bola odpoveď vytvorená. Porovnajte ho scallstate_ts, aby ste videli, ako dlho je hovor vo svojom stave, bez spoliehania sa na vlastné hodiny.
Účty: GET /accounts
Každý účet má svoje id (všade inde account_id), svoje nastavenia — transport (udp, tcp alebo tls), port, registrar, outbound_proxy, expiry_s a ďalšie —, či je enabled, a svoj state na ústredni: registered, kým je linka aktívna. Heslá sa nikdy neuvádzajú.
História hovorov: GET /history
Od najnovších, 100 záznamov, ak ?limit= neurčuje inak. ?missed=true vráti iba zmeškané hovory, ?declined=true iba hovory, ktoré tento telefón odmietol.
| Pole | Význam |
|---|---|
id | Vlastný identifikátor záznamu histórie. Nie je to id hovoru z /calls a webhookov; prepája ich seance_id. |
outcome | Hlavná klasifikácia: answered, missed, declined alebo failed. |
answered | true alebo false. |
duration_s | 0 pre hovor, ktorý sa nikdy nespojil. |
number, uri | Druhá strana, ako číslo a ako SIP adresa. |
name | Z Kontaktov, ak je číslo známe, inak prázdne. Párujte podľa number, nie podľa tohto. |
dialed | Vytočené číslice, pri odchádzajúcom hovore; pri prichádzajúcom prázdne. |
account, account_id | Linka, na ktorej hovor bol. |
reason | Ako sa skončil: local-hangup, remote-hangup, cancelled… |
answered_by | no, ak ho prijal človek; inak to, čo hovor prijalo. |
Kontakty: GET /contacts
Každý kontakt má svoje id, name, number a linku, ku ktorej patrí, account_id a account; prázdne account znamená, že kontakt nie je viazaný na linku.
Nahrávky
Nahrávky a prepisy sa nevydávajú ako JSON. API ich obsluhuje ako stránky HTML, /ui a /ui/recordings/{id}: odkazujte na tieto stránky zo svojho CRM namiesto presúvania zvuku. Odkaz sa otvorí na počítači, ktorý nahrávku uchováva, a zvuk ho nikdy neopustí.
Taxonómia a nastavenia
Každá položka /taxonomy má stály code, title a description v jazyku rozhrania, kind (category, tag alebo red_flag) a pri varovných signáloch severity. Párujte podľa code, nikdy podľa title: názvy prichádzajú v jazyku, na ktorý je telefón nastavený. Položka s retired: true sa uchováva, aby sa staršie hovory stále dali vyhodnotiť; novým hovorom sa už nepriraďuje. Taxonómiu načítajte raz pri spustení, aby ste slová telefónu namapovali na vlastné polia.
/settings vracia konfiguráciu okrem tajomstiev: zvukové zariadenia a hlasitosti, prioritu kodekov, vzhľad a jazyk, spúšťanie, klávesové skratky, úroveň diagnostiky a stav oboch integrácií — užitočné pre nástroj podpory, ktorý musí skontrolovať pracovnú stanicu bez zdieľania obrazovky. api.disabled uvádza vypnuté skupiny prístupu a webhooks.silenced vypnuté udalosti; prázdne zoznamy znamenajú, že je všetko zapnuté. Nikdy neobsahuje heslo SIP, token API ani hodnotu hlavičky webhooku.
Chyby
Každá chyba je JSON s jediným kľúčom error, určeným pre ľudí, nie na parsovanie.
| Stav | Telo | Význam |
|---|---|---|
| 404 | {"error":"no such endpoint"} | Cesta neexistuje alebo je jej skupina prístupu vypnutá; obe situácie dávajú zámerne rovnakú odpoveď. |
| 405 | {"error":"that endpoint does not take this method"} | Cesta existuje, ale túto metódu neprijíma: napríklad POST /settings namiesto PUT. |
| 401 | {"error":"writing needs a token, and none is configured"} | Koncový bod, ktorý mení uložené, na telefóne, kde je pole Token prázdne. Vyplňte ho v časti Miestne ovládanie. |
| 401 | {"error":"this endpoint needs the authorization token"} | Koncový bod, ktorý mení uložené, bez správneho tokenu. |
| 404 | {"error":"no contact with that id"} | Cesta je správna, identifikátor nie. |
| 400 | {"error":"no call with that id"} | Hovor sa skončil alebo nikdy neexistoval. |
| 400 | {"error":"a call needs a number"} | POST /calls bez čísla. Nič sa nevytočilo. |
| 400 | {"error":"no digits to send"} | POST /calls/{id}/dtmf bez číslic. |
| 400 | {"error":"a transfer needs a target"} | POST /calls/{id}/transfer bez cieľa. |
| 400 | {"error":"the account this call is on is no longer set up"} | Účet hovoru bol počas hovoru odstránený, takže cieľ sa nedá doplniť. Ústredni sa nič neposlalo. |
Odmietnuté požiadavky sa počítajú v api_requests_refused_total, takže integrácia, ktorá potichu zlyháva, je viditeľná v metrikách, nielen vo vašich vlastných záznamoch.
Metriky
GET /metrics vracia každé počítadlo telefónu, každé s textom pomocníka. Zbierajte ich Prometheusom alebo ich čítajte ručne.
| Počítadlo | Počíta |
|---|---|
calls_incoming_total | Prijaté prichádzajúce hovory. |
calls_outgoing_total | Uskutočnené odchádzajúce hovory. |
calls_answered_total | Hovory, ktoré boli prijaté. |
calls_missed_total | Prichádzajúce hovory, ktoré neboli prijaté. |
calls_declined_total | Hovory odmietnuté tu alebo druhou stranou. |
calls_failed_total | Hovory, ktoré sa nepodarilo zostaviť. |
registrations_succeeded_total | Úspešné SIP registrácie. |
registrations_failed_total | SIP registrácie odmietnuté alebo s vypršaným časom. |
webhooks_delivered_total | Webhooky, ktoré prijímač prijal. |
webhooks_failed_total | Webhooky odmietnuté alebo nedoručené. |
webhooks_dropped_total | Webhooky zahodené, lebo front bol plný. |
api_requests_total | Požiadavky spracované API. |
api_requests_refused_total | Odmietnuté požiadavky: nesprávny token, vypnutá skupina alebo neznáma cesta. |
Aktualizácia staršej integrácie
Staršie verzie používali názvy v camelCase a krátke identifikátory. accountId je teraz account_id, startedAt je callstart_ts, durationSeconds je duration_s, answeredBy je answered_by a pole webhooku at je event_ts. Hovory a účty sa identifikujú iba podľa UUID: runtimeId a identifikátory ako call-3 či account-2 sa už nevracajú ani neprijímajú.
Keď to nefunguje
| Príznak | Čo skontrolovať |
|---|---|
Odmietnuté spojenie na 127.0.0.1:8377 | Miestne ovládanie je vypnuté, telefón nebeží alebo sa zmenil port. |
404 {"error":"no such endpoint"} pre cestu z tejto stránky | Jej skupina prístupu je vypnutá. |
Čítanie funguje, zápis sa odmieta s 401 | Koncové body, ktoré menia uložené údaje, potrebujú token v hlavičke Authorization a na telefóne treba najprv vyplniť pole Token. |
| Názvy kategórií nie sú po anglicky | Názvy sa riadia jazykom rozhrania. Párujte podľa code z /taxonomy. |
Chýbajú accountId, startedAt alebo at | Integrácia bola napísaná pre staršie názvy; pozrite vyššie. |
Pri probléme s registráciou alebo so samotným hovorom otvorte Diagnostiku.