Webes widget beágyazása

Egyetlen scriptcímkével helyezzen el hangalapú AI-ügynököt marketing- vagy támogatási webhelyén — a látogatók közvetlenül a böngészőből beszélhetnek vele, telefonszám nélkül.

A webes widget lehetővé teszi, hogy a webhely látogatói a böngésző mikrofonját használva, kattintással indítsanak beszélgetést egy AI-ügynökkel. Ez egy különálló JavaScript / React SDK saját SDK-referenciával — ez az útmutató a widgethez szükséges ThunderPhone-oldali beállításokra összpontosít.

Előfeltételek#

1. AI-ügynök létrehozása

   Az az AI-ügynök, amelynek promptja és hangja futtatja a widgetmunkamenetet. Állítsa be a widget_enabled: true értéket (ez az alapértelmezett).

2. Az útválasztási mód kiválasztása
   • mode="agent" — kulcsonként egy statikus AI-ügynök. A legegyszerűbb.
   • mode="webhook" — a szervere látogatónként választja ki az AI-ügynököt egy web.incoming webhook segítségével. Használja ezt bejelentkezett felhasználókhoz, A/B-tesztekhez vagy oldalankénti útválasztáshoz.
3. Az engedélyezett domainek felsorolása

   Adjon meg minden gazdagépnevet, amely beágyazza a widgetet. A böngészők minden munkamenet-kéréssel elküldik az oldal eredetét, így a lista megakadályozza, hogy a kulcsa működjön, ha valaki átmásolja egy másik webhelyre. Ez nem hitelesítés: a böngészőn kívüli szkript bármilyen Origin fejlécet küldhet. A localhost éles környezetben nem engedélyezett automatikusan; ha helyileg szeretne tesztelni az éles API-val, adja hozzá a localhost értéket a listához.

4. A böngészőbeli felülbírálások kiválasztása

   Döntse el, mely munkamenet-beállításokat küldheti az oldala. Az új kulcsok egyiket sem engedélyezik; lásd: Böngészőbeli felülbírálások.

Publikálható kulcs létrehozása#

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

A válasz egy pk_live_... kezdetű key értéket tartalmaz. A publikálható kulcsok kialakításukból adódóan nyilvánosak — biztonságosan elhelyezhetők a front-end csomagban. Az összes mezőért lásd a Publikálható kulcsok referenciáját.

Helyezze el a widgetet a webhelyén#

Három integrációs lehetőséget ismertet a widget SDK dokumentációja:

Mindhárom ugyanazt a publishableKey értéket fogadja el, és megjeleníti a mikrofon gombját, valamint a hívás közbeni hangelemet.

Böngészőbeli felülbírálások#

A widget munkamenetenként négy beállítást küldhet az oldalról:

A publikálható kulcsa nyilvános, ezért bárki, aki rendelkezik vele, elküldheti ezeket a beállításokat, akár az Ön domainjét meghamisító szkriptből is. Ezért mindegyik alapértelmezés szerint ki van kapcsolva, amíg nem engedélyezi az adott kulcsnál: a vezérlőpulton a widget létrehozásakor vagy szerkesztésekor jelölje be a Böngészőfelülbírálások alatt, vagy állítsa be az allowed_overrides értékét a Publikálható kulcsok API segítségével. Csak azt engedélyezze, amit az oldala ténylegesen elküld.

Ha egy munkamenet-kérés olyan beállítást tartalmaz, amelyet a kulcs nem engedélyez, a kérés 400 hibával meghiúsul, és megnevezi azt:

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

Az ellenőrzés mindkét módban érvényes. Webhook módban az engedélyezett beállítás a web.incoming webhookhoz is továbbításra kerül (context értéke website_context néven érkezik). A beállítás bevezetése előtt létrehozott kulcsok mind a négyet engedélyezik, így a meglévő beágyazások továbbra is működnek; kapcsolja ki azt, amit nem használ.

A widget context értéke 12 000 karakterre csonkolódik (ez nagyjából 3 400 tokennyi tipikus angol szöveg), és beleszámít a promptméret-felárba. Az ügynök azt az utasítást kapja, hogy oldaltartalomként, ne utasításként kezelje.

Widget módú webhookok#

mode="webhook" esetén a ThunderPhone minden munkamenet indításakor meghívja az Ön webhook_url címét egy web.incoming adattartalommal. Adja vissza az adott látogatóhoz futtatni kívánt ügynökkonfigurációt — ez ugyanazt a válaszsémát követi, mint a telefonhívások:

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

A saját munkamenetéből származó kontextust (melyik ügyfél böngészik, melyik oldalon van) beillesztheti a promptba, és bevezetésenként cserélheti az ügynököket.

Munkamenetek megfigyelése#

A widgetmunkamenetek a GET /v1/calls végpontban jelennek meg direction="widget" értékkel — ugyanazzal az átirattal, felvétellel, értékeléssel és számlázással, mint a telefonhívások esetében. Szűrjön a direction alapján, hogy csak widgetes irányítópultot hozzon létre.

Következő lépések#