Open in
Вграждане на уеб джаджата
Добавете гласов агент към вашия маркетингов или сайт за поддръжка с един-единствен script таг — посетителите говорят с него директно от браузъра, без да е необходим телефонен номер.
Уеб уиджетът дава на посетителите на сайта ви разговор с кликване за говорене с AI агент, като използва микрофона на браузъра. Това е отделен JavaScript / React SDK със собствена SDK документация — това ръководство се фокусира върху настройката в ThunderPhone, необходима на уиджета.
Предварителни изисквания
- Създайте агент
Агентът, чиято подкана и глас ще изпълняват сесията на уиджета. Задайте
widget_enabled: true(по подразбиране). - Изберете режим на маршрутизиране
mode="agent"— един статичен агент за всеки ключ. Най-простият вариант.mode="webhook"— вашият сървър избира агента за всеки посетител чрезweb.incomingуебхук. Използвайте това за влезли в профила си потребители, A/B тестове или маршрутизиране по страници.
- Избройте разрешените домейни
Посочете всяко име на хост, което ще вгражда уиджета. Браузърите изпращат произхода на страницата с всяка заявка за сесия, така че списъкът не позволява ключът ви да работи, когато някой го копира в друг сайт. Това не е удостоверяване: скрипт извън браузър може да изпрати всякаква заглавка
Origin.localhostне е разрешен автоматично в продукционна среда; за да тествате локално спрямо продукционния API, добаветеlocalhostкъм списъка. - Изберете заместванията от браузъра
Решете кои настройки на сесията може да изпраща страницата ви. Новите ключове не приемат никакви; вижте Замествания от браузъра.
Създайте публикуем ключ
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_.... Публикуемите
ключове по замисъл са публични — безопасно е да ги включите във вашия front-end пакет.
Вижте справката за публикуеми ключове за
всички полета.
Добавете уиджета към сайта си
Три варианта за интеграция са разгледани в документацията за SDK на уиджета:
<ThunderPhoneWidget publishableKey="pk_live_..." />.
useThunderPhone() за персонализирани интерфейси.
ThunderPhone.mount({...}) за сайтове без bundler.
И трите приемат един и същ publishableKey и визуализират бутона за микрофона
заедно с аудио елемента по време на разговор.
Замени от браузъра
Уиджетът може да изпраща четири настройки за сесия от страницата:
| Настройка | Свойство на уиджета | Какво променя |
|---|---|---|
context | context | Текст от страницата, добавен към подканата на агента като справочна информация |
variables | няма (само необработен POST /v1/widget/session) | Стойности за заместителите {{variable}} в подканата |
voice | voice | Гласът на агента за тази сесия |
language | language | Езикът, на който започва сесията |
Вашият публичен ключ е публичен, така че всеки, който го има, може да изпраща тези
настройки, включително от скрипт, който имитира вашия домейн. Затова всяка от тях е
изключена, докато не я разрешите за ключа: отметнете я в Замени от браузъра, когато
създавате или редактирате уиджета в таблото за управление, или задайте
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 при всяко
стартиране на сесия с payload 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, за да създадете табло само за уиджета.
Следващи стъпки
Подробности за интеграция с React / hook / CDN.
Имплементирайте потока mode="webhook" от край до край.
Всяко поле в ресурса за ключ.
Пропуснете уиджета; управлявайте LiveKit директно за персонализирани потребителски интерфейси.