Ana içeriğe geç

Yerel REST API

AI Softphone'un CTI bütünleştirmesi için bir REST API'si vardır: aynı bilgisayardaki bir program çağrı yapabilir ve çağrıları yönetebilir, kişileri, çağrı geçmişini ve SIP hesaplarını okuyabilir ve süren çağrıları izleyebilir. SDK yok, bulutta aracı yok, ağa açık bir dinleyici yok. İstekler ve yanıtlar JSON'dur; bu yüzden curl ya da herhangi bir HTTP istemcisi yeterlidir.

API kurulumdan sonra kapalıdır; siz açana kadar hiçbir şey dinlemez. Açıldığında yalnızca geri döngü arayüzünde dinler — yalnızca bu bilgisayara yanıt veren küçük bir web arayüzü — ve ofis ağından, bir VPN'den ya da başka bir makineden erişilemez.

Programınızın telefondan veriye ihtiyacı olduğunda ya da bir çağrıyı yönetmesi gerektiğinde API'yi kullanın. Çağrılara, sorgulama yapmadan, gerçekleştikleri anda tepki vermesi gerektiğinde web kancalarını kullanın. Çoğu bütünleştirme ikisini de kullanır; birbirlerinden bağımsızdırlar.

Açma​

Ayarlar → Bütünleştirme bölümünü açın ve Yerel denetim kısmına gidin.

  1. Bu bilgisayardaki başka programlar telefonu yönetebilsin seçeneğini açın. Sunucu hemen başlar.
  2. Başka bir program zaten kullanmıyorsa öntanımlı Kapı değerini, 8377, koruyun.
  3. İsteğe bağlı olarak bir Belirteç belirleyin. Kaydedildikten sonra alan Kaydedildi — değiştirmek için yazın gösterir.
  4. Erişim altında açılacak grupları seçin: Kişiler, Çağrı geçmişi, Çağrılar ve onların yönetimi, Hesaplar, Ayarlar, Sayaçlar (ölçümler). Kapalı bir grup süzülmez, hiç sunulmaz.
  5. Sınayın: curl http://127.0.0.1:8377/accounts. Yanıt JSON ise API çalışıyordur.

Ayrı bir hizmet kurulmaz ve yeniden başlatma gerekmez. Programın bunu yapan bölümü Modüller (Bütünleştirme) içinde kapatılabilir.

API'nin kendi sayfası​

API'nin kendi sayfasını aç, http://127.0.0.1:8377 adresini bir tarayıcıda açar. Adres, sunduğu her şeyin bir listesiyle İngilizce olarak yanıt verir; bir şey okuyan adresler izleyebileceğiniz bağlantılardır.

Erişim ve belirteç​

Bir programın neler yapabileceği, okuyup okumamasına değil, saklanan verileri değiştirip değiştirmediğine bağlıdır:

  • Belirteç olmadan, bilgisayardaki herhangi bir program etkin gruplardaki her şeyi okuyabilir ve çağrıları yönetebilir: arama yapma, yanıtlama, kapatma, bekletme, sürdürme, aktarma ve DTMF gönderme.
  • Authorization başlığında belirteçle, saklananları değiştiren uç noktaları da kullanabilir. Belirteç olmadan bu uç noktalar API'nin kendi sayfasında listelenmez ve 401 ile yanıt verir. Hiç belirteç ayarlanmamışsa saklananları hiçbir şey değiştiremez.

Belirteç ayar dosyasında değil, bilgisayarın anahtarlığında saklanır ve /settings tarafından asla döndürülmez.

dikkat

Belirteç olmadan, bu bilgisayarda çalışan herhangi bir program telefonu yönetebilir, çağrıları yanıtlamak dahil. Kişisel bir iş istasyonunda bu genellikle kabul edilebilir. Paylaşılan ya da yönetilen bir makinede bir belirteç belirleyin ve ona diğer parolalar gibi davranın. Belirteç yalnızca kayıtlı verileri değiştiren istekleri korur, çağrıları değil: diğer programları çağrılardan uzak tutmak için Erişim altında Çağrılar ve onların yönetimi grubunu kapatın.

Uç noktalar​

Temel adres http://127.0.0.1:8377'dir. Aşağıdaki uç noktalar belirteç gerektirmez.

