跳到导航
部署Web

小组件自定义

了解如何自定义小组件外观以匹配品牌，并通过 html 个性化智能体行为。

小组件可将 ElevenAgents 即时集成到任何网站。你可以通过 UI 自定义小组件，也可以使用类型安全的 ElevenAgents SDK，全面控制样式和行为。SDK 覆盖配置的优先级高于 UI 自定义。 小组件支持多模态，可同时处理文本和音频。

还可以通过 托管 MCP 服务器，从 Claude 或其他 MCP 客户端获取智能体的小组件配置和可分享链接。

模态配置

小组件支持灵活的输入模式，以适配不同使用场景。在控制台中依次前往 渠道 → 小组件 → 界面，即可配置这些选项。

客户端 SDK 完全支持多模态，详见 此处。

小组件界面选项

可用模式：

  • 仅语音（默认）：用户仅通过语音互动。
  • 语音 + 文本：用户可在对话中切换语音和文本输入。
  • 聊天模式：通过文本消息发起时，对话将以无语音功能的聊天（纯文本）模式开始。

如需了解如何通过 SDK 使用聊天（纯文本）模式，请参阅聊天模式指南。

小组件默认使用仅语音模式。启用文本输入切换按钮可支持多模态互动；如需通过文本发起纯文本对话，则启用纯文本模式支持。

嵌入小组件

小组件目前需要使用已关闭身份验证的公开智能体。请确保在智能体设置的 高级标签页中关闭此功能。

将以下代码片段添加到网站的 <body> 部分。为使其在全站可用，请放入主 index.html 文件：

小组件嵌入代码
<elevenlabs-convai agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"></elevenlabs-convai>
<script
  src="https://unpkg.com/@elevenlabs/convai-widget-embed"
  async
  type="text/javascript"
></script>

为增强安全性，请在智能体的 允许列表（位于 安全 标签页）中定义允许的域名。这会将访问权限限制为指定主机。

小组件属性

此基础嵌入代码会以智能体控制台中定义的默认配置显示小组件。 小组件支持多种 HTML 属性，以便进一步自定义：

<elevenlabs-convai
  agent-id="agent_id"              // Required: Your agent ID
  signed-url="signed_url"          // Alternative to agent-id
  server-location="us"             // Optional: "us" or default
  variant="expanded"               // Optional: Widget display mode
  dismissible="true"               // Optional: Allow the user to minimize the widget
></elevenlabs-convai>
<elevenlabs-convai
  avatar-image-url="https://..." // Optional: Custom avatar image
  avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
  avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
></elevenlabs-convai>
<elevenlabs-convai
  action-text="Need assistance?" // Optional: CTA button text
  start-call-text="Begin conversation" // Optional: Start call button
  end-call-text="End call" // Optional: End call button
  expand-text="Open chat" // Optional: Expand widget text
  listening-text="Listening..." // Optional: Listening state
  speaking-text="Assistant speaking" // Optional: Speaking state
></elevenlabs-convai>

小组件会渲染智能体回复中的 Markdown。为防止钓鱼，链接默认显示为纯文本。

<elevenlabs-convai
  markdown-link-allowed-hosts="example.com"  // Domains where links are clickable (use "*" for all)
  markdown-link-include-www="true"           // Also allow www variants (default: true)
  markdown-link-allow-http="true"            // Allow http:// links (default: true)
  syntax-highlight-theme="dark"              // Code block theme: "dark", "light", or "auto"
></elevenlabs-convai>

运行时配置

另外两个 html 属性可用于在运行时自定义智能体行为。这两项功能可同时使用、单独使用，或均不使用。

动态变量

动态变量可让你将运行时值注入智能体的消息、系统提示词和工具中。

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>

必须在小组件中传入智能体所需的所有动态变量。

详见动态变量 指南。

覆盖配置

覆盖配置可在运行时全面自定义智能体行为：

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  override-language="es"
  override-prompt="Custom system prompt for this user"
  override-first-message="Hi! How can I help you today?"
  override-voice-id="axXgspJ2msm3clMCkdW3"
></elevenlabs-convai>

可为特定字段启用覆盖配置，完全可选。

详见覆盖配置指南。

视觉自定义

自定义小组件外观、文本内容、语言选择等。

在控制台中打开智能体，前往 小组件 标签页，自定义外观、头像、文本、条款、语言支持等。

小组件自定义

自定义小组件颜色和形状，以匹配品牌形象。

小组件外观

富内容

富内容可让智能体在消息旁回复交互式组件。在控制台中依次前往 渠道 → 小组件 → 富内容 进行配置。

小组件富内容设置

富内容会显示在文本对话中；在 界面 下启用 对话实时转录 后，也会显示在语音对话中。它仅适用于嵌入式小组件。

快捷回复是用户可点击的按钮，无需手动输入。用户点击后，其标签会作为下一条消息发送。

快捷回复

由智能体建议

智能体可在对话中建议最多 3 条回复，例如确认选择或提供后续步骤。

首条消息回复

在 首条消息回复 下添加最多 3 条回复，使其与智能体的首条消息一同显示，用户可一键开始对话。拖动可更改顺序。

这些回复是固定的：每条首条消息都会显示，且不由智能体选择。它们会随其他语言预设一同翻译。

智能体如何使用富内容

除首条消息回复外，智能体会在每轮对话中决定是否显示快捷回复或轮播。无需组件的回复会保持为纯文本。要控制其出现的时机和方式，请在智能体的系统提示词中说明。

新建智能体默认启用快捷回复和轮播。对于富内容功能推出前创建的智能体，请在小组件设置中启用它们。

高级实现

如需更高级的自定义，请在 Next.js、React 或 Python 应用中使用类型安全的 ElevenAgents SDK。

客户端工具

客户端工具可通过添加事件监听器扩展小组件功能，让小组件能够执行以下操作：

  • 将用户重定向到特定页面
  • 向支持团队发送电子邮件
  • 将用户重定向到外部 URL

要查看这些工具的实际示例，请使用本页面右下角的智能体发起通话。可参考 GitHub 上的源代码。

创建客户端工具

要创建第一个客户端工具，请参阅客户端工具指南。

客户端工具配置

实现示例

以下示例展示如何在 JavaScript 代码中处理由小组件触发的 redirectToExternalURL 工具：

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");
        },
      };
    });
  }
});

探索适用于 React、Next.js 和 Python 实现的类型安全 SDK。