Вграждане на уеб джаджата

Уеб уиджетът дава на посетителите на сайта ви възможност за разговор с AI агент чрез кликване, като използва микрофона на браузъра. Това е отделен JavaScript / React SDK със собствена справка за SDK — това ръководство е насочено към настройката от страна на ThunderPhone, необходима за уиджета.

Предварителни условия

1. Създайте агент

   Агентът, чийто промпт и глас ще се използват за сесията на уиджета. Задайте widget_enabled: true (по подразбиране).

2. Изберете режима на маршрутизиране
   • mode="agent" — един статичен агент за ключ. Най-простият вариант.
   • mode="webhook" — сървърът ви избира агента за всеки посетител чрез уеб кука web.incoming. Използвайте това за влезли в профила си потребители, A/B тестове или маршрутизиране по страница.
3. Посочете разрешените домейни

   Публичните ключове са ограничени до определени източници. Трябва да посочите всяко име на хост, което ще вгражда уиджета. localhost / 127.0.0.1 винаги са разрешени при локална разработка.

Създайте публичен ключ

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

Отговорът включва key, започващ с pk_live_.... Публичните ключове са публични по замисъл — безопасни са за включване във фронтенд пакета ви. Вижте справката за публичните ключове за всички полета.

Добавете уиджета към сайта си

Три варианта за интеграция са разгледани в документацията за SDK на уиджета:

И трите приемат един и същ publishableKey и визуализират бутона за микрофона и аудио елемента по време на разговора.

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, за да създадете табло само за уиджета.

Следващи стъпки