> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 嵌入网页小组件

> 将语音智能体添加到您的营销或支持网站，无需电话号码。

网页小组件通过浏览器的麦克风，让您的网站访客能够与智能体进行点击通话对话。它是一个独立的 JavaScript / React SDK，并拥有自己的 [SDK 参考](/zh/widget/overview)——本指南重点介绍小组件所需的 ThunderPhone 端设置。

<Note>
  您无需使用 cURL 即可完成所有操作：**网页小组件**控制台页面
  （`/dashboard/web-widgets`）可创建小组件、设置其模式和智能体、管理允许的域名，并向您提供嵌入代码片段。
</Note>

## 前提条件

<Steps>
  <Step title="创建智能体">
    该智能体的提示词和语音将运行小组件会话。设置
    `widget_enabled: true`（默认值）。
  </Step>

  <Step title="确定路由模式">
    * `mode="agent"` —— 每个密钥对应一个静态智能体。最简单。
    * `mode="webhook"` —— 您的服务器通过
      [`web.incoming` webhook](/zh/webhooks/call-incoming) 为每位访客选择智能体。将其用于
      已登录用户、A/B 测试或按页面路由。
  </Step>

  <Step title="列出允许的域名">
    可发布密钥受来源限制。您必须列出将嵌入小组件的每个主机名。
    本地开发期间始终允许使用 `localhost` / `127.0.0.1`。
  </Step>
</Steps>

## 创建可发布密钥

<CodeGroup>
  ```bash Static agent theme={null}
  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 theme={null}
  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>

响应中包含一个以 `pk_live_...` 开头的 `key`。**可发布密钥在设计上是公开的**——可安全地包含在您的前端构建包中。
有关所有字段，请参阅[可发布密钥参考](/api-reference/publishable-keys)。

<Warning>
  `allowed_domains` 必须至少包含一个条目。`*.example.com`
  匹配子域名（例如 `api.example.com`），但**不**匹配裸域名。
  将拒绝 `*` 或 `*.*` 等裸通配符。
</Warning>

## 在您的网站中嵌入小组件

[小组件 SDK 文档](/zh/widget/overview)涵盖了三种集成选项：

<CardGroup cols={3}>
  <Card title="React 组件" icon="react" href="/zh/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`。
  </Card>

  <Card title="无头 Hook" icon="circle-nodes" href="/zh/widget/headless-hook">
    用于自定义 UI 的 `useThunderPhone()`。
  </Card>

  <Card title="CDN 脚本标签" icon="code" href="/zh/widget/cdn-script-tag">
    用于非构建工具网站的 `ThunderPhone.mount({...})`。
  </Card>
</CardGroup>

三种方式均接受相同的 `publishableKey`，并渲染麦克风按钮和通话中的音频元素。

小组件的 `context` 会被截断至 12,000 个字符（约为 3,400 个典型英文文本 token），并计入[提示词大小附加费](/zh/guides/billing-and-topups)。

## 小组件模式 webhook

当 `mode="webhook"` 时，ThunderPhone 会在每次会话开始时使用 `web.incoming` 负载调用您的 `webhook_url`。返回您希望为该访客运行的智能体配置——其遵循与电话呼叫相同的[响应架构](/zh/webhooks/call-incoming)：

```json theme={null}
{
  "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="小组件 SDK 参考" icon="window-maximize" href="/zh/widget/overview">
    React / hook / CDN 集成详情。
  </Card>

  <Card title="动态的每通通话配置" icon="bolt" href="/zh/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 以构建自定义 UI。
  </Card>
</CardGroup>