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

Уеб уиджетът дава на посетителите на сайта ви разговор с кликване за говорене
с AI агент, като използва микрофона на браузъра. Това е отделен
JavaScript / React SDK със собствена [SDK документация](/bg/widget/overview)
— това ръководство се фокусира върху настройката в ThunderPhone, необходима на уиджета.

<Note>
  Можете да направите всичко това без cURL: страницата в таблото **Уеб уиджети**
  (`/dashboard/web-widgets`) създава уиджета, задава режима
  и агента му, управлява разрешените домейни и ви предоставя кода за вграждане.
</Note>

## Предварителни изисквания

<Steps>
  <Step title="Създайте агент">
    Агентът, чиято подкана и глас ще се използват за сесията на уиджета. Задайте
    `widget_enabled: true` (по подразбиране).
  </Step>
  <Step title="Изберете режим на маршрутизиране">
    - `mode="agent"` — един статичен агент за ключ. Най-простият вариант.
    - `mode="webhook"` — вашият сървър избира агента за всеки посетител чрез
      [`web.incoming` уебкука](/bg/webhooks/call-incoming). Използвайте това за
      влезли в профила си потребители, A/B тестове или маршрутизиране по страници.
  </Step>
  <Step title="Посочете разрешените домейни">
    Публикуемите ключове са ограничени до източника. Трябва да посочите всяко име на хост,
    което ще вгражда уиджета. `localhost` / `127.0.0.1` винаги са
    разрешени по време на локална разработка.
  </Step>
</Steps>

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

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

```bash 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"]
  }'
```
</CodeGroup>

Отговорът включва `key`, започващ с `pk_live_...`. **Публикуемите
ключове по замисъл са публични** — безопасно е да ги включите във вашия front-end пакет.
Вижте [справката за публикуеми ключове](/api-reference/publishable-keys) за
всички полета.

<Warning>
  `allowed_domains` трябва да съдържа поне един запис. `*.example.com`
  съвпада с поддомейни (например `api.example.com`), но **не** със самия
  домейн. Непълни заместващи знаци като `*` или `*.*` се отхвърлят.
</Warning>

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

Три варианта за интеграция са разгледани в
[документацията за SDK на уиджета](/bg/widget/overview):

<CardGroup cols={3}>
  <Card title="React компонент" icon="react" href="/bg/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="Headless hook" icon="circle-nodes" href="/bg/widget/headless-hook">
    `useThunderPhone()` за персонализирани интерфейси.
  </Card>
  <Card title="CDN script таг" icon="code" href="/bg/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` за сайтове без bundler.
  </Card>
</CardGroup>

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

`context` на уиджета се съкращава до 12 000 знака (приблизително 3400
токена типичен английски текст) и се включва в
[доплащането за размер на подканата](/bg/guides/billing-and-topups).

## Уебкукове в режим на уиджет

Когато `mode="webhook"`, ThunderPhone извиква вашия `webhook_url` при всяко
стартиране на сесия с payload `web.incoming`. Върнете конфигурацията на агента,
който искате да се изпълнява за този посетител — тя следва същата
[схема на отговора](/bg/webhooks/call-incoming) като при телефонни
обаждания:

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

Можете да включвате контекст от собствената си сесия (кой клиент разглежда,
на коя страница се намира) в подканата и да сменяте агенти при всяко внедряване.

## Наблюдавайте сесиите

Сесиите на уиджета се показват в
[`GET /v1/calls`](/api-reference/calls#list-calls) с
`direction="widget"` — със същия транскрипт, запис, оценяване и
таксуване като телефонните обаждания. Филтрирайте по `direction`, за да създадете табло само за уиджета.

---

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

<CardGroup cols={2}>
  <Card title="Справочник за Widget SDK" icon="window-maximize" href="/bg/widget/overview">
    Подробности за интеграция с React / hook / CDN.
  </Card>
  <Card title="Динамична конфигурация за всяко обаждане" icon="bolt" href="/bg/guides/dynamic-call-config">
    Имплементирайте потока `mode="webhook"` от край до край.
  </Card>
  <Card title="Справочник за публикуваеми ключове" icon="key" href="/api-reference/publishable-keys">
    Всяко поле в ресурса за ключ.
  </Card>
  <Card title="API за сесии с микрофон" icon="microphone" href="/api-reference/mic-sessions">
    Пропуснете уиджета; управлявайте LiveKit директно за персонализирани потребителски интерфейси.
  </Card>
</CardGroup>