Langsung ke konten utama

REST API lokal

AI Softphone memiliki REST API untuk integrasi CTI: program di komputer yang sama dapat melakukan dan mengendalikan panggilan, membaca kontak, riwayat panggilan, dan akun SIP, serta memantau panggilan yang sedang berlangsung. Tanpa SDK, tanpa perantara cloud, dan tanpa pendengar yang terbuka ke jaringan. Permintaan dan jawaban berupa JSON, jadi curl atau klien HTTP apa pun sudah cukup.

API mati setelah instalasi; tidak ada yang mendengarkan sampai Anda menyalakannya. Setelah itu API hanya mendengarkan di antarmuka loopback — antarmuka web kecil yang hanya menjawab komputer ini — dan tidak dapat dijangkau dari jaringan kantor, VPN, atau komputer lain.

Gunakan API ketika program Anda memerlukan data dari telepon atau harus mengendalikan panggilan. Gunakan webhook ketika program harus bereaksi terhadap panggilan saat terjadi, tanpa polling. Sebagian besar integrasi menggunakan keduanya; keduanya tidak saling bergantung.

Menyalakannya​

Buka Pengaturan → Integrasi dan pergi ke Kendali lokal.

  1. Nyalakan Izinkan program lain di komputer ini mengendalikan telepon. Server langsung berjalan.
  2. Pertahankan Porta bawaan, 8377, kecuali program lain sudah menggunakannya.
  3. Secara opsional, atur Token. Setelah disimpan, kolom menampilkan Tersimpan — ketik untuk menggantinya.
  4. Di bawah Akses, pilih kelompok yang akan dibuka: Kontak, Riwayat panggilan, Panggilan, dan kendalinya, Akun, Pengaturan, Pencacah (metrik). Kelompok yang mati bukan disaring, melainkan sama sekali tidak dilayani.
  5. Ujilah: curl http://127.0.0.1:8377/accounts. Jika jawabannya JSON, API berfungsi.

Tidak ada layanan terpisah yang dipasang dan tidak perlu memulai ulang. Bagian program yang melakukan ini dapat dimatikan di Modul (Integrasi).

Halaman API sendiri​

Buka halaman API sendiri membuka http://127.0.0.1:8377 di peramban. Alamat itu menjawab dengan daftar semua yang dilayaninya, dalam bahasa Inggris; alamat yang membaca sesuatu berupa tautan yang dapat Anda ikuti.

Akses dan token​

Apa yang boleh dilakukan sebuah program bergantung pada apakah ia mengubah data yang tersimpan, bukan pada apakah ia membaca:

  • Tanpa token, program apa pun di komputer boleh membaca semua yang ada di kelompok yang diaktifkan dan mengendalikan panggilan: melakukan, menjawab, menutup, menahan, melanjutkan, mengalihkan, dan mengirim DTMF.
  • Dengan token di tajuk Authorization, program juga boleh menggunakan endpoint yang mengubah apa yang tersimpan. Tanpa token, endpoint tersebut tidak dicantumkan di halaman API sendiri dan menjawab 401. Jika token sama sekali tidak diatur, tidak ada yang bisa mengubah apa yang tersimpan.

Token disimpan di gantungan kunci komputer, bukan di berkas pengaturan, dan tidak pernah dikembalikan oleh /settings.

waspada

Tanpa token, program apa pun yang berjalan di komputer ini dapat mengendalikan telepon, termasuk menjawab panggilan. Di komputer kerja pribadi, hal itu biasanya dapat diterima. Di komputer bersama atau yang dikelola, atur token dan perlakukan seperti kata sandi lainnya. Token hanya melindungi permintaan yang mengubah data tersimpan, bukan panggilan: agar program lain tidak dapat menyentuh panggilan, matikan Panggilan, dan kendalinya di bawah Akses.

Endpoint​

Alamat dasarnya http://127.0.0.1:8377. Endpoint di bawah ini tidak memerlukan token.

