ThunderPhone v3 вече е тук.Започнете самостоятелно — от 2 цента/мин.Прочетете съобщението

Developer cookbook

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

Добавете гласов агент към вашия маркетингов или сайт за поддръжка с един-единствен script таг — посетителите говорят с него директно от браузъра, без да е необходим телефонен номер.

Уеб уиджетът дава на посетителите на сайта ви разговор с кликване за говорене с 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. Изберете заместванията от браузъра

    Решете кои настройки на сесията може да изпраща страницата ви. Новите ключове не приемат никакви; вижте Замествания от браузъра.

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

Static agent
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"]
  }'
Dynamic via webhook
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 на уиджета:

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

Замени от браузъра

Уиджетът може да изпраща четири настройки за сесия от страницата:

НастройкаСвойство на уиджетаКакво променя
contextcontextТекст от страницата, добавен към подканата на агента като справочна информация
variablesняма (само необработен POST /v1/widget/session)Стойности за заместителите {{variable}} в подканата
voicevoiceГласът на агента за тази сесия
languagelanguageЕзикът, на който започва сесията

Вашият публичен ключ е публичен, така че всеки, който го има, може да изпраща тези настройки, включително от скрипт, който имитира вашия домейн. Затова всяка от тях е изключена, докато не я разрешите за ключа: отметнете я в Замени от браузъра, когато създавате или редактирате уиджета в таблото за управление, или задайте 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, за да създадете табло само за уиджета.


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