Przejdź do głównej treści

Lokalne REST API

AI Softphone ma REST API do integracji CTI: program na tym samym komputerze może wykonywać połączenia i nimi sterować, odczytywać kontakty, historię połączeń i konta SIP oraz obserwować trwające połączenia. Bez SDK, bez pośrednika w chmurze i bez nasłuchu wystawionego do sieci. Żądania i odpowiedzi to JSON, więc wystarczy curl albo dowolny klient HTTP.

API jest wyłączone po instalacji; nic nie nasłuchuje, dopóki go nie włączysz. Wtedy nasłuchuje tylko na interfejsie pętli zwrotnej — mały interfejs WWW, który odpowiada tylko temu komputerowi — i nie jest osiągalne z sieci biurowej, VPN ani z innej maszyny.

Używaj API, gdy twój program potrzebuje danych z telefonu albo musi sterować połączeniem. Używaj webhooków, gdy musi reagować na połączenia na bieżąco, bez odpytywania. Większość integracji używa obu; są od siebie niezależne.

Włączanie​

Otwórz Ustawienia → Integracja i przejdź do Sterowanie lokalne.

  1. Włącz Pozwól innym programom na tym komputerze sterować telefonem. Serwer startuje od razu.
  2. Zostaw domyślny Port, 8377, chyba że używa go już inny program.
  3. Opcjonalnie ustaw Token. Po zapisaniu pole pokazuje Zapisane — wpisz, by zastąpić.
  4. W sekcji Dostęp wybierz grupy do otwarcia: Kontakty, Historia połączeń, Połączenia i ich obsługa, Konta, Ustawienia, Liczniki (metryki). Wyłączona grupa nie jest filtrowana, tylko w ogóle nie jest obsługiwana.
  5. Sprawdź: curl http://127.0.0.1:8377/accounts. Jeśli odpowiedzią jest JSON, API działa.

Nie instaluje się żadnej osobnej usługi i nie trzeba niczego uruchamiać ponownie. Część programu, która za to odpowiada, można wyłączyć w Modułach (Integracja).

Własna strona API​

Otwórz własną stronę API otwiera http://127.0.0.1:8377 w przeglądarce. Adres odpowiada listą wszystkiego, co obsługuje, po angielsku; adresy, które coś odczytują, są odnośnikami, w które można kliknąć.

Dostęp i token​

To, co program może robić, zależy od tego, czy zmienia zapisane dane, a nie od tego, czy odczytuje:

  • Bez tokenu każdy program na komputerze może odczytywać wszystko we włączonych grupach i sterować połączeniami: wykonywać, odbierać, rozłączać, zawieszać, wznawiać, przekazywać i wysyłać DTMF.
  • Z tokenem w nagłówku Authorization może też używać punktów końcowych, które zmieniają to, co zapisane. Bez tokenu te punkty końcowe nie są wymieniane na własnej stronie API i odpowiadają 401. Gdy token w ogóle nie jest ustawiony, nic nie może zmienić tego, co zapisane.

Token jest przechowywany w pęku kluczy komputera, nie w pliku ustawień, i nigdy nie jest zwracany przez /settings.

ostrożnie

Bez tokenu każdy program działający na tym komputerze może sterować telefonem, łącznie z odbieraniem połączeń. Na osobistym stanowisku zwykle jest to do przyjęcia. Na współdzielonej lub zarządzanej maszynie ustaw token i traktuj go jak każde inne hasło. Token chroni tylko żądania, które zmieniają zapisane dane, a nie połączenia: aby inne programy nie miały dostępu do połączeń, wyłącz Połączenia i ich obsługa w sekcji Dostęp.

Punkty końcowe​

Adres bazowy to http://127.0.0.1:8377. Poniższe punkty końcowe nie wymagają tokenu.

