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 pomocí webhooku web.incoming. Použijte pro přihlášené uživatele, A/B testy nebo směrování podle stránky.
3. Uveďte povolené domény

   Uveďte každý název hostitele, který bude widget vkládat. Prohlížeče odesílají původ stránky s každým požadavkem na relaci, takže seznam zabrání tomu, aby váš klíč fungoval, když jej někdo zkopíruje na jiný web. Nejde o ověřování: skript mimo prohlížeč může odeslat libovolnou hlavičku Origin. localhost není v produkci automaticky povolen; chcete-li testovat lokálně proti produkčnímu API, přidejte localhost do seznamu.

4. Zvolte přepsání nastavení prohlížečem

   Rozhodněte, která nastavení relace může vaše stránka odesílat. Nové klíče nepřijímají žádná; viz Přepsání nastavení prohlížečem.

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

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.

Přepsání z prohlížeče#

Widget může ze stránky odesílat čtyři nastavení pro jednotlivé relace:

Váš publikovatelný klíč je veřejný, takže kdokoli, kdo jej má, může tato nastavení odeslat, včetně skriptu, který se vydává za vaši doménu. Každé z nich je proto vypnuté, dokud je u klíče nepovolíte: zaškrtněte je v části Přepsání v prohlížeči, když widget vytváříte nebo upravujete v dashboardu, nebo nastavte allowed_overrides prostřednictvím API publikovatelných klíčů. Povolte pouze to, co vaše stránka skutečně odesílá.

Požadavek na relaci, který obsahuje nastavení, jež klíč nepovoluje, selže s 400 a uvede jeho název:

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

Kontrola se uplatňuje v obou režimech. V režimu webhooku se povolené nastavení také předá vašemu webhooku web.incoming (context dorazí jako website_context). Klíče vytvořené před zavedením tohoto nastavení povolují všechna čtyři, takže stávající vložení nadále fungují; vypněte to, co nepoužíváte.

Hodnota context widgetu je zkrácena na 12 000 znaků (přibližně 3 400 tokenů běžného anglického textu) a započítává se do příplatku za velikost promptu. Agent dostane pokyn, aby ji považoval za obsah stránky, nikoli za instrukce.

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#