Уградите веб виџет

Додајте гласовног агента на свој маркетиншки сајт или сајт за подршку помоћу једне ознаке скрипте — посетиоци разговарају с њим директно из прегледача, без потребе за бројем телефона.

Веб-виџет посетиоцима Вашег сајта пружа разговор на клик са AI гласовним агентом, користећи микрофон прегледача. То је засебан JavaScript / React SDK са сопственом SDK референцом — овај водич се фокусира на подешавање на страни ThunderPhone које је виџету потребно.

Предуслови#

1. Направите агента

   Агент чији ће упит и глас покретати сесију виџета. Подесите widget_enabled: true (подразумевано).

2. Одлучите о режиму рутирања
   • mode="agent" — један статички агент по кључу. Најједноставније.
   • mode="webhook" — Ваш сервер бира агента за сваког посетиоца путем web.incoming вебхука. Користите ово за пријављене кориснике, A/B тестове или рутирање по страници.
3. Наведите дозвољене домене

   Наведите сваки назив хоста који ће уградити виџет. Прегледачи шаљу извориште странице са сваким захтевом за сесију, па листа спречава да Ваш кључ ради када га неко копира на други сајт. Ово није аутентификација: скрипта ван прегледача може послати било које Origin заглавље. localhost није аутоматски дозвољен у продукцији; да бисте локално тестирали у односу на продукциони API, додајте localhost на листу.

4. Изаберите подешавања која прегледач може да замени

   Одлучите која подешавања сесије Ваша страница може да пошаље. Нови кључеви не прихватају ниједно; погледајте Замене подешавања у прегледачу.

Креирајте јавни кључ#

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

Одговор укључује key који почиње са pk_live_.... Јавни кључеви су по дизајну јавни — безбедно их је укључити у пакет Вашег клијентског дела. Погледајте референцу јавних кључева за сва поља.

Додајте виџет на свој сајт#

Три опције интеграције обухваћене су у документацији SDK-а за виџет:

Сва три прихватају исти publishableKey и приказују дугме микрофона и аудио елемент током позива.

Замене из прегледача#

Виџет може да пошаље четири подешавања по сесији са странице:

Ваш објављиви кључ је јаван, тако да свако ко га има може да пошаље ова подешавања, укључујући и из скрипте која се представља као Ваш домен. Зато је свако од њих искључено док га не дозволите за кључ: означите га у оквиру Преовлађивања у прегледачу када креирате или уређујете виџет на контролној табли или подесите allowed_overrides путем API-ја за објављиве кључеве. Дозволите само оно што Ваша страница заиста шаље.

Захтев за сесију који садржи подешавање које кључ не дозвољава не успева са 400 и наводи га:

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

Провера се примењује у оба режима. У режиму веб-закачке, дозвољено подешавање се такође прослеђује вашој веб-закачки web.incoming (context стиже као website_context). Кључеви креирани пре него што је ово подешавање постојало дозвољавају сва четири, тако да постојећа уграђивања настављају да раде; искључите оно што не користите.

context виџета се скраћује на 12.000 знакова (око 3.400 токена типичног енглеског текста) и рачуна се у доплату за величину промпта. Агенту се налаже да га третира као садржај странице, а не као упутства.

Веб-хукови у режиму виџета#

Када је mode="webhook", ThunderPhone позива Ваш webhook_url при сваком покретању сесије са web.incoming садржајем. Вратите конфигурацију агента коју желите да покренете за тог посетиоца — она прати исту шему одговора као телефонски позиви:

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

Можете у упит укључити контекст из сопствене сесије (који клијент прегледа, на којој је страници) и мењати агенте по фазама увођења.

Пратите сесије#

Сесије виџета се појављују у GET /v1/calls са direction="widget" — са истим транскриптом, снимком, оцењивањем и наплатом као и телефонски позиви. Филтрирајте по direction да бисте направили контролну таблу само за виџет.

Следећи кораци#