YöntemYolNe yapar
GET/metricsSayaçlar, Prometheus biçiminde.
GET/uiKayıtların listesi, bir HTML sayfası olarak.
GET/ui/recordings/{id}Dökümüyle birlikte bir kayıt, bir HTML sayfası olarak.
GET/ui/recordings/{id}/audioYukarıdaki sayfanın sesi.
GET/contactsKişiler.
GET/contacts/{id}Tek bir kişi.
GET/historyÇağrı geçmişi, en yenisi önce. ?limit=, ?missed=true ve ?declined=true kabul eder.
GET/callsSüren çağrılar.
POST/callsBir çağrı yapar: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerBir çağrıyı yanıtlar.
POST/calls/{id}/hangupBir çağrıyı kapatır.
POST/calls/{id}/holdBir çağrıyı beklemeye alır.
POST/calls/{id}/resumeOnu beklemeden çıkarır.
POST/calls/{id}/dtmfTon gönderir: {"digits": "..."}.
POST/calls/{id}/transferÇağrıyı aktarır: {"target": "..."}.
GET/accountsSIP hesapları ve kayıt durumları. Asla parola değil.
GET/settingsGizli bilgiler olmadan tüm yapılandırma.
GET/taxonomyKodlarıyla birlikte kategoriler, etiketler ve uyarı işaretleri.

Belirteç isteyen uç noktalar​

Bunlar saklananları değiştirir, bu yüzden her istek Authorization başlığında belirteci taşımalıdır. API'nin kendi sayfası onları yalnızca belirteci taşıyan bir isteğe gösterir.

YöntemYolNe yapar
POST/contactsBir kişi ekler: {"name": "...", "number": "...", "account_id": "..."}; account_id isteğe bağlıdır.
PUT/contacts/{id}Bir kişiyi değiştirir.
DELETE/contacts/{id}Bir kişiyi kaldırır.
DELETE/history/{id}Çağrı geçmişinden bir çağrıyı unutur.
DELETE/historyTüm çağrı geçmişini unutur. Geri alınamaz.
PUT/accounts/{id}Bir hesabın ayarlarını değiştirir. Parola bunların arasında değildir.
PUT/settingsAyarları değiştirir.

Her tanımlayıcı telefonun verdiği bir UUID'dir: bir çağrının id değeri /calls ya da POST /calls yanıtından, bir hesabın id değeri /accounts'tan gelir.

Alan adları snake_case biçimindedir ve sonek türü belirtir: _id bir UUID'ye başvurudur, _ts Unix milisaniyesi cinsinden bir andır (UTC), _s saniye cinsinden bir süredir. Aynısı web kancaları için de geçerlidir; yalnızca /settings kendi adlarını korur. REST API'de bu değerler JSON sayılarıdır ve bilinmeyen bir an null olur.

Örnek: çağrı yapma​

POST /calls giden bir çağrı yapar. Gövde, aranacak number değerini ve isteğe bağlı olarak aramanın yapılacağı hesabın account_id değerini içeren JSON'dur:

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

Yanıt, yeni çağrının tanımlayıcısıdır:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number zorunludur. O olmadan yanıt 400 {"error":"a call needs a number"} olur ve hiçbir şey aranmaz.
  • Numara, seçilen hesapta çeviricinin tamamladığı gibi tamamlanır: 1020, sip:1020@pbx.example.com olarak gönderilir. POST /calls/{id}/transfer da target değerini aynı şekilde tamamlar; zaten bir şeması ya da @ işareti olan bir hedef olduğu gibi gönderilir.
  • account_id isteğe bağlıdır; onu GET /accounts'tan alın. O olmadan çağrı ana pencerede seçili hesaptan yapılır.
  • id değerini /calls/{id}/… içinde kullanın: hangup, hold, resume, dtmf ve transfer. Bu çağrının web kancaları aynı id değerini taşır.

Bir web sayfasından: tıkla ve ara​

127.0.0.1 adresini çağıran bir sayfa, tarayıcının çalıştığı bilgisayara — telefonun çalıştığı bilgisayarın ta kendisine — ulaşır; bu yüzden bir CRM'deki "tıkla ve ara" düğmesinin kendi sunucusuna ihtiyacı yoktur:

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

Yanıtlar ne içerir​

