diff --git a/docs/getting-started/channel-deployment.md b/docs/getting-started/channel-deployment.md index ab940062..0b94d850 100644 --- a/docs/getting-started/channel-deployment.md +++ b/docs/getting-started/channel-deployment.md @@ -801,9 +801,11 @@ After creation, note down: ### Step 3: Configure Graph API Permissions -In your App Registration, go to **API permissions** → **Add a permission** → **Microsoft Graph** → **Application permissions**. +In your App Registration, go to **API permissions** → **Add a permission** → **Microsoft Graph**. -Add the following permissions: +#### Application Permissions + +Select **Application permissions** and add: | Permission | Purpose | |------------|---------| @@ -812,9 +814,23 @@ Add the following permissions: | `ChannelMessage.Read.All` | Read team channel message history | | `User.Read.All` | Resolve user mentions and search users | -After adding all four, click **Grant admin consent for [your organization]** and confirm. All permissions should show a green checkmark. +#### Delegated Permissions + +Go back to **Add a permission** → **Microsoft Graph** → **Delegated permissions** and add: + +| Permission | Purpose | +|------------|---------| +| `Chat.ReadWrite` | Read and send chat messages on behalf of the user | +| `ChannelMessage.Send` | Send channel messages on behalf of the user | +| `ChannelMessage.Read.All` | Read channel messages on behalf of the user | +| `Files.Read.All` | Access files the user can access | +| `offline_access` | Maintain access when the user is not actively signed in | + +#### Grant Admin Consent + +After adding all 9 permissions (4 application + 5 delegated), click **Grant admin consent for [your organization]** and confirm. All permissions should show a green checkmark. -> **Important:** Admin consent is required. Without it, file downloads, chat history, and smart mode features will not work. +> **Important:** Admin consent is required. Without it, file downloads, chat history, emoji reactions, and smart mode features will not work. ### Step 4: Create an Azure Bot Resource @@ -856,63 +872,31 @@ After connecting, the employee detail page displays a **Messaging Endpoint** URL ### Step 7: Create and Install the Teams App Manifest -To make the bot available in Teams, you need a Teams App Manifest: +To make the bot available in Teams, you need a Teams App Manifest — a `.zip` file containing a `manifest.json` and two icon files. -::: warning The manifest below is NOT copy-paste ready -You must replace all `` placeholders (3 places) with your actual App ID from Step 1 before zipping and uploading. +We provide a ready-made template with the COCO icon included. Download all three files: + +- [manifest.json](/ms-teams-manifest/manifest.json) — app manifest template +- [color.png](/ms-teams-manifest/color.png) — 192x192 full-color app icon +- [outline.png](/ms-teams-manifest/outline.png) — 32x32 transparent outline icon + +::: warning Edit manifest.json before zipping +Open `manifest.json` in any text editor and replace all placeholders with your actual values. ::: -1. Create a folder with three files: +**Placeholders to replace:** -**manifest.json:** -```json -{ - "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json", - "manifestVersion": "1.17", - "version": "1.0.0", - "id": "", - "developer": { - "name": "Your Company", - "websiteUrl": "https://coco.xyz", - "privacyUrl": "https://coco.xyz/privacy", - "termsOfUseUrl": "https://coco.xyz/terms" - }, - "name": { "short": "COCO AI Employee" }, - "description": { - "short": "AI-powered assistant", - "full": "COCO AI Employee connected via Microsoft Teams" - }, - "icons": { "color": "color.png", "outline": "outline.png" }, - "accentColor": "#4F6BED", - "bots": [{ - "botId": "", - "scopes": ["personal", "team", "groupChat"], - "supportsFiles": true, - "isNotificationOnly": false - }], - "permissions": ["messageTeamMembers"], - "validDomains": [], - "webApplicationInfo": { - "id": "", - "resource": "https://graph.microsoft.com" - }, - "authorization": { - "permissions": { - "resourceSpecific": [ - { "name": "ChatMessage.Read.Chat", "type": "Application" }, - { "name": "ChannelMessage.Read.Group", "type": "Application" } - ] - } - } -} -``` +| Placeholder | Replace With | Where | +|-------------|-------------|-------| +| `` | Your App ID from Step 1 | `id`, `botId`, `webApplicationInfo.id` (3 places) | +| `` | Your company or team name | `developer.name` | +| `` | Bot name shown in Teams (e.g., `COCO AI Employee`) | `name.short` | +| `` | One-line summary (e.g., `AI-powered assistant`) | `description.short` | +| `` | Longer description | `description.full` | -> **Note:** Replace `` in all three places (`id`, `botId`, `webApplicationInfo.id`). The `webApplicationInfo` section enables Graph API integration. The `resourceSpecific` permissions enable resource-specific consent (RSC) for reading messages in chats and channels where the bot is installed. +> **Note on scopes:** The `scopes` field defines where the bot can be used: `personal` = 1:1 DM conversations, `team` = team channels, `groupChat` = group chats. All three are enabled by default. The `resourceSpecific` permissions enable resource-specific consent (RSC) for reading messages in chats and channels where the bot is installed. -2. Add two icon files: - - **color.png** — 192x192 pixels, full-color app icon - - **outline.png** — 32x32 pixels, transparent outline icon -3. Zip all three files into a single `.zip` file +After editing `manifest.json`, select all three files and compress them into a single `.zip` file. **Install in Teams:** - **Sideload (testing):** In Teams → Apps → Manage your apps → Upload a custom app → select the `.zip` diff --git a/docs/public/ms-teams-manifest/color.png b/docs/public/ms-teams-manifest/color.png new file mode 100644 index 00000000..decb1ea2 Binary files /dev/null and b/docs/public/ms-teams-manifest/color.png differ diff --git a/docs/public/ms-teams-manifest/manifest.json b/docs/public/ms-teams-manifest/manifest.json new file mode 100644 index 00000000..f80b5389 --- /dev/null +++ b/docs/public/ms-teams-manifest/manifest.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json", + "manifestVersion": "1.17", + "version": "1.0.0", + "id": "", + "developer": { + "name": "", + "websiteUrl": "https://coco.xyz", + "privacyUrl": "https://coco.xyz/privacy", + "termsOfUseUrl": "https://coco.xyz/terms" + }, + "name": { "short": "" }, + "description": { + "short": "", + "full": "" + }, + "icons": { "color": "color.png", "outline": "outline.png" }, + "accentColor": "#4F6BED", + "bots": [{ + "botId": "", + "scopes": ["personal", "team", "groupChat"], + "supportsFiles": true, + "isNotificationOnly": false + }], + "permissions": ["messageTeamMembers"], + "validDomains": [], + "webApplicationInfo": { + "id": "", + "resource": "https://graph.microsoft.com" + }, + "authorization": { + "permissions": { + "resourceSpecific": [ + { "name": "ChatMessage.Read.Chat", "type": "Application" }, + { "name": "ChannelMessage.Read.Group", "type": "Application" } + ] + } + } +} diff --git a/docs/public/ms-teams-manifest/outline.png b/docs/public/ms-teams-manifest/outline.png new file mode 100644 index 00000000..d47b3b8b Binary files /dev/null and b/docs/public/ms-teams-manifest/outline.png differ diff --git a/docs/zh/getting-started/channel-deployment.md b/docs/zh/getting-started/channel-deployment.md index dd9b94a3..8782b0bb 100644 --- a/docs/zh/getting-started/channel-deployment.md +++ b/docs/zh/getting-started/channel-deployment.md @@ -931,9 +931,11 @@ Bot 需要独立身份。只有使用专属号码，其他人才能把它当作 ### 第3步：配置 Graph API 权限 -在 App Registration 页面，进入 **API permissions** → **Add a permission** → **Microsoft Graph** → **Application permissions**。 +在 App Registration 页面，进入 **API permissions** → **Add a permission** → **Microsoft Graph**。 -添加以下权限： +#### 应用程序权限（Application Permissions） + +选择 **Application permissions**，添加以下权限： | 权限 | 用途 | |------|------| @@ -942,9 +944,23 @@ Bot 需要独立身份。只有使用专属号码，其他人才能把它当作 | `ChannelMessage.Read.All` | 读取团队频道消息历史 | | `User.Read.All` | 解析用户提及和搜索用户 | -全部添加后，点击 **Grant admin consent for [你的组织]** 并确认。所有权限应显示绿色勾号。 +#### 委托权限（Delegated Permissions） + +返回 **Add a permission** → **Microsoft Graph** → **Delegated permissions**，添加以下权限： + +| 权限 | 用途 | +|------|------| +| `Chat.ReadWrite` | 代表用户读取和发送聊天消息 | +| `ChannelMessage.Send` | 代表用户发送频道消息 | +| `ChannelMessage.Read.All` | 代表用户读取频道消息 | +| `Files.Read.All` | 访问用户有权访问的文件 | +| `offline_access` | 在用户未主动登录时保持访问权限 | + +#### 授予管理员同意 + +全部 9 项权限（4 项应用程序权限 + 5 项委托权限）添加完成后，点击 **Grant admin consent for [你的组织]** 并确认。所有权限应显示绿色勾号。 -> **注意：** 必须获得管理员同意。否则文件下载、聊天历史和智能模式功能将无法使用。 +> **注意：** 必须获得管理员同意。否则文件下载、聊天历史、表情回应和智能模式功能将无法使用。 ### 第4步：创建 Azure Bot 资源 @@ -986,63 +1002,31 @@ Bot 需要独立身份。只有使用专属号码，其他人才能把它当作 ### 第7步：创建并安装 Teams App Manifest -要让机器人在 Teams 中可用，需要创建 Teams App Manifest： +要让机器人在 Teams 中可用，需要一个 Teams App Manifest — 包含 `manifest.json` 和两个图标文件的 `.zip` 压缩包。 -::: warning 以下 manifest 不能直接复制使用 -你必须将其中所有 `` 占位符（共 3 处）替换为第1步中获取的实际 App ID，然后再打包上传。 +我们提供了包含 COCO 图标的现成模板，下载以下三个文件： + +- [manifest.json](/ms-teams-manifest/manifest.json) — 应用 manifest 模板 +- [color.png](/ms-teams-manifest/color.png) — 192x192 全彩应用图标 +- [outline.png](/ms-teams-manifest/outline.png) — 32x32 透明轮廓图标 + +::: warning 压缩前请编辑 manifest.json +用任意文本编辑器打开 `manifest.json`，将所有占位符替换为你的实际值。 ::: -1. 创建一个文件夹，包含三个文件： +**需要替换的占位符：** -**manifest.json：** -```json -{ - "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json", - "manifestVersion": "1.17", - "version": "1.0.0", - "id": "", - "developer": { - "name": "Your Company", - "websiteUrl": "https://coco.xyz", - "privacyUrl": "https://coco.xyz/privacy", - "termsOfUseUrl": "https://coco.xyz/terms" - }, - "name": { "short": "COCO AI Employee" }, - "description": { - "short": "AI-powered assistant", - "full": "COCO AI Employee connected via Microsoft Teams" - }, - "icons": { "color": "color.png", "outline": "outline.png" }, - "accentColor": "#4F6BED", - "bots": [{ - "botId": "", - "scopes": ["personal", "team", "groupChat"], - "supportsFiles": true, - "isNotificationOnly": false - }], - "permissions": ["messageTeamMembers"], - "validDomains": [], - "webApplicationInfo": { - "id": "", - "resource": "https://graph.microsoft.com" - }, - "authorization": { - "permissions": { - "resourceSpecific": [ - { "name": "ChatMessage.Read.Chat", "type": "Application" }, - { "name": "ChannelMessage.Read.Group", "type": "Application" } - ] - } - } -} -``` +| 占位符 | 替换为 | 位置 | +|--------|-------|------| +| `` | 第1步获取的 App ID | `id`、`botId`、`webApplicationInfo.id`（共 3 处） | +| `` | 你的公司或团队名称 | `developer.name` | +| `` | 在 Teams 中显示的 Bot 名称（如 `COCO AI 员工`） | `name.short` | +| `` | 一句话简介（如 `AI 智能助手`） | `description.short` | +| `` | 详细描述 | `description.full` | -> **说明：** 将 `` 替换为你的实际 App ID（`id`、`botId`、`webApplicationInfo.id` 三处）。`webApplicationInfo` 部分启用 Graph API 集成。`resourceSpecific` 权限启用资源特定同意（RSC），允许在安装了机器人的聊天和频道中读取消息。 +> **关于 scopes 字段：** `scopes` 定义 Bot 可以在哪些场景中使用：`personal` = 1对1私聊，`team` = 团队频道，`groupChat` = 群聊。默认三个都已启用。`resourceSpecific` 权限启用资源特定同意（RSC），允许在安装了机器人的聊天和频道中读取消息。 -2. 添加两个图标文件： - - **color.png** — 192x192 像素，全彩应用图标 - - **outline.png** — 32x32 像素，透明轮廓图标 -3. 将三个文件压缩为一个 `.zip` 文件 +编辑完 `manifest.json` 后，选中这三个文件压缩为一个 `.zip` 文件。 **在 Teams 中安装：** - **侧载安装（测试）：** Teams → Apps → Manage your apps → Upload a custom app → 选择 `.zip` 文件