MetodeJalurFungsi
GET/metricsPencacah, dalam format Prometheus.
GET/uiDaftar rekaman, sebagai halaman HTML.
GET/ui/recordings/{id}Sebuah rekaman beserta transkripnya, sebagai halaman HTML.
GET/ui/recordings/{id}/audioAudio untuk halaman di atas.
GET/contactsKontak.
GET/contacts/{id}Satu kontak.
GET/historyLog panggilan, yang terbaru di atas. Menerima ?limit=, ?missed=true, dan ?declined=true.
GET/callsPanggilan yang sedang berlangsung.
POST/callsMelakukan panggilan: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerMenjawab panggilan.
POST/calls/{id}/hangupMenutup panggilan.
POST/calls/{id}/holdMenahan panggilan.
POST/calls/{id}/resumeMelanjutkan panggilan yang ditahan.
POST/calls/{id}/dtmfMengirim nada: {"digits": "..."}.
POST/calls/{id}/transferMengalihkan panggilan: {"target": "..."}.
GET/accountsAkun SIP dan status registrasinya. Tidak pernah berisi kata sandi.
GET/settingsSeluruh konfigurasi, tanpa rahasia.
GET/taxonomyKategori, label, dan tanda peringatan, beserta kodenya.

Endpoint yang memerlukan token​

Endpoint ini mengubah apa yang tersimpan, jadi setiap permintaan harus membawa token di tajuk Authorization. Halaman API sendiri hanya menampilkannya kepada permintaan yang membawanya.

MetodeJalurFungsi
POST/contactsMenambahkan kontak: {"name": "...", "number": "...", "account_id": "..."}; account_id opsional.
PUT/contacts/{id}Mengganti kontak.
DELETE/contacts/{id}Menghapus kontak.
DELETE/history/{id}Melupakan satu panggilan dari log panggilan.
DELETE/historyMelupakan seluruh log panggilan. Tidak bisa dibatalkan.
PUT/accounts/{id}Mengganti pengaturan sebuah akun. Kata sandi tidak termasuk.
PUT/settingsMengganti pengaturan.

Setiap pengenal adalah UUID yang dikeluarkan oleh telepon: id panggilan berasal dari /calls atau dari jawaban atas POST /calls, id akun dari /accounts.

Nama kolom ditulis dalam snake_case dan akhirannya menunjukkan jenisnya: _id adalah rujukan ke UUID, _ts adalah saat dalam milidetik Unix (UTC), _s adalah durasi dalam detik. Hal yang sama berlaku untuk webhook; hanya /settings yang mempertahankan nama-namanya sendiri. Di REST API nilai-nilai ini berupa angka JSON, dan saat yang tidak diketahui bernilai null.

Contoh: melakukan panggilan​

POST /calls melakukan panggilan keluar. Isinya JSON dengan number yang akan diputar dan, secara opsional, account_id akun yang digunakan untuk menelepon:

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

Jawabannya adalah pengenal panggilan baru:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number wajib diisi. Tanpanya, jawabannya 400 {"error":"a call needs a number"} dan tidak ada yang diputar.
  • Nomor dilengkapi pada akun yang dipilih dengan cara yang sama seperti papan panggil melengkapinya: 1020 dikirim sebagai sip:1020@pbx.example.com. POST /calls/{id}/transfer melengkapi target-nya dengan cara yang sama; target yang sudah memiliki skema atau @ dikirim apa adanya.
  • account_id bersifat opsional; ambil dari GET /accounts. Tanpanya, panggilan keluar melalui akun yang dipilih di jendela utama.
  • Gunakan id di /calls/{id}/…: hangup, hold, resume, dtmf, dan transfer. Webhook dari panggilan ini membawa id yang sama.

Dari halaman web: klik untuk menelepon​

Halaman yang memanggil 127.0.0.1 menjangkau komputer tempat peramban berjalan — komputer yang sama tempat telepon berjalan — sehingga tombol klik-untuk-menelepon di CRM tidak memerlukan server sendiri:

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

Isi jawaban​

Panggilan yang sedang berlangsung: GET /calls​

