Пређи на главни садржај

Локални REST API

AI Softphone има REST API за CTI интеграцију: програм на истом рачунару може да упућује позиве и управља њима, чита контакте, историју позива и SIP налоге и прати позиве у току. Без SDK-а, без посредника у облаку и без слушаоца изложеног мрежи. Захтеви и одговори су JSON, па је довољан curl или било који HTTP клијент.

API је након инсталације искључен; ништа не слуша док га не укључите. Тада слуша само на loopback сучељу — малом веб-сучељу које одговара само овом рачунару — и није доступан из канцеларијске мреже, VPN-а нити са другог рачунара.

Користите API када ваш програм треба податке из телефона или мора да управља позивом. Користите веб-куке када мора да реагује на позиве док се дешавају, без прозивања. Већина интеграција користи обоје; међусобно су независни.

Укључивање​

Отворите Подешавања → Повезивање и идите на Локално управљање.

  1. Укључите Дозволи другим програмима на овом рачунару да управљају телефоном. Сервер се одмах покреће.
  2. Задржите подразумевани Порт, 8377, осим ако га већ користи други програм.
  3. По жељи подесите Жетон. Након чувања поље приказује Сачувано — куцајте да замените.
  4. Под Приступ изаберите групе које желите да отворите: Контакти, Историја позива, Позиви и управљање њима, Налози, Подешавања, Бројачи (метрике). Искључена група се не филтрира, него се уопште не служи.
  5. Испробајте: curl http://127.0.0.1:8377/accounts. Ако је одговор JSON, API ради.

Не инсталира се засебна услуга и није потребно поновно покретање. Део програма који то ради може да се искључи у Модулима (Повезивање).

Сопствена страница API-ја​

Отвори сопствену страницу API-ја отвара http://127.0.0.1:8377 у прегледачу. Адреса одговара списком свега што служи, на енглеском; адресе које нешто читају су везе које можете да пратите.

Приступ и жетон​

Шта програм сме да ради зависи од тога да ли мења сачуване податке, а не од тога да ли чита:

  • Без жетона било који програм на рачунару сме да чита све у укљученим групама и да управља позивима: да упути, јави се, прекине, стави на чекање, настави, проследи и шаље DTMF.
  • Са жетоном у заглављу Authorization сме да користи и крајње тачке које мењају оно што је сачувано. Без жетона те крајње тачке се не наводе на сопственој страници API-ја и одговарају са 401. Ако жетон уопште није подешен, ништа не може да промени сачувано.

Жетон се чува у складишту кључева рачунара, не у датотеци подешавања, и /settings га никада не враћа.

опрез

Без жетона било који програм који ради на овом рачунару може да управља телефоном, укључујући јављање на позиве. На личној радној станици то је обично прихватљиво. На заједничком или управљаном рачунару подесите жетон и поступајте са њим као са било којом другом лозинком. Жетон штити само захтеве који мењају сачуване податке, а не позиве: ако желите да друге програме држите даље од позива, искључите Позиви и управљање њима под Приступ.

Крајње тачке​

Основна адреса је http://127.0.0.1:8377. Крајње тачке у наставку не захтевају жетон.

МетодПутањаШта ради
GET/metricsБројачи, у формату Prometheus.
GET/uiСписак снимака, као HTML страница.
GET/ui/recordings/{id}Снимак са преписом, као HTML страница.
GET/ui/recordings/{id}/audioЗвук за горњу страницу.
GET/contactsКонтакти.
GET/contacts/{id}Један контакт.
GET/historyДневник позива, од најновијих. Прихвата ?limit=, ?missed=true и ?declined=true.
GET/callsПозиви у току.
POST/callsУпућује позив: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerЈавља се на позив.
POST/calls/{id}/hangupПрекида позив.
POST/calls/{id}/holdСтавља позив на чекање.
POST/calls/{id}/resumeВраћа га са чекања.
POST/calls/{id}/dtmfШаље тонове: {"digits": "..."}.
POST/calls/{id}/transferПрослеђује позив: {"target": "..."}.
GET/accountsSIP налози и стање њихове регистрације. Никада лозинка.
GET/settingsЦела конфигурација, без тајни.
GET/taxonomyКатегорије, ознаке и упозорења, са њиховим кодовима.

Крајње тачке којима треба жетон​

