Developer cookbook

Osadź widżet internetowy

Dodaj agenta głosowego do swojej witryny marketingowej lub wsparcia za pomocą jednego tagu skryptu — odwiedzający rozmawiają z nim bezpośrednio w przeglądarce, bez potrzeby podawania numeru telefonu.

Widżet internetowy zapewnia odwiedzającym Twoją witrynę rozmowę typu kliknij, aby porozmawiać z agentem AI, przy użyciu mikrofonu przeglądarki. To osobny zestaw SDK JavaScript / React z własnym opisem SDK — ten przewodnik koncentruje się na konfiguracji po stronie ThunderPhone, której potrzebuje widżet.

Wymagania wstępne#

1. Utwórz agenta AI

   Agent AI, którego prompt i głos będą używane podczas sesji widżetu. Ustaw widget_enabled: true (wartość domyślna).

2. Wybierz tryb routingu
   • mode="agent" — jeden statyczny agent AI na klucz. Najprostsza opcja.
   • mode="webhook" — Twój serwer wybiera agenta AI dla każdego odwiedzającego za pomocą webhooka web.incoming. Użyj tego dla zalogowanych użytkowników, testów A/B lub routingu zależnego od strony.
3. Wskaż dozwolone domeny

   Klucze publikowalne są ograniczone do źródeł. Musisz wskazać każdą nazwę hosta, która będzie osadzać widżet. localhost / 127.0.0.1 są zawsze dozwolone podczas lokalnego programowania.

Utwórz klucz publikowalny#

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

Odpowiedź zawiera key zaczynający się od pk_live_.... Klucze publikowalne są z założenia publiczne — można je bezpiecznie umieścić w pakiecie front-endu. Wszystkie pola znajdziesz w opisie kluczy publikowalnych.

Umieść widżet na swojej stronie#

Trzy opcje integracji opisano w dokumentacji SDK widżetu:

Wszystkie trzy akceptują ten sam publishableKey i renderują przycisk mikrofonu oraz element audio podczas rozmowy.

context widżetu jest obcinany do 12 000 znaków (około 3400 tokenów typowego angielskiego tekstu) i wlicza się do dopłaty za rozmiar promptu.

Webhooki w trybie widżetu#

Gdy mode="webhook", ThunderPhone wywołuje Twój webhook_url przy każdym rozpoczęciu sesji z ładunkiem web.incoming. Zwróć konfigurację agenta AI, którą chcesz uruchomić dla tego odwiedzającego — korzysta ona z tego samego schematu odpowiedzi co połączenia telefoniczne:

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

Możesz łączyć w prompcie kontekst z własnej sesji (który klient przegląda stronę, na której stronie się znajduje) oraz zmieniać agentów AI dla poszczególnych wdrożeń.

Monitoruj sesje#

Sesje widżetu pojawiają się w GET /v1/calls z direction="widget" — mają ten sam transkrypt, nagranie, ocenę i rozliczenia co połączenia telefoniczne. Filtruj według direction, aby utworzyć panel wyłącznie dla widżetu.

Kolejne kroki#