Към основното съдържание

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

При проблем с регистрацията или със самото обаждане отворете Диагностика.