MetodaŚcieżkaCo robi
GET/metricsLiczniki w formacie Prometheus.
GET/uiLista nagrań jako strona HTML.
GET/ui/recordings/{id}Nagranie z transkrypcją jako strona HTML.
GET/ui/recordings/{id}/audioDźwięk do powyższej strony.
GET/contactsKontakty.
GET/contacts/{id}Pojedynczy kontakt.
GET/historyDziennik połączeń, od najnowszych. Przyjmuje ?limit=, ?missed=true i ?declined=true.
GET/callsTrwające połączenia.
POST/callsWykonuje połączenie: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerOdbiera połączenie.
POST/calls/{id}/hangupRozłącza połączenie.
POST/calls/{id}/holdZawiesza połączenie.
POST/calls/{id}/resumeWznawia je.
POST/calls/{id}/dtmfWysyła tony: {"digits": "..."}.
POST/calls/{id}/transferPrzekazuje połączenie: {"target": "..."}.
GET/accountsKonta SIP i stan ich rejestracji. Nigdy hasło.
GET/settingsCała konfiguracja, bez sekretów.
GET/taxonomyKategorie, etykiety i sygnały ostrzegawcze, z ich kodami.

Punkty końcowe, które wymagają tokenu​

Zmieniają to, co zapisane, więc każde żądanie musi nieść token w nagłówku Authorization. Własna strona API pokazuje je tylko żądaniu, które go niesie.

MetodaŚcieżkaCo robi
POST/contactsDodaje kontakt: {"name": "...", "number": "...", "account_id": "..."}; account_id jest opcjonalne.
PUT/contacts/{id}Zastępuje kontakt.
DELETE/contacts/{id}Usuwa kontakt.
DELETE/history/{id}Zapomina jedno połączenie z rejestru połączeń.
DELETE/historyZapomina cały rejestr połączeń. Nie da się tego cofnąć.
PUT/accounts/{id}Zastępuje ustawienia konta. Hasła wśród nich nie ma.
PUT/settingsZastępuje ustawienia.

Każdy identyfikator to UUID nadany przez telefon: id połączenia pochodzi z /calls albo z odpowiedzi na POST /calls, id konta z /accounts.

Nazwy pól są w snake_case, a końcówka mówi o typie: _id to odwołanie do UUID, _ts to moment w milisekundach uniksowych (UTC), _s to długość w sekundach. To samo dotyczy webhooków; tylko /settings ma własne nazwy. W REST API te wartości są liczbami JSON, a nieznany moment to null.

Przykład: wykonanie połączenia​

POST /calls wykonuje połączenie wychodzące. Treść to JSON z number do wybrania i, opcjonalnie, account_id konta, z którego dzwonić:

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

Odpowiedzią jest identyfikator nowego połączenia:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number jest wymagany. Bez niego odpowiedź to 400 {"error":"a call needs a number"} i nic nie jest wybierane.
  • Numer jest uzupełniany na wybranym koncie tak, jak uzupełnia go pole wybierania: 1020 jest wysyłany jako sip:1020@pbx.example.com. POST /calls/{id}/transfer uzupełnia swój target w ten sam sposób; cel, który ma już schemat lub @, jest wysyłany bez zmian.
  • account_id jest opcjonalne; weź je z GET /accounts. Bez niego połączenie idzie z konta wybranego w oknie głównym.
  • Używaj id w /calls/{id}/…: hangup, hold, resume, dtmf i transfer. Webhooki tego połączenia mają to samo id.

Ze strony WWW: kliknij, aby zadzwonić​

Strona, która wywołuje 127.0.0.1, trafia do komputera, na którym działa przeglądarka — tego samego, na którym działa telefon — więc przycisk „kliknij, aby zadzwonić” w CRM nie potrzebuje własnego serwera:

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

Co zawierają odpowiedzi​

Trwające połączenia: GET /calls​

