> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.
# 小组件自定义
**小组件**可将 ElevenAgents 即时集成到任何网站。你可以通过 UI 自定义小组件，也可以使用类型安全的 [ElevenAgents SDK](/docs/zh/eleven-api/resources/libraries)，全面控制样式和行为。SDK 覆盖配置的优先级高于 UI 自定义。
小组件支持多模态，可同时处理文本和音频。
> **Note**
>
> 还可以通过 [托管 MCP 服务器](/docs/zh/eleven-agents/operate/hosted-mcp)，从 Claude 或其他
> MCP 客户端获取智能体的小组件配置和可分享链接。
## 模态配置
小组件支持灵活的输入模式，以适配不同使用场景。在控制台中依次前往 **渠道** → **小组件** → **界面**，即可配置这些选项。
> **Note**
>
> 客户端 SDK 完全支持多模态，详见
> [此处](/docs/zh/eleven-api/resources/libraries)。
**可用模式：**
* **仅语音**（默认）：用户仅通过语音互动。
* **语音 + 文本**：用户可在对话中切换语音和文本输入。
* **聊天模式**：通过文本消息发起时，对话将以无语音功能的聊天（纯文本）模式开始。
如需了解如何通过 SDK 使用聊天（纯文本）模式，请参阅[聊天模式指南](/docs/zh/eleven-agents/guides/chat-mode)。
> **Note**
>
> 小组件默认使用仅语音模式。启用文本输入切换按钮可支持多模态互动；如需通过文本发起纯文本对话，则启用纯文本模式支持。
## 嵌入小组件
> **Note**
>
> 小组件目前需要使用已关闭身份验证的公开智能体。请确保在智能体设置的
> **高级**标签页中关闭此功能。
将以下代码片段添加到网站的 `` 部分。为使其在全站可用，请放入主 `index.html` 文件：
**`小组件嵌入代码`**
```html title="小组件嵌入代码"
```
> **Info**
>
> 为增强安全性，请在智能体的 **允许列表**（位于 **安全** 标签页）中定义允许的域名。这会将访问权限限制为指定主机。
## 小组件属性
此基础嵌入代码会以智能体控制台中定义的默认配置显示小组件。
小组件支持多种 HTML 属性，以便进一步自定义：
#### 核心配置
```html
```
#### 视觉自定义
```html
```
#### 文本自定义
```html
```
#### Markdown 渲染
小组件会渲染智能体回复中的 Markdown。为防止钓鱼，链接默认显示为纯文本。
```html
```
## 运行时配置
另外两个 html 属性可用于在运行时自定义智能体行为。这两项功能可同时使用、单独使用，或均不使用。
### 动态变量
动态变量可让你将运行时值注入智能体的消息、系统提示词和工具中。
```html
```
必须在小组件中传入智能体所需的所有动态变量。
> **Info**
>
> 详见[动态变量 指南](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)。
### 覆盖配置
覆盖配置可在运行时全面自定义智能体行为：
```html
```
可为特定字段启用覆盖配置，完全可选。
> **Info**
>
> 详见[覆盖配置指南](/docs/zh/eleven-agents/customization/personalization/overrides)。
## 视觉自定义
自定义小组件外观、文本内容、语言选择等。
#### 通过控制台更新
在控制台中打开智能体，前往 **小组件** 标签页，自定义外观、头像、文本、条款、语言支持等。
#### 通过 CLI 更新
#### 拉取智能体配置
```bash
elevenlabs agents pull --agent ""
```
#### 编辑 \`agent_configs/\.json\`
在 `platform_settings.widget` 下设置字段。例如，要更改光球颜色和反馈模式：
```json
{
"platform_settings": {
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB"
},
"feedback_mode": "during",
"bg_color": "#ffffff",
"text_color": "#000000",
"btn_color": "#000000",
"btn_text_color": "#ffffff"
}
}
}
```
#### 推送更改
```bash
elevenlabs agents push --agent ""
```
#### 通过 API 更新
```python
from elevenlabs import ElevenLabs
elevenlabs = ElevenLabs()
elevenlabs.conversational_ai.agents.update(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
platform_settings={
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB",
},
"feedback_mode": "during",
},
},
)
```
```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
platformSettings: {
widget: {
variant: "full",
placement: "bottom-right",
avatar: {
type: "orb",
color1: "#6DB035",
color2: "#F5CABB",
},
feedbackMode: "during",
},
},
});
```
#### 外观
自定义小组件颜色和形状，以匹配品牌形象。
#### 反馈
收集用户洞察以提升智能体表现。可用于微调智能体的知识库和系统提示词。
**收集模式**
* **无**：完全禁用反馈收集。
* **对话中**：支持在对话期间提供实时反馈。还会收集触发反馈的智能体回复等额外元数据，帮助进一步识别不足之处。
* **对话后**：对话结束后显示一次反馈提示。
> **Note**
>
> 使用自定义 SDK 实现时，可通过 [API](/docs/zh/eleven-agents/api-reference/conversations/create) 以编程方式发送反馈。
#### 头像
配置语音光球或提供自己的头像。
**可用选项**
* **光球**：选择两种渐变色（例如 #6DB035 和 #F5CABB）。
* **链接/图片**：使用自定义头像图片。
#### 显示文本
自定义小组件显示的所有文本元素，例如修改按钮标签。
#### 条款
在对话前显示自定义条款与条件。
**可用选项**
* **条款内容**：使用 Markdown 设置政策文本格式。
* **本地存储键**：用于避免重复提示回访用户的键（例如 "terms_accepted"）。
**用法**
发起通话前，系统会在模态窗口中向用户显示条款：
条款可使用 Markdown 编写，你可以：
* 添加外部政策链接
* 使用标题和列表设置文本格式
* 添加强调和样式
有关 Markdown 的更多帮助，请参阅 [CommonMark 帮助指南](https://commonmark.org/help/)。
> **Info**
>
> 接受后，状态会保存在本地，用户后续访问时不会再次收到提示。
#### 语言
在小组件中启用多语言支持。
> **Note**
>
> 要启用语言选择，必须先为智能体[添加其他 语言](/docs/zh/eleven-agents/customization/voice/customization/language)。
#### 静音
允许用户在小组件中将音频静音。
要添加静音按钮，请在智能体 `widget` 设置的 `interface` 卡片中启用此功能。
#### 可分享页面
自定义公开的小组件落地页（可分享链接）。
**可用选项**
* **描述**：简要说明通话目的。
## 富内容
富内容可让智能体在消息旁回复交互式组件。在控制台中依次前往 **渠道** → **小组件** → **富内容** 进行配置。
富内容会显示在文本对话中；在 **界面** 下启用 **对话实时转录** 后，也会显示在语音对话中。它仅适用于嵌入式小组件。
#### 快捷回复
快捷回复是用户可点击的按钮，无需手动输入。用户点击后，其标签会作为下一条消息发送。
**由智能体建议**
智能体可在对话中建议最多 3 条回复，例如确认选择或提供后续步骤。
**首条消息回复**
在 **首条消息回复** 下添加最多 3 条回复，使其与智能体的首条消息一同显示，用户可一键开始对话。拖动可更改顺序。
这些回复是固定的：每条首条消息都会显示，且不由智能体选择。它们会随其他[语言预设](/docs/zh/eleven-agents/customization/voice/customization/language)一同翻译。
#### 轮播
智能体最多可将 5 个项目显示为可滚动卡片，例如搜索结果或产品推荐。
**卡片内容**
每张卡片都有标题，还可包含副标题、图片、描述和最多 3 个按钮。用户点击卡片按钮时，其标签会与项目标题一同作为用户的下一条消息发送。
**提示轮播**
只有智能体有真实项目可显示时，轮播才会生效。它会根据[工具](/docs/zh/eleven-agents/customization/tools)返回的内容或[知识库](/docs/zh/eleven-agents/customization/knowledge-base)提供的内容构建卡片，不会编造项目、价格或图片。没有可返回项目的工具或知识库的智能体很少会显示轮播。
在提示词中，告知智能体：
* **何时显示轮播**，例如用户要求浏览或比较产品时。
* **各字段填写什么**，例如产品名称作为标题，价格作为副标题。
* **添加哪些按钮，以及点击后该做什么。** 只要求添加智能体能实际处理的按钮。**加入购物车**按钮需要有能将商品加入购物车的工具，否则点击后不会有任何结果。
将如下说明添加到系统提示词中，并将方括号内的工具名称替换为自己的工具：
**`示例提示词`**
```markdown title="示例提示词"
# Product carousel
When the user asks to browse, search or compare products, call [your product search tool] and show the results as a carousel.
- Title: the product name
- Subtitle: the price
- Description: a one-sentence summary
- Image: the product image URL from the search results
Give each card "View product" and "Add to cart" buttons. When the user picks "Add to cart" on a card, call [your add to cart tool] with that product.
```
**故障排除**
* **未显示轮播**：检查工具或知识库是否返回了智能体可显示的项目，以及提示词是否说明了何时使用轮播。
* **卡片没有图片**：仅当图片 URL 先前出现在对话中（例如工具结果中），且通过 HTTPS 提供时，才会显示卡片图片。请确保工具返回图片 URL。
### 智能体如何使用富内容
除首条消息回复外，智能体会在每轮对话中决定是否显示快捷回复或轮播。无需组件的回复会保持为纯文本。要控制其出现的时机和方式，请在智能体的[系统提示词](/docs/zh/eleven-agents/best-practices/prompting-guide)中说明。
新建智能体默认启用快捷回复和轮播。对于富内容功能推出前创建的智能体，请在小组件设置中启用它们。
---
## 高级实现
> **Note**
>
> 如需更高级的自定义，请在 Next.js、React 或 Python 应用中使用类型安全的 [ElevenAgents SDK](/docs/zh/eleven-api/resources/libraries)。
### 客户端工具
客户端工具可通过添加事件监听器扩展小组件功能，让小组件能够执行以下操作：
* 将用户重定向到特定页面
* 向支持团队发送电子邮件
* 将用户重定向到外部 URL
要查看这些工具的实际示例，请使用本页面右下角的智能体发起通话。可参考 [GitHub 上的源代码](https://github.com/elevenlabs/elevenlabs-dx/blob/main/fern/assets/scripts/widget.js)。
#### 创建客户端工具
要创建第一个客户端工具，请参阅[客户端工具指南](/docs/zh/eleven-agents/customization/tools/client-tools)。
#### 示例：创建 \`redirectToExternalURL\` 工具
#### 实现示例
以下示例展示如何在 JavaScript 代码中处理由小组件触发的 `redirectToExternalURL` 工具：
**`index.js`**
```javascript title="index.js"
document.addEventListener("DOMContentLoaded", () => {
const widget = document.querySelector("elevenlabs-convai");
if (widget) {
// Listen for the widget's "call" event to trigger client-side tools
widget.addEventListener("elevenlabs-convai:call", (event) => {
event.detail.config.clientTools = {
// Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
redirectToExternalURL: ({ url }) => {
window.open(url, "_blank", "noopener,noreferrer");
},
};
});
}
});
```
> **Info**
>
> 探索适用于 React、Next.js 和 Python 实现的类型安全 [SDK](/docs/zh/eleven-api/resources/libraries)。