Developer cookbook

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. Ügynök létrehozása

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

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

   A publikálható kulcsok originhez kötöttek. Meg kell adnia minden olyan gazdagépnevet, amely beágyazza a widgetet. A localhost / 127.0.0.1 helyi fejlesztés során mindig engedélyezett.

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

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.

A widget context értéke 12 000 karakternél csonkolódik (körülbelül 3 400 tokennyi átlagos angol szöveg), és beleszámít a promptméret-felárba.

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#