Każde połączenie ma swoje id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts i callstate_ts.

  • state to dialing, ringing-out, ringing-in, active, hold (zawieszone przez ten telefon), onhold (zawieszone przez drugą stronę), conference lub ended. Gdy pasuje więcej niż jeden, conference ma pierwszeństwo przed hold, a hold przed onhold.
  • muted mówi, czy mikrofon w połączeniu jest wyciszony; wyciszenie nie zmienia state.
  • seance_id to rozmowa: połączenia powiązane przekazaniem, konsultacją lub konferencją mają go wspólnego.
  • event_ts to chwila, w której udzielono odpowiedzi. Porównaj go z callstate_ts, aby zobaczyć, jak długo połączenie jest w swoim stanie, bez polegania na własnym zegarze.

Konta: GET /accounts​

Każde konto ma swoje id (account_id wszędzie indziej), swoje ustawienia — transport (udp, tcp lub tls), port, registrar, outbound_proxy, expiry_s i inne — czy jest enabled oraz swój state w centrali: registered, gdy linia działa. Hasła nigdy nie są dołączane.

Historia połączeń: GET /history​

Od najnowszych, 100 wpisów, chyba że ?limit= mówi inaczej. ?missed=true zwraca tylko nieodebrane połączenia, ?declined=true tylko połączenia odrzucone przez ten telefon.

PoleZnaczenie
idWłasny identyfikator wpisu historii. To nie jest id połączenia z /calls i webhooków; łączy je seance_id.
outcomeGłówna klasyfikacja: answered, missed, declined lub failed.
answeredtrue lub false.
duration_s0 dla połączenia, które nigdy nie zostało zestawione.
number, uriDruga strona, jako numer i jako adres SIP.
nameZ Kontaktów, jeśli numer jest znany, w przeciwnym razie puste. Dopasowuj po number, nie po tym.
dialedWybrane cyfry, dla połączenia wychodzącego; puste dla przychodzącego.
account, account_idLinia, na której było połączenie.
reasonJak się zakończyło: local-hangup, remote-hangup, cancelled…
answered_byno, jeśli odebrał człowiek; w przeciwnym razie to, co odebrało połączenie.

Kontakty: GET /contacts​

Każdy kontakt ma swoje id, name, number i linię, do której należy, account_id i account; puste account oznacza, że kontakt nie jest przypisany do linii.

Nagrania​

Nagrania i transkrypcje nie są wydawane jako JSON. API udostępnia je jako strony HTML, /ui i /ui/recordings/{id}: linkuj do tych stron z CRM zamiast przenosić dźwięk. Odnośnik otwiera się na komputerze, który przechowuje nagranie, a dźwięk nigdy go nie opuszcza.

Taksonomia i ustawienia​

Każdy wpis /taxonomy ma stały code, title i description w języku interfejsu, kind (category, tag lub red_flag) oraz, dla sygnałów ostrzegawczych, severity. Dopasowuj po code, nigdy po title: tytuły są w języku, na który ustawiony jest telefon. Wpis z retired: true jest zachowany, aby starsze połączenia nadal się rozwiązywały; nie jest już nadawany nowym połączeniom. Wczytaj taksonomię raz przy starcie, aby odwzorować słowa telefonu na własne pola.

/settings zwraca konfigurację oprócz sekretów: urządzenia dźwiękowe i głośności, priorytet kodeków, wygląd i język, uruchamianie, skróty klawiszowe, poziom diagnostyki i stan obu integracji — przydatne dla narzędzia wsparcia, które ma sprawdzić stanowisko bez udostępniania ekranu. api.disabled wymienia wyłączone grupy dostępu, a webhooks.silenced wyłączone zdarzenia; puste listy oznaczają, że wszystko jest włączone. Nigdy nie zawiera hasła SIP, tokenu API ani wartości nagłówka webhooka.

Błędy​

Każdy błąd to JSON z jednym kluczem error, przeznaczony dla ludzi, nie do parsowania.

