Developer cookbook

Vložení webového widgetu

Přidejte na svůj marketingový nebo podpůrný web hlasového agenta pomocí jediného tagu skriptu — návštěvníci s ním mohou mluvit přímo z prohlížeče, bez nutnosti telefonního čísla.

Webový widget umožňuje návštěvníkům vašeho webu konverzaci po kliknutí pro zahájení hovoru s hlasovým agentem s AI pomocí mikrofonu v prohlížeči. Jde o samostatné JavaScriptové / React SDK s vlastní referencí SDK — tato příručka se zaměřuje na nastavení na straně ThunderPhone, které widget potřebuje.

Předpoklady#

1. Vytvořte agenta

   Agent, jehož prompt a hlas budou používat relaci widgetu. Nastavte widget_enabled: true (výchozí hodnota).

2. Rozhodněte o režimu směrování
   • mode="agent" — jeden statický agent pro každý klíč. Nejjednodušší možnost.
   • mode="webhook" — váš server vybere agenta pro každého návštěvníka prostřednictvím webhooku web.incoming. Použijte jej pro přihlášené uživatele, A/B testy nebo směrování podle stránky.
3. Uveďte povolené domény

   Veřejné klíče jsou vázané na zdroj. Musíte uvést každý název hostitele, který bude widget vkládat. localhost / 127.0.0.1 jsou při lokálním vývoji vždy povoleny.

Vytvořte veřejný klíč#

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

Odpověď obsahuje key začínající na pk_live_.... Veřejné klíče jsou záměrně veřejné — můžete je bezpečně zahrnout do front-endového balíčku. Všechna pole najdete v referenci veřejných klíčů.

Vložte widget na svůj web#

Tři možnosti integrace jsou popsány v dokumentaci SDK widgetu:

Všechny tři přijímají stejný publishableKey a vykreslují tlačítko mikrofonu spolu s prvkem zvuku během hovoru.

context widgetu je zkrácen na 12 000 znaků (přibližně 3 400 tokenů typického anglického textu) a započítává se do příplatku za velikost promptu.

Webhooky v režimu widgetu#

Když je nastaveno mode="webhook", ThunderPhone volá vaše webhook_url při každém zahájení relace s daty web.incoming. Vraťte konfiguraci agenta, kterou chcete pro daného návštěvníka spustit — používá stejné schéma odpovědi jako telefonní hovory:

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

Do promptu můžete přidat kontext z vlastní relace (který zákazník prochází web, na které stránce se nachází) a během nasazení měnit agenty.

Sledování relací#

Relace widgetu se zobrazují v GET /v1/calls s direction="widget" — mají stejný přepis, nahrávku, hodnocení a účtování jako telefonní hovory. Filtrujte podle direction a vytvořte si řídicí panel pouze pro widget.

Další kroky#