小组件选项卡 | ElevenLabs Documentation

概述

托管一个加载智能体小组件的小型 HTML 页面，并将其作为 Teams 选项卡显示。用户可在 Teams 客户端中打开选项卡并与智能体交谈，无需电话号码或电话服务。这是最轻量的方式，适合内部自助助手和演示。

在 Microsoft Teams
选项卡中打开的 ElevenLabs 智能体小组件 — 在 Teams 选项卡中运行的智能体小组件

工作原理

该小组件是一个 Web 组件。Teams 会在 webview（iframe）中渲染选项卡的 contentUrl，因此小组件的运行方式与在网站上完全相同，包括麦克风采集，前提是该页面允许嵌入 Teams 并已获得媒体权限。

Teams 用户打开一个选项卡，其 webview 通过 iframe 嵌入托管页面。该页面运行 ElevenLabs 智能体小组件，并将音频流传输至 ElevenLabs — 嵌入 Teams 选项卡的小组件

Teams 不会执行粘贴到聊天、消息或 Loop 页面中的原始 <script>。小组件脚本必须位于你托管的页面上，然后由 Teams 将其嵌入为选项卡。

要求

一个公开的 ElevenLabs 智能体，且已禁用身份验证（智能体设置的“高级”选项卡）。小组件需要此配置。
用于托管单个静态 HTML 文件的 HTTPS 主机（Vercel、Netlify、Cloudflare Pages、Azure Static Web Apps 等）。
如果使用自定义选项卡方案，需要拥有在租户中上传自定义 Teams 应用的权限（Teams 管理中心 → 管理应用 → 上传自定义应用）。

第 1 步：创建小组件页面

创建包含小组件嵌入代码和智能体 ID 的 agent-widget.html：

agent-widget.html

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Voice Agent</title>
  </head>
  <body style="margin:0">
    <elevenlabs-convai
      agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"
    ></elevenlabs-convai>
    <script
      src="https://unpkg.com/@elevenlabs/convai-widget-embed"
      async
      type="text/javascript"
    ></script>
  </body>
</html>

将其部署到 HTTPS 主机，并先确认它能正常加载，且麦克风可在普通浏览器中使用。

如果工作区使用数据驻留环境，请添加小组件的 server-location 属性，使其连接到所在区域。支持的值请参阅小组件自定义。

在配置 Teams 前，先在浏览器中单独测试该页面。如果麦克风在浏览器中无法使用，在 Teams webview 中同样无法使用。

第 2 步：添加到 Teams

有两种选择，语音可靠性依次提高。

选项 A：网站选项卡（最快，但可能仅以链接方式打开）

在聊天或频道中，选择 + 添加选项卡 → 网站，粘贴 HTTPS URL 并保存。

内置的网站选项卡有时会将页面作为外部链接打开，而不是嵌入页面。即使已嵌入，Teams 桌面版 webview 也可能阻止麦克风访问。如果语音不可用，请使用选项 B。

选项 B：自定义选项卡应用（推荐用于语音）

一个小型自定义 Teams 应用会将页面声明为静态选项卡，并且请求媒体权限，这样才能让麦克风在 Teams 内稳定运行。

创建清单文件

创建 manifest.json。将 your-domain.com 替换为主机域名，并为 id 设置一个唯一的 GUID：

manifest.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
  "manifestVersion": "1.19",
  "version": "1.0.0",
  "id": "11111111-1111-1111-1111-111111111111",
  "developer": {
    "name": "ElevenLabs",
    "websiteUrl": "https://your-domain.com",
    "privacyUrl": "https://your-domain.com/privacy",
    "termsOfUseUrl": "https://your-domain.com/terms"
  },
  "name": { "short": "Voice Agent", "full": "ElevenLabs Voice Agent" },
  "description": {
    "short": "ElevenLabs voice agent",
    "full": "Embedded ElevenLabs voice agent"
  },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#000000",
  "staticTabs": [
    {
      "entityId": "voice-agent",
      "name": "Voice Agent",
      "contentUrl": "https://your-domain.com/agent-widget.html",
      "websiteUrl": "https://your-domain.com/agent-widget.html",
      "scopes": ["personal"]
    }
  ],
  "devicePermissions": ["media"],
  "validDomains": ["your-domain.com", "unpkg.com", "elevenlabs.io", "*.elevenlabs.io"]
}

语音相关的关键字段是 devicePermissions: ["media"]（麦克风），以及在 validDomains 中列出页面访问的所有域名（小组件脚本使用 unpkg.com，智能体使用 *.elevenlabs.io）。

打包应用

在清单文件旁添加 color.png（192×192）和 outline.png（32×32，透明），然后将清单文件和两个图标放在压缩包的根目录中：

zip -j voice-agent.zip manifest.json color.png outline.png

上传并打开

在 Teams 中：应用 → 管理应用 → 上传应用 → 上传自定义应用，选择 voice-agent.zip，然后打开 Voice Agent 选项卡，并在提示时授予麦克风访问权限。

Teams 管理员可以跳过客户端 UI，通过 PowerShell 将应用发布到整个组织。随后，所有人都可在 应用 → 为你的组织构建下找到它：

Connect-MicrosoftTeams
New-TeamsApp -DistributionMethod organization -Path ./voice-agent.zip

如果未出现提示，请打开选项卡的下拉菜单，选择 应用权限，手动授予麦克风访问权限：

突出显示“应用权限”的 Teams 选项卡下拉菜单 — 选项卡下拉菜单 → 应用权限

第 3 步：允许 Teams 嵌入页面

主机必须允许 Teams 通过 iframe 嵌入页面。如果可以控制响应标头，请设置：

Content-Security-Policy: frame-ancestors 'self' https://teams.microsoft.com https://*.teams.microsoft.com https://*.cloud.microsoft;

如果 Teams 始终在浏览器中打开页面而不是嵌入，说明页面被阻止通过 iframe 嵌入。请在主机上修复 CSP / X-Frame-Options。

故障排除

选项卡在浏览器中打开页面，而不是嵌入页面

页面被阻止通过 iframe 嵌入。移除所有 X-Frame-Options: DENY/SAMEORIGIN，并设置上文所示的 frame-ancestors CSP 以允许 Teams 域名。自定义选项卡应用（选项 B）也比内置网站选项卡更可靠。

小组件已加载，但麦克风无法使用

这是 Teams webview 的权限层问题。请使用包含 "devicePermissions": ["media"] 的自定义选项卡应用，并在 Teams 中授予应用麦克风权限（选项卡下拉菜单 → 应用权限）。Teams 网页版和桌面版的行为不同，请同时测试。作为备用方案，可提供“在浏览器中打开”链接。

小组件始终不显示

请确认智能体是公开的，且已禁用身份验证（智能体高级设置），并确认 unpkg.com 和 *.elevenlabs.io 已添加至清单的 validDomains。

概述