---
title: "Pachika wijeti ya wavuti"
description: "Weka ejenti ya sauti kwenye tovuti yako ya uuzaji au usaidizi kwa tagi moja ya script — wageni wanaizungumza moja kwa moja kutoka kwenye kivinjari, bila nambari ya simu kuhitajika."
---

Wijeti ya wavuti huwapa wageni wa tovuti yako mazungumzo ya kubofya ili kuzungumza
na ejenti wa AI, kwa kutumia maikrofoni ya kivinjari. Ni SDK tofauti ya
JavaScript / React yenye [marejeleo yake ya SDK](/sw/widget/overview)
— mwongozo huu unaangazia usanidi wa upande wa ThunderPhone unaohitajika na wijeti.

<Note>
  Unaweza kufanya haya yote bila cURL: ukurasa wa dashibodi wa **Wijeti za Wavuti**
  (`/dashboard/web-widgets`) huunda wijeti, huweka hali
  na ejenti yake, husimamia domeni zinazoruhusiwa, na hukupa kijisehemu cha kupachika.
</Note>

## Mahitaji ya awali

<Steps>
  <Step title="Unda ejenti">
    Ejenti ambaye prompt na sauti yake zitaendesha kipindi cha wijeti. Weka
    `widget_enabled: true` (chaguo-msingi).
  </Step>
  <Step title="Amua hali ya uelekezaji">
    - `mode="agent"` — ejenti mmoja wa kudumu kwa kila ufunguo. Rahisi zaidi.
    - `mode="webhook"` — seva yako huchagua ejenti kwa kila mgeni kupitia
      [`web.incoming` webhook](/sw/webhooks/call-incoming). Tumia hii kwa
      watumiaji walioingia, majaribio ya A/B, au uelekezaji kwa kila ukurasa.
  </Step>
  <Step title="Orodhesha domeni zinazoruhusiwa">
    Funguo zinazoweza kuchapishwa hufungwa kwa origin. Lazima utaje kila hostname
    itakayopachika wijeti. `localhost` / `127.0.0.1` huruhusiwa daima
    wakati wa usanidi wa ndani.
  </Step>
</Steps>

## Unda ufunguo unaoweza kuchapishwa

<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>

Jibu linajumuisha `key` inayoanza na `pk_live_...`. **Funguo zinazoweza kuchapishwa
ni za umma kimakusudi** — ni salama kujumuisha katika kifurushi chako cha front-end.
Angalia [marejeleo ya funguo zinazoweza kuchapishwa](/api-reference/publishable-keys) kwa
sehemu zote.

<Warning>
  `allowed_domains` lazima iwe na angalau ingizo moja. `*.example.com`
  hulingana na subdomaini (kwa mfano, `api.example.com`) lakini **si**
  domeni isiyo na subdomaini. Wildcardi tupu kama `*` au `*.*` hukataliwa.
</Warning>

## Ongeza wijeti kwenye tovuti yako

Chaguo tatu za ujumuishaji zimeelezwa katika
[nyaraka za SDK ya wijeti](/sw/widget/overview):

<CardGroup cols={3}>
  <Card title="Kipengele cha React" icon="react" href="/sw/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="Hook isiyo na kiolesura" icon="circle-nodes" href="/sw/widget/headless-hook">
    `useThunderPhone()` kwa UI maalum.
  </Card>
  <Card title="Lebo ya script ya CDN" icon="code" href="/sw/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` kwa tovuti zisizotumia bundler.
  </Card>
</CardGroup>

Zote tatu zinakubali `publishableKey` sawa na huonyesha kitufe cha maikrofoni
pamoja na kipengele cha sauti wakati wa simu.

`context` ya wijeti hukatwa hadi herufi 12,000 (takriban tokeni 3,400
za maandishi ya kawaida ya Kiingereza) na huhesabiwa katika
[ada ya ziada ya ukubwa wa prompt](/sw/guides/billing-and-topups).

## Webhook za hali ya wijeti

Wakati `mode="webhook"`, ThunderPhone hupiga `webhook_url` yako kila
kipindi kinapoanza kwa payload ya `web.incoming`. Rudisha usanidi wa ejenti
unaotaka kuendesha kwa mgeni huyo — unafuata [schema sawa ya jibu](/sw/webhooks/call-incoming) kama
simu za kawaida:

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

Unaweza kuchanganya muktadha kutoka kwenye kipindi chako mwenyewe (ni mteja gani anavinjari,
yuko kwenye ukurasa gani) kwenye prompt, na kubadilisha ejenti kwa kila utoaji.

## Fuatilia sesheni

Sesheni za wijeti huonekana katika
[`GET /v1/calls`](/api-reference/calls#list-calls) kwa
`direction="widget"` — zikiwa na nakala sawa ya mazungumzo, kurekodi, tathmini na
utozaji kama simu. Chuja kwa `direction` ili kutengeneza dashibodi ya
wijeti pekee.

---

## Hatua zinazofuata

<CardGroup cols={2}>
  <Card title="Marejeleo ya SDK ya wijeti" icon="window-maximize" href="/sw/widget/overview">
    Maelezo ya muunganisho wa React / hook / CDN.
  </Card>
  <Card title="Usanidi unaobadilika kwa kila simu" icon="bolt" href="/sw/guides/dynamic-call-config">
    Tekeleza mtiririko wa `mode="webhook"` kutoka mwanzo hadi mwisho.
  </Card>
  <Card title="Marejeleo ya funguo zinazoweza kuchapishwa" icon="key" href="/api-reference/publishable-keys">
    Kila sehemu kwenye rasilimali ya ufunguo.
  </Card>
  <Card title="API ya sesheni za maikrofoni" icon="microphone" href="/api-reference/mic-sessions">
    Ruka wijeti; endesha LiveKit moja kwa moja kwa UI maalum.
  </Card>
</CardGroup>