Upota verkkowidget

Lisää puheagentti markkinointi- tai tukisivustollesi yhdellä skriptitunnisteella — kävijät voivat puhua sille suoraan selaimesta ilman puhelinnumeroa.

Verkkowidget antaa sivustosi kävijöille selaimen mikrofonia hyödyntävän klikkaa ja puhu -keskustelun tekoälyagentin kanssa. Se on erillinen JavaScript- / React-SDK omalla SDK-viitteellään — tässä oppaassa keskitytään widgetin tarvitsemaan ThunderPhone-puolen määritykseen.

Vaatimukset#

1. Luo agentti

   Agentti, jonka kehote ja ääni ohjaavat widget-istuntoa. Aseta widget_enabled: true (oletusarvo).

2. Valitse reititystila
   • mode="agent" — yksi staattinen agentti avainta kohden. Yksinkertaisin vaihtoehto.
   • mode="webhook" — palvelimesi valitsee agentin kävijäkohtaisesti web.incoming-webhookin kautta. Käytä tätä kirjautuneille käyttäjille, A/B-testeihin tai sivukohtaiseen reititykseen.
3. Luettele sallitut verkkotunnukset

   Määritä jokainen isäntänimi, johon widget upotetaan. Selaimet lähettävät sivun alkuperän jokaisen istuntopyynnön mukana, joten luettelo estää avaimesi toimimisen, jos joku kopioi sen toiselle sivustolle. Tämä ei ole todennus: selaimen ulkopuolinen komentosarja voi lähettää minkä tahansa Origin- otsakkeen. localhost ei ole automaattisesti sallittu tuotannossa; jos haluat testata paikallisesti tuotanto-APIa vasten, lisää localhost luetteloon.

4. Valitse selaimen ohitukset

   Päätä, mitkä istuntoasetukset sivusi voi lähettää. Uudet avaimet eivät hyväksy mitään; katso Selaimen ohitukset.

Luo julkaistava avain#

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

Vastaus sisältää pk_live_...-alkuisen key-avaimen. Julkaistavat avaimet ovat julkisia tarkoituksella — ne voi sisällyttää turvallisesti käyttöliittymäpakettiisi. Katso kaikki kentät julkaistavien avainten viitteestä.

Lisää widget sivustollesi#

Kolme integraatiovaihtoehtoa käsitellään widgetin SDK-dokumentaatiossa:

Kaikki kolme hyväksyvät saman publishableKey-arvon ja renderöivät mikrofonipainikkeen sekä puhelun aikaisen äänielementin.

Selaimen ohitukset#

Widget voi lähettää sivulta neljä istuntokohtaista asetusta:

Julkaistava avaimesi on julkinen, joten kuka tahansa, jolla se on, voi lähettää nämä asetukset, myös skriptistä, joka teeskentelee verkkotunnustasi. Kukin asetus on siksi pois käytöstä, kunnes sallit sen avaimessa: valitse se kohdassa Selaimen ohitukset, kun luot tai muokkaat widgetiä hallintapaneelissa, tai määritä allowed_overrides Julkaistavien avainten API:n kautta. Salli vain se, mitä sivusi todella lähettää.

Istuntopyyntö, joka sisältää asetuksen, jota avain ei salli, epäonnistuu virheellä 400 ja nimeää asetuksen:

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

Tarkistus koskee molempia tiloja. Webhook-tilassa sallittu asetus välitetään myös web.incoming-webhookiisi (context saapuu nimellä website_context). Ennen tämän asetuksen käyttöönottoa luodut avaimet sallivat kaikki neljä asetusta, joten olemassa olevat upotukset toimivat edelleen; poista käytöstä ne, joita et käytä.

Widgetin context katkaistaan 12 000 merkkiin (noin 3 400 tokenia tyypillistä englanninkielistä tekstiä), ja se lasketaan mukaan kehotteen koon lisämaksuun. Agenttia ohjeistetaan käsittelemään sitä sivun sisältönä, ei ohjeina.

Widget-tilan webhookit#

Kun mode="webhook", ThunderPhone kutsuu webhook_url-osoitettasi jokaisen istunnon alkaessa web.incoming-payloadilla. Palauta agentin määritys, jonka haluat suorittaa kyseiselle kävijälle — se noudattaa samaa vastausskeemaa kuin puhelut:

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

Voit yhdistää omaa istuntoasi koskevan kontekstin (mitä asiakasta selataan, millä sivulla hän on) kehotteeseen ja vaihtaa agentteja käyttöönoton mukaan.

Tarkastele sessioita#

Widget-sessiot näkyvät GET /v1/calls-päätepisteessä, kun direction="widget" — niillä on sama transkriptio, tallenne, arviointi ja laskutus kuin puheluilla. Suodata direction-kentän mukaan luodaksesi vain widgeteille tarkoitetun hallintapaneelin.

Seuraavat vaiheet#