Setiap panggilan memiliki id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts, dan callstate_ts.

  • state adalah dialing, ringing-out, ringing-in, active, hold (ditahan oleh telepon ini), onhold (ditahan oleh pihak lain), conference, atau ended. Bila lebih dari satu berlaku, conference mengalahkan hold, dan hold mengalahkan onhold.
  • muted menyatakan apakah mikrofon dibisukan dalam panggilan; membisukan tidak mengubah state.
  • seance_id adalah percakapan: panggilan yang terhubung oleh pengalihan, konsultasi, atau konferensi berbagi nilai ini.
  • event_ts adalah saat jawaban dibuat. Bandingkan dengan callstate_ts untuk melihat berapa lama panggilan berada dalam statusnya, tanpa bergantung pada jam Anda sendiri.

Akun: GET /accounts​

Setiap akun memiliki id (yang di tempat lain disebut account_id), pengaturannya — transport (udp, tcp, atau tls), port, registrar, outbound_proxy, expiry_s, dan lainnya — apakah akun itu enabled, dan state-nya di PBX: registered selama saluran aktif. Kata sandi tidak pernah disertakan.

Riwayat panggilan: GET /history​

Yang terbaru di atas, 100 entri kecuali ?limit= menyatakan lain. ?missed=true hanya mengembalikan panggilan tak terjawab, ?declined=true hanya panggilan yang ditolak oleh telepon ini.

KolomArti
idPengenal entri riwayat itu sendiri. Ini bukan id panggilan dari /calls dan webhook; seance_id menghubungkan keduanya.
outcomeKlasifikasi utama: answered, missed, declined, atau failed.
answeredtrue atau false.
duration_s0 untuk panggilan yang tidak pernah tersambung.
number, uriPihak lain, sebagai nomor dan sebagai alamat SIP.
nameDari Kontak jika nomornya dikenal, jika tidak kosong. Cocokkan berdasarkan number, bukan kolom ini.
dialedAngka yang diputar, untuk panggilan keluar; kosong untuk panggilan masuk.
account, account_idSaluran yang digunakan panggilan.
reasonBagaimana panggilan berakhir: local-hangup, remote-hangup, cancelled…
answered_byno jika seseorang menjawabnya; selain itu, apa yang menjawab panggilan.

Kontak: GET /contacts​

Setiap kontak memiliki id, name, number, dan saluran tempatnya berada, account_id dan account; account yang kosong berarti kontak tidak terikat pada saluran.

Rekaman​

Rekaman dan transkrip tidak diberikan sebagai JSON. API menyajikannya sebagai halaman HTML, /ui dan /ui/recordings/{id}: tautkan halaman-halaman ini dari CRM Anda alih-alih memindahkan audio ke sana kemari. Tautan terbuka di komputer yang menyimpan rekaman, dan audionya tidak pernah meninggalkan komputer itu.

Taksonomi dan pengaturan​

Setiap entri /taxonomy memiliki code yang tetap, title dan description dalam bahasa antarmuka, kind (category, tag, atau red_flag) dan, untuk tanda peringatan, severity. Cocokkan berdasarkan code, jangan pernah berdasarkan title: judul datang dalam bahasa yang diatur pada telepon. Entri dengan retired: true dipertahankan agar panggilan lama tetap dapat dirujuk; entri itu tidak lagi diberikan pada panggilan baru. Muat taksonomi sekali saat mulai untuk memetakan kata-kata telepon ke kolom Anda sendiri.

/settings mengembalikan konfigurasi kecuali rahasia: perangkat audio dan volume, prioritas codec, tampilan dan bahasa, awalan, tombol pintas, tingkat diagnostik, dan status kedua integrasi — berguna bagi alat dukungan yang harus memeriksa komputer kerja tanpa berbagi layar. api.disabled mencantumkan kelompok akses yang mati dan webhooks.silenced peristiwa yang mati; daftar kosong berarti semuanya menyala. Konfigurasi ini tidak pernah memuat kata sandi SIP, token API, atau nilai tajuk webhook.

Kesalahan​

