> 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.

# 小组件选项卡

## 概述

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

![在 Microsoft Teams
选项卡中打开的 ElevenLabs 智能体小组件](/docs/_fern-img/8fedd2110258c6751012619128601214cdfcd4a11aaa832f62050c00c52106e7.webp)

## 工作原理

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

![Teams 用户打开一个选项卡，其 webview 通过 iframe 嵌入托管页面。该页面运行 ElevenLabs 智能体小组件，并将音频流传输至 ElevenLabs](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/c90698c01d5e874b3a3fa8a07af5ef64620e0fe8a602155aed31bd3f1ce06273/assets/images/conversational-ai/teams-widget-architecture.svg)

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

## 要求

1. 一个**公开**的 [ElevenLabs 智能体](/docs/zh/eleven-agents/quickstart)，且已禁用身份验证（智能体设置的“高级”选项卡）。小组件需要此配置。
2. 用于托管单个静态 HTML 文件的 HTTPS 主机（Vercel、Netlify、Cloudflare Pages、Azure Static Web Apps 等）。
3. 如果使用自定义选项卡方案，需要拥有在租户中上传自定义 Teams 应用的权限（[Teams 管理中心 → 管理应用](https://admin.teams.microsoft.com/policies/manage-apps) → 上传自定义应用）。

## 第 1 步：创建小组件页面

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

**`agent-widget.html`**

```html title="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 主机，并先确认它能正常加载，且麦克风可在普通浏览器中使用。

> **Note**
>
> 如果工作区使用[数据驻留](/docs/zh/overview/administration/data-residency)
> 环境，请添加小组件的 `server-location` 属性，使其连接到所在区域。支持的值请参阅
> [小组件自定义](/docs/zh/eleven-agents/customization/widget)。

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

## 第 2 步：添加到 Teams

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

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

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

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

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

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

#### 创建清单文件

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

**`manifest.json`**

```json title="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，透明），然后将清单文件和两个图标放在压缩包的**根目录**中：

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

#### 上传并打开

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

> **Tip**
>
> Teams 管理员可以跳过客户端 UI，通过 PowerShell 将应用发布到整个组织。随后，所有人都可在 **应用 → 为你的组织构建**下找到它：
>
> ```powershell
> Connect-MicrosoftTeams
> New-TeamsApp -DistributionMethod organization -Path ./voice-agent.zip
> ```

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

![突出显示“应用权限”的 Teams 选项卡下拉菜单
](/docs/_fern-img/308d95d230864371f4ad2cd8b329c503e672878788a1fdcbc49ab2ce6aa8ce7d.webp)

## 第 3 步：允许 Teams 嵌入页面

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

```http
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`。

## 实用链接

* [小组件自定义](/docs/zh/eleven-agents/customization/widget)
* [Teams 选项卡要求](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/tab-requirements)
* [创建个人选项卡](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/create-personal-tab)
* [Teams 设备权限](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/device-capabilities/native-device-permissions)