Локални REST API
AI Softphone има REST API за CTI интеграцију: програм на истом рачунару може да упућује позиве и управља њима, чита контакте, историју позива и SIP налоге и прати позиве у току. Без SDK-а, без посредника у облаку и без слушаоца изложеног мрежи. Захтеви и одговори су JSON, па је довољан curl или било који HTTP клијент.
API је након инсталације искључен; ништа не слуша док га не укључите. Тада слуша само на loopback сучељу — малом веб-сучељу које одговара само овом рачунару — и није доступан из канцеларијске мреже, VPN-а нити са другог рачунара.
Користите API када ваш програм треба податке из телефона или мора да управља позивом. Користите веб-куке када мора да реагује на позиве док се дешавају, без прозивања. Већина интеграција користи обоје; међусобно су независни.
Укључивање
Отворите Подешавања → Повезивање и идите на Локално управљање.
- Укључите Дозволи другим програмима на овом рачунару да управљају телефоном. Сервер се одмах покреће.
- Задржите подразумевани Порт,
8377, осим ако га већ користи други програм. - По жељи подесите Жетон. Након чувања поље приказује Сачувано — куцајте да замените.
- Под Приступ изаберите групе које желите да отворите: Контакти, Историја позива, Позиви и управљање њима, Налози, Подешавања, Бројачи (метрике). Искључена група се не филтрира, него се уопште не служи.
- Испробајте:
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 | /accounts | SIP налози и стање њихове регистрације. Никада лозинка. |
| 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. |
answered | true или false. |
duration_s | 0 за позив који никада није успостављен. |
number, uri | Друга страна, као број и као SIP адреса. |
name | Из Контаката ако је број познат, иначе празно. Упарујте по number, не по овоме. |
dialed | Биране цифре, за одлазни позив; празно за долазни. |
account, account_id | Линија на којој је позив био. |
reason | Како се завршио: local-hangup, remote-hangup, cancelled… |
answered_by | no ако се јавио човек; иначе оно што се јавило на позив. |
Контакти: 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_total | SIP регистрације одбијене или истекле. |
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 | Интеграција је писана за раније називе; погледајте горе. |
За проблем са регистрацијом или самим позивом отворите Дијагностику.