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

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

更多信息请参阅覆盖设置指南。

视觉自定义

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

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

小组件自定义

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

小组件外观

高级实现

如需更高级的自定义，请在 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。