Developer cookbook

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. 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 sudah Masuk, pengujian A/B, atau perutean per halaman.
3. Daftarkan domain yang diizinkan

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

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"]
  }'

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.

context widget dipotong hingga 12.000 karakter (sekitar 3.400 token teks bahasa Inggris umum) 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:

{
  "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#