Süren çağrılar: GET /calls​

Her çağrının kendi id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts ve callstate_ts değerleri vardır.

  • state değeri dialing, ringing-out, ringing-in, active, hold (bu telefon tarafından bekletilen), onhold (karşı taraf tarafından bekletilen), conference ya da ended olur. Birden fazlası geçerli olduğunda conference, hold'a; hold da onhold'a üstün gelir.
  • muted, çağrıda mikrofonun sesinin kapalı olup olmadığını söyler; sesi kapatmak state değerini değiştirmez.
  • seance_id görüşmedir: bir aktarma, bir danışma ya da bir konferansla bağlanan çağrılar onu paylaşır.
  • event_ts, yanıtın oluşturulduğu andır. Kendi saatinize güvenmeden, çağrının ne kadar süredir o durumda olduğunu görmek için onu callstate_ts ile karşılaştırın.

Hesaplar: GET /accounts​

Her hesabın kendi id değeri (başka her yerde account_id), ayarları — transport (udp, tcp ya da tls), port, registrar, outbound_proxy, expiry_s ve diğerleri —, enabled olup olmadığı ve santraldeki state değeri vardır: hat çalışırken registered. Parolalar asla dahil edilmez.

Çağrı geçmişi: GET /history​

En yenisi önce, ?limit= başka bir şey söylemedikçe 100 girdi. ?missed=true yalnızca cevapsız çağrıları, ?declined=true yalnızca bu telefonun reddettiği çağrıları döndürür.

AlanAnlamı
idGeçmiş girdisinin kendi tanımlayıcısı. /calls ve web kancalarındaki çağrı id değeri değildir; ikisini seance_id bağlar.
outcomeAna sınıflandırma: answered, missed, declined ya da failed.
answeredtrue ya da false.
duration_sHiç bağlanmamış bir çağrı için 0.
number, uriKarşı taraf, numara olarak ve SIP adresi olarak.
nameNumara biliniyorsa Kişiler'den, aksi hâlde boş. Buna göre değil, number alanına göre eşleştirin.
dialedGiden bir çağrı için tuşlanan rakamlar; gelen bir çağrı için boş.
account, account_idÇağrının bulunduğu hat.
reasonNasıl bittiği: local-hangup, remote-hangup, cancelled…
answered_byBir insan yanıtladıysa no; aksi hâlde çağrıyı yanıtlayan şey.

Kişiler: GET /contacts​

Her kişinin kendi id, name, number değerleri ve ait olduğu hat, account_id ve account vardır; boş bir account, kişinin bir hatta bağlı olmadığı anlamına gelir.

Kayıtlar​

Kayıtlar ve dökümler JSON olarak verilmez. API onları /ui ve /ui/recordings/{id} HTML sayfaları olarak sunar: sesi bir yerden bir yere taşımak yerine CRM'inizden bu sayfalara bağlantı verin. Bağlantı, kaydı tutan bilgisayarda açılır ve ses o bilgisayardan asla çıkmaz.

Sınıflandırma ve ayarlar​

/taxonomy içindeki her girdinin sabit bir code değeri, arayüz dilinde bir title ve bir description değeri, bir kind değeri (category, tag ya da red_flag) ve uyarı işaretleri için bir severity değeri vardır. Asla title ile değil, code ile eşleştirin: başlıklar telefonun ayarlandığı dilde gelir. retired: true olan bir girdi, eski çağrılar yine çözümlenebilsin diye tutulur; artık yeni çağrılara verilmez. Telefonun sözcüklerini kendi alanlarınıza eşlemek için sınıflandırmayı başlangıçta bir kez yükleyin.

/settings, gizli bilgiler dışında yapılandırmayı döndürür: ses aygıtları ve ses düzeyleri, kodek önceliği, görünüm ve dil, başlangıç, kısayollar, tanılama düzeyi ve iki bütünleştirmenin durumu — bir iş istasyonunu ekran paylaşmadan denetlemesi gereken bir destek aracı için yararlıdır. api.disabled kapalı erişim gruplarını, webhooks.silenced ise kapalı olayları listeler; boş listeler her şeyin açık olduğu anlamına gelir. SIP parolasını, API belirtecini ya da web kancası başlık değerini asla içermez.

Hatalar​

