Developer cookbook

Web widget

Tek bir script etiketiyle pazarlama veya destek sitenize bir sesli AI ajanı ekleyin — ziyaretçiler telefon numarasına gerek olmadan doğrudan tarayıcıdan konuşabilir.

Web widget'ı, site ziyaretçilerinize tarayıcının mikrofonunu kullanarak bir yapay zeka ajanıyla tıklayıp konuşabilecekleri bir görüşme sunar. Bu, kendi SDK referansına sahip ayrı bir JavaScript / React SDK'sıdır — bu kılavuz, widget'ın ihtiyaç duyduğu ThunderPhone tarafındaki kuruluma odaklanır.

Ön koşullar#

1. Bir ajan oluşturun

   İstemi ve sesi widget oturumunu çalıştıracak olan ajan. Varsayılan değer olan widget_enabled: true ayarını kullanın.

2. Yönlendirme modunu belirleyin
   • mode="agent" — anahtar başına tek bir sabit ajan. En basit seçenek.
   • mode="webhook" — sunucunuz, her ziyaretçi için ajanı bir web.incoming webhook'u aracılığıyla seçer. Bunu oturum açmış kullanıcılar, A/B testleri veya sayfa başına yönlendirme için kullanın.
3. İzin verilen alan adlarını listeleyin

   Yayınlanabilir anahtarlar kaynak kökene kilitlidir. Widget'ı gömecek her ana makine adını belirtmeniz gerekir. Yerel geliştirme sırasında localhost / 127.0.0.1 her zaman izinlidir.

Yayınlanabilir anahtar oluşturun#

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

Yanıt, pk_live_... ile başlayan bir key içerir. Yayınlanabilir anahtarlar tasarım gereği herkese açıktır — ön uç paketinizle birlikte güvenle yayınlayabilirsiniz. Tüm alanlar için Yayınlanabilir anahtarlar referansına bakın.

Widget'ı sitenize ekleyin#

Üç entegrasyon seçeneği widget SDK belgelerinde açıklanmıştır:

Üçü de aynı publishableKey değerini kabul eder ve mikrofon düğmesini ile arama sırasındaki ses öğesini oluşturur.

Widget context değeri 12.000 karakterde kesilir (tipik İngilizce metnin yaklaşık 3.400 token'ı) ve istem boyutu ek ücretine dahil edilir.

Widget modu webhook'ları#

mode="webhook" olduğunda ThunderPhone, her oturum başlangıcında web.incoming yüküyle webhook_url adresinizi çağırır. Bu ziyaretçi için çalıştırmak istediğiniz yapay zeka ajanı yapılandırmasını döndürün — telefon aramalarıyla aynı yanıt şemasını izler:

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

Kendi oturumunuzdaki bağlamı (hangi müşterinin göz attığını, hangi sayfada olduklarını) isteme ekleyebilir ve her yayına alma süreci için ajanları değiştirebilirsiniz.

Oturumları izleyin#

Widget oturumları, GET /v1/calls içinde direction="widget" ile görünür — telefon çağrılarıyla aynı transkript, kayıt, değerlendirme ve faturalandırma uygulanır. Yalnızca widget'a özel bir pano oluşturmak için direction ile filtreleyin.

Sonraki adımlar#