Sematkan widget web

Tambahkan agen suara ke situs pemasaran atau dukungan Anda dengan satu tag skrip — pengunjung dapat berbicara langsung dengannya dari browser, tanpa memerlukan nomor telepon.

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 di sisi ThunderPhone yang diperlukan widget.

Prasyarat#

1. Buat agen

   Agen yang Prompt dan suaranya akan menjalankan sesi widget. Atur 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 sudah masuk, pengujian A/B, atau perutean per halaman.
3. Cantumkan domain yang diizinkan

   Cantumkan setiap nama host yang akan menyematkan widget. Browser mengirim origin halaman dengan setiap permintaan sesi, sehingga daftar ini mencegah kunci Anda berfungsi ketika seseorang menyalinnya ke situs lain. Ini bukan autentikasi: skrip di luar browser dapat mengirim header Origin apa pun. localhost tidak diizinkan secara otomatis di produksi; untuk menguji secara lokal terhadap API produksi, tambahkan localhost ke dalam daftar.

4. Pilih override browser

   Tentukan pengaturan sesi yang dapat dikirim oleh halaman Anda. Kunci baru tidak menerima override; lihat Override browser.

Buat kunci yang dapat dipublikasikan#

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

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.

Tambahkan widget ke situs Anda#

Tiga opsi integrasi dibahas dalam dokumentasi SDK widget:

Ketiganya menerima publishableKey yang sama dan merender tombol mikrofon beserta elemen audio saat panggilan berlangsung.

Override browser#

Widget dapat mengirim empat pengaturan per sesi dari halaman:

Kunci publishable Anda bersifat publik, sehingga siapa pun yang memilikinya dapat mengirimkan pengaturan ini, termasuk dari skrip yang memalsukan domain Anda. Karena itu, masing-masing dinonaktifkan hingga Anda mengizinkannya pada kunci: centang di bawah Override browser saat Anda membuat atau mengedit widget di dashboard, atau tetapkan allowed_overrides melalui API kunci publishable. Izinkan hanya yang benar-benar dikirim oleh halaman Anda.

Permintaan sesi yang membawa pengaturan yang tidak diizinkan oleh kunci akan gagal dengan 400 dan menyebutkan pengaturan tersebut:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

Pemeriksaan ini berlaku di kedua mode. Dalam mode webhook, pengaturan yang diizinkan juga diteruskan ke webhook web.incoming Anda (context diterima sebagai website_context). Kunci yang dibuat sebelum pengaturan ini tersedia mengizinkan keempatnya, sehingga penyematan yang ada tetap berfungsi; nonaktifkan yang tidak Anda gunakan.

context widget dipotong hingga 12.000 karakter (sekitar 3.400 token teks bahasa Inggris umum) dan diperhitungkan dalam biaya tambahan ukuran Prompt. Agen diinstruksikan untuk memperlakukannya sebagai konten halaman, bukan sebagai instruksi.

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:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

Anda dapat mencampurkan konteks dari sesi Anda sendiri (pelanggan mana yang sedang menjelajah, halaman mana yang mereka buka) ke dalam prompt, serta mengganti agen pada setiap peluncuran.

Pantau sesi#

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

Langkah berikutnya#