Her hata, tek bir error anahtarı olan bir JSON'dur; ayrıştırma için değil, insanlar için tasarlanmıştır.

DurumGövdeAnlamı
404{"error":"no such endpoint"}Yol yok ya da erişim grubu kapalı; ikisi de bilerek aynı yanıtı verir.
405{"error":"that endpoint does not take this method"}Yol var, ama bu yöntemi kabul etmiyor: örneğin PUT yerine POST /settings.
401{"error":"writing needs a token, and none is configured"}Saklananları değiştiren bir uç nokta, Belirteç alanının boş olduğu bir telefonda. Bu alanı Yerel denetim altında doldurun.
401{"error":"this endpoint needs the authorization token"}Saklananları değiştiren bir uç nokta, doğru belirteç olmadan.
404{"error":"no contact with that id"}Yol doğru, tanımlayıcı yanlış.
400{"error":"no call with that id"}Çağrı bitti ya da hiç var olmadı.
400{"error":"a call needs a number"}Numarasız POST /calls. Hiçbir şey aranmadı.
400{"error":"no digits to send"}Rakamsız POST /calls/{id}/dtmf.
400{"error":"a transfer needs a target"}Hedefsiz POST /calls/{id}/transfer.
400{"error":"the account this call is on is no longer set up"}Çağrının hesabı çağrı sırasında kaldırıldı; bu yüzden hedef tamamlanamıyor. Santrale hiçbir şey gönderilmedi.

Reddedilen istekler api_requests_refused_total içinde sayılır; böylece sessizce başarısız olan bir bütünleştirme yalnızca kendi günlüklerinizde değil, ölçümlerde de görünür.

Ölçümler​

GET /metrics, telefonun her sayacını, her birini bir yardım metniyle birlikte döndürür. Onları Prometheus ile toplayın ya da elle okuyun.

SayaçNeyi sayar
calls_incoming_totalAlınan gelen çağrılar.
calls_outgoing_totalYapılan giden çağrılar.
calls_answered_totalYanıtlanan çağrılar.
calls_missed_totalYanıtlanmayan gelen çağrılar.
calls_declined_totalBurada ya da karşı tarafta reddedilen çağrılar.
calls_failed_totalKurulamayan çağrılar.
registrations_succeeded_totalBaşarılı SIP kayıtları.
registrations_failed_totalReddedilen ya da zaman aşımına uğrayan SIP kayıtları.
webhooks_delivered_totalAlıcının kabul ettiği web kancaları.
webhooks_failed_totalReddedilen ya da teslim edilemeyen web kancaları.
webhooks_dropped_totalKuyruk dolu olduğu için atılan web kancaları.
api_requests_totalAPI'nin işlediği istekler.
api_requests_refused_totalReddedilen istekler: yanlış belirteç, kapalı grup ya da bilinmeyen yol.

Eski bir bütünleştirmeyi güncelleme​

Önceki sürümler camelCase adlar ve kısa tanımlayıcılar kullanıyordu. accountId artık account_id, startedAt artık callstart_ts, durationSeconds artık duration_s, answeredBy artık answered_by, web kancası alanı at ise artık event_ts'dir. Çağrılar ve hesaplar yalnızca UUID ile tanımlanır: runtimeId ve call-3 ya da account-2 gibi tanımlayıcılar artık ne döndürülür ne de kabul edilir.

Çalışmadığında​

BelirtiNeyi denetlemeli
127.0.0.1:8377 üzerinde bağlantı reddedildiYerel denetim kapalı, telefon çalışmıyor ya da kapı değiştirildi.
Bu sayfadaki bir yol için 404 {"error":"no such endpoint"}Yolun erişim grubu kapalı.
Okuma çalışıyor, yazma 401 ile reddediliyorSaklanan verileri değiştiren uç noktalar Authorization başlığında belirteç gerektirir ve telefonda önce Belirteç alanının doldurulması gerekir.
Kategori başlıkları İngilizce değilBaşlıklar arayüz dilini izler. /taxonomy içindeki code ile eşleştirin.
accountId, startedAt ya da at eksikBütünleştirme önceki adlara göre yazılmış; yukarıya bakın.

Kayıtla ya da bir çağrının kendisiyle ilgili bir sorun için Tanılama penceresini açın.