Оне мењају оно што је сачувано, па сваки захтев мора да носи жетон у заглављу Authorization. Сопствена страница API-ја их приказује само захтеву који га носи.

МетодПутањаШта ради
POST/contactsДодаје контакт: {"name": "...", "number": "...", "account_id": "..."}; account_id није обавезан.
PUT/contacts/{id}Замењује контакт.
DELETE/contacts/{id}Уклања контакт.
DELETE/history/{id}Заборавља један позив из дневника позива.
DELETE/historyЗаборавља цео дневник позива. То се не може опозвати.
PUT/accounts/{id}Замењује подешавања налога. Лозинка није међу њима.
PUT/settingsЗамењује подешавања.

Сваки идентификатор је UUID који додељује телефон: id позива долази из /calls или из одговора на POST /calls, id налога из /accounts.

Називи поља су у snake_case-у, а завршетак говори о врсти: _id је референца на UUID, _ts је тренутак у Unix милисекундама (UTC), _s је трајање у секундама. Исто важи за веб-куке; само /settings има сопствене називе. У REST API-ју те вредности су JSON бројеви, а непознат тренутак је null.

Пример: упућивање позива​

POST /calls упућује одлазни позив. Тело је JSON са number који треба позвати и, по жељи, account_id налога са ког треба звати:

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

Одговор је идентификатор новог позива:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number је обавезан. Без њега одговор је 400 {"error":"a call needs a number"} и ништа се не бира.
  • Број се на изабраном налогу допуњује као што га допуњује поље за бирање: 1020 се шаље као sip:1020@pbx.example.com. POST /calls/{id}/transfer допуњује свој target на исти начин; циљ који већ има шему или @ шаље се такав какав јесте.
  • account_id је необавезан; узмите га из GET /accounts. Без њега позив иде са налога изабраног у главном прозору.
  • Користите id у /calls/{id}/…: hangup, hold, resume, dtmf и transfer. Веб-куке овог позива носе исти id.

Са веб-странице: клик за позив​

Страница која зове 127.0.0.1 долази до рачунара на ком ради прегледач — истог на ком ради телефон —, па дугме „клик за позив” у CRM-у не треба сопствени сервер:

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

Шта садрже одговори​

Позиви у току: GET /calls​

Сваки позив има свој id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts и callstate_ts.

  • state је dialing, ringing-out, ringing-in, active, hold (на чекање ставио овај телефон), onhold (на чекање ставила друга страна), conference или ended. Када важи више од једног, conference има предност над hold, а hold над onhold.
  • muted каже да ли је микрофон у позиву искључен; искључивање микрофона не мења state.
  • seance_id је разговор: позиви повезани прослеђивањем, консултацијом или конференцијом деле га.
  • event_ts је тренутак када је одговор настао. Упоредите га са callstate_ts да видите колико је дуго позив у свом стању, без ослањања на сопствени сат.

Налози: GET /accounts​

Сваки налог има свој id (свуда другде account_id), своја подешавања — transport (udp, tcp или tls), port, registrar, outbound_proxy, expiry_s и друга —, да ли је enabled, и свој state на централи: registered док је линија активна. Лозинке никада нису укључене.

Историја позива: GET /history​

Од најновијих, 100 ставки осим ако ?limit= каже другачије. ?missed=true враћа само пропуштене позиве, ?declined=true само позиве које је овај телефон одбио.

ПољеЗначење
idСопствени идентификатор ставке историје. То није id позива из /calls и веб-кука; повезује их seance_id.
outcomeГлавна класификација: answered, missed, declined или failed.
answeredtrue или false.
duration_s0 за позив који никада није успостављен.
number, uriДруга страна, као број и као SIP адреса.
nameИз Контаката ако је број познат, иначе празно. Упарујте по number, не по овоме.
dialedБиране цифре, за одлазни позив; празно за долазни.
account, account_idЛинија на којој је позив био.
reasonКако се завршио: local-hangup, remote-hangup, cancelled…
answered_byno ако се јавио човек; иначе оно што се јавило на позив.

Контакти: GET /contacts​

Сваки контакт има свој id, name, number и линију којој припада, account_id и account; празан account значи да контакт није везан за линију.

Снимци​

Снимци и преписи се не издају као JSON. API их служи као HTML странице, /ui и /ui/recordings/{id}: повезујте на те странице из свог CRM-а уместо премештања звука. Веза се отвара на рачунару који чува снимак, а звук га никада не напушта.