Setiap kesalahan berupa JSON dengan satu kunci error, ditujukan untuk manusia, bukan untuk diurai.

StatusIsiArti
404{"error":"no such endpoint"}Jalurnya tidak ada, atau kelompok aksesnya mati; keduanya sengaja memberikan jawaban yang sama.
405{"error":"that endpoint does not take this method"}Jalurnya ada, tetapi tidak menerima metode ini: misalnya POST /settings alih-alih PUT.
401{"error":"writing needs a token, and none is configured"}Endpoint yang mengubah apa yang tersimpan, pada telepon yang kolom Token-nya kosong. Isi kolom itu di Kendali lokal.
401{"error":"this endpoint needs the authorization token"}Endpoint yang mengubah apa yang tersimpan, tanpa token yang benar.
404{"error":"no contact with that id"}Jalurnya benar, pengenalnya tidak.
400{"error":"no call with that id"}Panggilan telah berakhir, atau tidak pernah ada.
400{"error":"a call needs a number"}POST /calls tanpa nomor. Tidak ada yang diputar.
400{"error":"no digits to send"}POST /calls/{id}/dtmf tanpa angka.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer tanpa target.
400{"error":"the account this call is on is no longer set up"}Akun panggilan dihapus selama panggilan, sehingga target tidak dapat dilengkapi. Tidak ada yang dikirim ke PBX.

Permintaan yang ditolak dihitung di api_requests_refused_total, sehingga integrasi yang gagal diam-diam terlihat di metrik, tidak hanya di log Anda sendiri.

Metrik​

GET /metrics mengembalikan setiap pencacah telepon, masing-masing dengan teks bantuan. Ambil dengan Prometheus atau baca secara manual.

PencacahYang dihitung
calls_incoming_totalPanggilan masuk yang diterima.
calls_outgoing_totalPanggilan keluar yang dilakukan.
calls_answered_totalPanggilan yang dijawab.
calls_missed_totalPanggilan masuk yang tidak dijawab.
calls_declined_totalPanggilan yang ditolak di sini atau oleh pihak lain.
calls_failed_totalPanggilan yang tidak dapat dibangun.
registrations_succeeded_totalRegistrasi SIP yang berhasil.
registrations_failed_totalRegistrasi SIP yang ditolak atau habis waktu.
webhooks_delivered_totalWebhook yang diterima oleh penerima.
webhooks_failed_totalWebhook yang ditolak atau tidak terkirim.
webhooks_dropped_totalWebhook yang dibuang karena antrean penuh.
api_requests_totalPermintaan yang ditangani oleh API.
api_requests_refused_totalPermintaan yang ditolak: token salah, kelompok mati, atau jalur tidak dikenal.

Memperbarui integrasi lama​

Versi sebelumnya menggunakan nama camelCase dan pengenal pendek. accountId kini account_id, startedAt menjadi callstart_ts, durationSeconds menjadi duration_s, answeredBy menjadi answered_by, dan kolom webhook at menjadi event_ts. Panggilan dan akun hanya diidentifikasi dengan UUID: runtimeId dan pengenal seperti call-3 atau account-2 tidak lagi dikembalikan maupun diterima.

Ketika tidak berfungsi​

GejalaYang perlu diperiksa
Koneksi ditolak di 127.0.0.1:8377Kendali lokal mati, telepon tidak berjalan, atau porta telah diubah.
404 {"error":"no such endpoint"} untuk jalur di halaman iniKelompok aksesnya mati.
Membaca berhasil, menulis ditolak dengan 401Endpoint yang mengubah data tersimpan memerlukan token di tajuk Authorization, dan kolom Token di telepon harus diisi lebih dulu.
Judul kategori tidak dalam bahasa InggrisJudul mengikuti bahasa antarmuka. Cocokkan berdasarkan code dari /taxonomy.
accountId, startedAt, atau at tidak adaIntegrasi ditulis untuk nama-nama lama; lihat di atas.

Untuk masalah registrasi atau panggilan itu sendiri, buka Diagnostik.