Локален 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 | Интеграцията е писана за по-ранните имена; вижте по-горе. |
При проблем с регистрацията или със самото обаждане отворете Диагностика.