Таксономија и подешавања​

Свака ставка /taxonomy има сталан code, title и description на језику сучеља, kind (category, tag или red_flag) и, за упозорења, severity. Упарујте по code, никада по title: наслови долазе на језику на који је телефон подешен. Ставка са retired: true задржава се како би се старији позиви и даље разрешавали; новим позивима се више не додељује. Учитајте таксономију једном при покретању да речи телефона пресликате на сопствена поља.

/settings враћа конфигурацију осим тајни: звучне уређаје и јачине, приоритет кодека, изглед и језик, покретање, пречице, ниво дијагностике и стање обе интеграције — корисно за алат подршке који мора да провери радну станицу без дељења екрана. api.disabled наводи искључене групе приступа, а webhooks.silenced искључене догађаје; празни спискови значе да је све укључено. Никада не укључује SIP лозинку, жетон API-ја ни вредност заглавља веб-куке.

Грешке​

Свака грешка је JSON са једним кључем error, намењена људима, а не рашчлањивању.

СтатусТелоЗначење
404{"error":"no such endpoint"}Путања не постоји или је њена група приступа искључена; обоје намерно даје исти одговор.
405{"error":"that endpoint does not take this method"}Путања постоји, али не прима ту методу: на пример POST /settings уместо PUT.
401{"error":"writing needs a token, and none is configured"}Крајња тачка која мења сачувано, на телефону где је поље Жетон празно. Попуните га у Локално управљање.
401{"error":"this endpoint needs the authorization token"}Крајња тачка која мења сачувано, без исправног жетона.
404{"error":"no contact with that id"}Путања је исправна, идентификатор није.
400{"error":"no call with that id"}Позив се завршио или никада није постојао.
400{"error":"a call needs a number"}POST /calls без броја. Ништа није бирано.
400{"error":"no digits to send"}POST /calls/{id}/dtmf без цифара.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer без циља.
400{"error":"the account this call is on is no longer set up"}Налог позива је уклоњен током позива, па циљ не може да се допуни. Централи ништа није послато.

Одбијени захтеви броје се у api_requests_refused_total, па се интеграција која тихо не успева види у метрикама, а не само у вашим сопственим дневницима.

Метрике​

GET /metrics враћа сваки бројач телефона, сваки са текстом помоћи. Прикупљајте их Prometheus-ом или их читајте ручно.

БројачБроји
calls_incoming_totalПримљене долазне позиве.
calls_outgoing_totalУпућене одлазне позиве.
calls_answered_totalПозиве на које се неко јавио.
calls_missed_totalДолазне позиве на које се нико није јавио.
calls_declined_totalПозиве одбијене овде или на другој страни.
calls_failed_totalПозиве који нису могли да се успоставе.
registrations_succeeded_totalУспешне SIP регистрације.
registrations_failed_totalSIP регистрације одбијене или истекле.
webhooks_delivered_totalВеб-куке које је прималац прихватио.
webhooks_failed_totalВеб-куке одбијене или неиспоручене.
webhooks_dropped_totalВеб-куке одбачене јер је ред био пун.
api_requests_totalЗахтеве које је API обрадио.
api_requests_refused_totalОдбијене захтеве: погрешан жетон, искључена група или непозната путања.

Ажурирање старије интеграције​

Раније верзије су користиле називе у camelCase-у и кратке идентификаторе. accountId је сада account_id, startedAt је callstart_ts, durationSeconds је duration_s, answeredBy је answered_by, а поље веб-куке at је event_ts. Позиви и налози се идентификују само UUID-ом: runtimeId и идентификатори као што су call-3 или account-2 више се не враћају нити прихватају.

Када не ради​

СимптомШта проверити
Веза одбијена на 127.0.0.1:8377Локално управљање је искључено, телефон не ради или је порт промењен.
404 {"error":"no such endpoint"} за путању са ове страницеЊена група приступа је искључена.
Читање ради, писање се одбија са 401Крајњим тачкама које мењају сачуване податке треба жетон у заглављу Authorization, а на телефону најпре треба попунити поље Жетон.
Наслови категорија нису на енглескомНаслови прате језик сучеља. Упарујте по code из /taxonomy.
Недостају accountId, startedAt или atИнтеграција је писана за раније називе; погледајте горе.

За проблем са регистрацијом или самим позивом отворите Дијагностику.