Skip to main content
Widget web memberi pengunjung situs Anda percakapan klik-untuk-berbicara dengan agen AI, menggunakan mikrofon browser. Ini adalah SDK JavaScript / React terpisah dengan referensi SDK sendiri — panduan ini berfokus pada penyiapan sisi ThunderPhone yang dibutuhkan widget.
Anda dapat melakukan semuanya tanpa cURL: halaman dasbor Widget Web (/dashboard/web-widgets) membuat widget, menetapkan mode dan agennya, mengelola domain yang diizinkan, dan memberikan snippet sematan.

​
Prasyarat

1

Buat agen

Agen yang Prompt dan suaranya akan menjalankan sesi widget. Tetapkan widget_enabled: true (default).
2

Tentukan mode perutean

  • mode="agent" — satu agen statis per kunci. Paling sederhana.
  • mode="webhook" — server Anda memilih agen per pengunjung melalui webhook web.incoming. Gunakan ini untuk pengguna yang masuk, pengujian A/B, atau perutean per halaman.
3

Daftarkan domain yang diizinkan

Kunci yang dapat dipublikasikan terkunci ke origin. Anda harus mencantumkan setiap hostname yang akan menyematkan widget. localhost / 127.0.0.1 selalu diizinkan selama pengembangan lokal.

​
Buat kunci yang dapat dipublikasikan

Respons mencakup key yang diawali dengan pk_live_.... Kunci yang dapat dipublikasikan bersifat publik secara desain — aman untuk disertakan dalam bundle front-end Anda. Lihat referensi kunci yang dapat dipublikasikan untuk semua field.
allowed_domains harus berisi setidaknya satu entri. *.example.com cocok dengan subdomain (misalnya, api.example.com) tetapi tidak dengan domain utama. Wildcard utama seperti * atau *.* ditolak.

​
Tambahkan widget ke situs Anda

Tiga opsi integrasi dibahas dalam dokumentasi SDK widget:

Komponen React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Hook headless

useThunderPhone() untuk UI kustom.

Tag skrip CDN

ThunderPhone.mount({...}) untuk situs tanpa bundler.
Ketiganya menerima publishableKey yang sama dan merender tombol mikrofon beserta elemen audio saat panggilan. context widget dipotong hingga 12.000 karakter (sekitar 3.400 token teks bahasa Inggris biasa) dan diperhitungkan dalam biaya tambahan ukuran Prompt.

​
Webhook mode widget

Saat mode="webhook", ThunderPhone memanggil webhook_url Anda pada setiap awal sesi dengan payload web.incoming. Kembalikan konfigurasi agen yang ingin Anda jalankan untuk pengunjung tersebut — konfigurasi ini mengikuti skema respons yang sama seperti panggilan telepon:
Anda dapat mencampurkan konteks dari sesi Anda sendiri (pelanggan mana yang sedang menjelajah, halaman mana yang mereka buka) ke dalam Prompt, dan mengganti agen untuk setiap peluncuran.

​
Pantau sesi

Sesi widget muncul di GET /v1/calls dengan direction="widget" — dengan transkrip, rekaman, penilaian, dan penagihan yang sama seperti panggilan telepon. Filter berdasarkan direction untuk membuat dasbor khusus widget.

​
Langkah berikutnya

Referensi SDK widget

Detail integrasi React / hook / CDN.

Konfigurasi dinamis per panggilan

Terapkan alur mode="webhook" secara menyeluruh.

Referensi kunci yang dapat dipublikasikan

Setiap field pada resource kunci.

API sesi mikrofon

Lewati widget; gunakan LiveKit secara langsung untuk UI kustom.