StatusTreśćZnaczenie
404{"error":"no such endpoint"}Ścieżka nie istnieje albo jej grupa dostępu jest wyłączona; oba przypadki celowo dają tę samą odpowiedź.
405{"error":"that endpoint does not take this method"}Ścieżka istnieje, ale nie przyjmuje tej metody: na przykład POST /settings zamiast PUT.
401{"error":"writing needs a token, and none is configured"}Punkt końcowy, który zmienia to, co zapisane, na telefonie, gdzie pole Token jest puste. Wypełnij je w Sterowanie lokalne.
401{"error":"this endpoint needs the authorization token"}Punkt końcowy, który zmienia to, co zapisane, bez właściwego tokenu.
404{"error":"no contact with that id"}Ścieżka jest prawidłowa, identyfikator nie.
400{"error":"no call with that id"}Połączenie się zakończyło albo nigdy nie istniało.
400{"error":"a call needs a number"}POST /calls bez numeru. Nic nie zostało wybrane.
400{"error":"no digits to send"}POST /calls/{id}/dtmf bez cyfr.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer bez celu.
400{"error":"the account this call is on is no longer set up"}Konto połączenia zostało usunięte w trakcie połączenia, więc celu nie da się uzupełnić. Nic nie zostało wysłane do centrali.

Odrzucone żądania są liczone w api_requests_refused_total, więc integracja, która po cichu zawodzi, jest widoczna w metrykach, a nie tylko w twoich własnych dziennikach.

Metryki​

GET /metrics zwraca każdy licznik telefonu, każdy z tekstem pomocy. Zbieraj je Prometheusem albo czytaj ręcznie.

LicznikLiczy
calls_incoming_totalOdebrane połączenia przychodzące.
calls_outgoing_totalWykonane połączenia wychodzące.
calls_answered_totalPołączenia, które zostały odebrane.
calls_missed_totalPołączenia przychodzące, które nie zostały odebrane.
calls_declined_totalPołączenia odrzucone tutaj lub przez drugą stronę.
calls_failed_totalPołączenia, których nie udało się zestawić.
registrations_succeeded_totalUdane rejestracje SIP.
registrations_failed_totalRejestracje SIP odrzucone lub przerwane po przekroczeniu czasu.
webhooks_delivered_totalWebhooki przyjęte przez odbiorcę.
webhooks_failed_totalWebhooki odrzucone lub niedostarczone.
webhooks_dropped_totalWebhooki porzucone, bo kolejka była pełna.
api_requests_totalŻądania obsłużone przez API.
api_requests_refused_totalOdrzucone żądania: zły token, wyłączona grupa lub nieznana ścieżka.

Aktualizacja starszej integracji​

Wcześniejsze wersje używały nazw w camelCase i krótkich identyfikatorów. accountId to teraz account_id, startedAt to callstart_ts, durationSeconds to duration_s, answeredBy to answered_by, a pole webhooka at to event_ts. Połączenia i konta są identyfikowane wyłącznie przez UUID: runtimeId i identyfikatory takie jak call-3 czy account-2 nie są już zwracane ani przyjmowane.

Gdy to nie działa​

ObjawCo sprawdzić
Odmowa połączenia na 127.0.0.1:8377Sterowanie lokalne jest wyłączone, telefon nie działa albo zmieniono port.
404 {"error":"no such endpoint"} dla ścieżki z tej stronyJej grupa dostępu jest wyłączona.
Odczyt działa, zapis jest odrzucany z 401Punkty końcowe, które zmieniają zapisane dane, wymagają tokenu w nagłówku Authorization, a na telefonie trzeba najpierw wypełnić pole Token.
Tytuły kategorii nie są po angielskuTytuły idą za językiem interfejsu. Dopasowuj po code z /taxonomy.
Brakuje accountId, startedAt lub atIntegracja została napisana dla wcześniejszych nazw; zobacz wyżej.

W przypadku problemu z rejestracją lub samym połączeniem otwórz Diagnostykę.