teams-bot-infra

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Teams Bot Infrastructure Management

Teams机器人基础设施管理

This skill guides you through creating, configuring, and troubleshooting Microsoft Teams bot infrastructure using the Teams CLI. It does NOT cover building or hosting bot application code.

本技能指导你使用Teams CLI完成Microsoft Teams机器人基础设施的创建、配置与问题排查，不涵盖机器人应用代码的构建或托管内容。

1. Prerequisites Verification

1. 前置条件校验

Before creating a Teams bot, verify these prerequisites:

创建Teams机器人前，请先校验以下前置条件：

Step 1: Check Teams CLI Installation

步骤1：检查Teams CLI安装情况

Verify the Teams CLI is installed:

bash

teams --version

Expected output: Shows version number (e.g.,

1.0.0

or similar)

If not installed:

Install the Teams CLI using npm:

bash

npm install -g https://github.com/heyitsaamir/teamscli/releases/latest/download/teamscli.tgz

After installation:

Verify: Run
```
teams --version
```
to confirm installation
You should see the version number

Checkpoint: Teams CLI is installed.

校验Teams CLI是否已安装：

bash

teams --version

预期输出： 显示版本号（例如

1.0.0

或类似内容）

如果未安装：

使用npm安装Teams CLI：

bash

npm install -g https://github.com/heyitsaamir/teamscli/releases/latest/download/teamscli.tgz

安装完成后：

校验：执行
```
teams --version
```
确认安装成功
你应该能看到对应的版本号

检查点： Teams CLI已安装完成。

Step 2: Check Authentication

步骤2：检查认证状态

Run the following command to check authentication status:

bash

teams status

Expected output: Shows authenticated user information.

If not authenticated:

Run:
```
teams login
```
Follow the authentication flow
Verify: Run
```
teams status
```
again and confirm you see your authenticated account

Checkpoint: Authentication verified before proceeding.

执行以下命令检查认证状态：

bash

teams status

预期输出： 显示已认证的用户信息。

如果未完成认证：

执行：
```
teams login
```
按照引导完成认证流程
校验：再次执行
```
teams status
```
，确认显示你的已认证账号信息

检查点： 继续操作前已完成认证校验。

Step 3: Verify Bot Endpoint Availability

步骤3：校验机器人端点可用性

Ask the user: "Do you have a bot messaging endpoint URL?"

If YES:

Confirm the endpoint format:
```
https://your-domain/api/messages
```

Common formats:

Devtunnels:

https://your-tunnel.devtunnels.ms/api/messages

ngrok:

https://your-ngrok-id.ngrok.io/api/messages

Azure:

https://your-app.azurewebsites.net/api/messages

Default port for Teams SDK samples:
```
3978
```

If NO:

Recommend Microsoft devtunnels (recommended, Microsoft product)
Link: https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started?tabs=windows
Alternative: ngrok
Out of scope: Setting up the tunnel itself (point user to docs)
User should set up tunnel first, then return to this workflow

Checkpoint: Bot endpoint URL is ready.

询问用户："你是否已经准备好机器人消息端点URL？"

如果有：

确认端点格式：
```
https://your-domain/api/messages
```

常见格式：

Devtunnels：

https://your-tunnel.devtunnels.ms/api/messages

ngrok：

https://your-ngrok-id.ngrok.io/api/messages

Azure：

https://your-app.azurewebsites.net/api/messages

Teams SDK示例的默认端口：
```
3978
```

如果没有：

推荐使用 Microsoft devtunnels（微软官方产品，优先推荐）
链接：https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started?tabs=windows
替代方案：ngrok
超出范围： 隧道本身的配置（引导用户查阅官方文档）
用户需要先完成隧道配置，再回到当前工作流

检查点： 机器人端点URL已准备就绪。

2. Create Teams Bot

2. 创建Teams机器人

Now create the Teams bot with infrastructure.

现在开始创建Teams机器人及相关基础设施。

Step 1: Run Creation Command

步骤1：执行创建命令

Execute the following command (replace placeholders):

bash

teams app create --name "YourBotName" --endpoint "https://your-endpoint/api/messages" --json

Parameters:

```
--name
```
: Your bot's display name (e.g., "Notification Bot", "MyBot")
```
--endpoint
```
: The bot messaging endpoint URL from Step 2
```
--json
```
: Output structured JSON (required for parsing)

Expected: Command completes successfully and returns JSON output.

执行以下命令（替换占位符内容）：

bash

teams app create --name "YourBotName" --endpoint "https://your-endpoint/api/messages" --json

参数说明：

```
--name
```
：机器人的显示名称（例如 "Notification Bot"、"MyBot"）
```
--endpoint
```
：步骤2中获取的机器人消息端点URL
```
--json
```
：输出结构化JSON（解析所需必填参数）

预期结果： 命令执行成功并返回JSON输出。

Step 2: Parse JSON Output

步骤2：解析JSON输出

The command returns JSON with these fields:

json

{
  "appName": "YourBotName",
  "teamsAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "endpoint": "https://your-endpoint/api/messages",
  "installLink": "https://teams.microsoft.com/l/app/...",
  "botLocation": "bf",
  "credentials": {
    "CLIENT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "CLIENT_SECRET": "your-secret-value",
    "TENANT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

命令返回的JSON包含以下字段：

json

{
  "appName": "YourBotName",
  "teamsAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "endpoint": "https://your-endpoint/api/messages",
  "installLink": "https://teams.microsoft.com/l/app/...",
  "botLocation": "bf",
  "credentials": {
    "CLIENT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "CLIENT_SECRET": "your-secret-value",
    "TENANT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Step 3: Display Credentials

步骤3：展示凭证信息

Extract and display the credentials clearly:

CLIENT_ID=<value-from-json>
CLIENT_SECRET=<value-from-json>
TENANT_ID=<value-from-json>

Instruct the user:

"Add these credentials to your .env file. Your bot application code will need these values to authenticate with Microsoft Teams."

Do NOT automatically write to .env file - let the developer decide where to store credentials.

提取并清晰展示凭证信息：

CLIENT_ID=<value-from-json>
CLIENT_SECRET=<value-from-json>
TENANT_ID=<value-from-json>

告知用户：

"将这些凭证添加到你的.env文件中，你的机器人应用代码需要这些值来完成Microsoft Teams的身份认证。"

不要自动写入.env文件 - 让开发者自行决定凭证的存储位置。

Step 4: Display Install Link

步骤4：展示安装链接

Show the install link from the JSON output:

Install your bot in Teams:
<install-link-from-json>

Instruct the user:

"Open this link in your browser to install the bot in Microsoft Teams. You can install it for personal use, in a team, or in a group chat."

Do NOT automatically open the browser - let the user decide when to install.

Checkpoint: Bot created successfully, credentials and install link displayed.

展示JSON输出中的安装链接：

在Teams中安装你的机器人：
<install-link-from-json>

告知用户：

"在浏览器中打开该链接即可在Microsoft Teams中安装机器人，你可以选择个人安装、安装到团队或者群聊中。"

不要自动打开浏览器 - 让用户自行决定安装时机。

检查点： 机器人创建成功，凭证信息与安装链接已展示。

3. Verification

3. 校验

Verify the bot was created successfully.

校验机器人是否创建成功。

Step 1: Verify App Exists

步骤1：校验应用是否存在

Run the following command (use the

teamsAppId

from creation output):

bash

teams app view <teamsAppId> --json

Expected output: Returns app details matching what was created:

```
teamsAppId
```
matches
```
botId
```
matches
```
endpoint
```
matches
App shows as active

If verification fails: Check the error message and refer to Error Recovery section.

Checkpoint: App verified in Teams Developer Portal.

执行以下命令（使用创建输出中的

teamsAppId

）：

bash

teams app view <teamsAppId> --json

预期输出： 返回与创建内容匹配的应用详情：

```
teamsAppId
```
匹配
```
botId
```
匹配
```
endpoint
```
匹配
应用状态为活跃

如果校验失败： 查看错误信息，参考错误恢复章节处理。

检查点： 已在Teams开发者门户中校验应用存在。

4. Common Operations

4. 常用操作

Update Teams CLI

更新Teams CLI

Use case: Update the Teams CLI to the latest version (recommended to stay current with new features and bug fixes)

Command:

bash

teams self-update

When to use:

Periodically update to get latest features
After bug reports or known issues
When new CLI features are announced

Expected: CLI downloads and installs the latest version

使用场景： 将Teams CLI更新到最新版本（建议保持最新版本以获取新功能与Bug修复）

命令：

bash

teams self-update

适用时机：

定期更新以获取最新功能
收到Bug反馈或已知问题后
有新的CLI功能发布时

预期结果： CLI下载并安装最新版本

Update Bot Endpoint

更新机器人端点

Use case: Endpoint URL changed (new ngrok/devtunnels session, redeployment, local → cloud migration)

Command:

bash

teams app edit <appId> --endpoint "https://new-endpoint-url/api/messages"

When to use:

Ngrok URL changed (new session)
Devtunnels URL changed
Deployed bot to cloud (Azure, AWS, etc.)
Switched from local dev to production endpoint

使用场景： 端点URL发生变更（新的ngrok/devtunnels会话、重新部署、本地→云端迁移）

命令：

bash

teams app edit <appId> --endpoint "https://new-endpoint-url/api/messages"

适用时机：

Ngrok URL变更（新会话）
Devtunnels URL变更
机器人部署到云端（Azure、AWS等）
从本地开发端点切换到生产端点

View App Details

查看应用详情

Command:

bash

teams app view <appId> --json

Use case: Check current bot configuration, verify settings

命令：

bash

teams app view <appId> --json

使用场景： 查看当前机器人配置、校验设置

List All Apps

列出所有应用

Command:

bash

teams app list

Use case: See all Teams apps you've created

命令：

bash

teams app list

使用场景： 查看你创建的所有Teams应用

5. Error Recovery

5. 错误恢复

Cannot Install App (Sideloading Disabled)

无法安装应用（旁加载被禁用）

Symptom: Install link shows "Permission denied", "Custom apps are blocked", or similar message

Cause: Tenant administrator has disabled custom app upload (sideloading)

Solution:

Contact your tenant administrator
Request they enable custom app upload
Reference documentation: https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant#enable-custom-teams-apps-and-configure-custom-app-upload-settings

Admin steps: Admin must enable "Allow interaction with custom apps" in Teams admin center.

症状： 安装链接显示"Permission denied"、"Custom apps are blocked"或类似提示

原因： 租户管理员禁用了自定义应用上传（旁加载）功能

解决方案：

联系你的租户管理员
申请启用自定义应用上传权限
参考文档：https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant#enable-custom-teams-apps-and-configure-custom-app-upload-settings

管理员操作步骤： 管理员需要在Teams管理中心启用"允许与自定义应用交互"选项。

AUTH_REQUIRED Error

AUTH_REQUIRED 错误

Symptom: Command fails with "Not logged in", "AUTH_REQUIRED", or "authentication required" message

Cause: Not authenticated or authentication token expired

Solution:

Run:
```
teams login
```
Complete authentication flow
Verify: Run
```
teams status
```
and confirm authenticated
Retry the original command

症状： 命令执行失败，提示"Not logged in"、"AUTH_REQUIRED"或"authentication required"

原因： 未完成认证或认证令牌已过期

解决方案：

执行：
```
teams login
```
完成认证流程
校验：执行
```
teams status
```
确认已认证
重试原命令

AUTH_TOKEN_FAILED Error

AUTH_TOKEN_FAILED 错误

Symptom: Command fails with "Failed to get token" or "AUTH_TOKEN_FAILED" message

Cause: Token acquisition failed (expired, corrupted, or network issue)

Solution:

Run:
```
teams login
```
again to refresh tokens
Verify: Run
```
teams status
```
shows authenticated
Retry the original command

症状： 命令执行失败，提示"Failed to get token"或"AUTH_TOKEN_FAILED"

原因： 令牌获取失败（过期、损坏或网络问题）

解决方案：

重新执行
```
teams login
```
刷新令牌
校验：执行
```
teams status
```
显示已认证
重试原命令

6. Resources

6. 相关资源

Building Bot Application Code

构建机器人应用代码

This skill covers bot infrastructure only. To build the actual bot code:

Teams AI SDK (Recommended):

https://microsoft.github.io/teams-sdk/welcome
Comprehensive bot framework with built-in Teams features
Supports TypeScript, JavaScript, Python, C#

本技能仅覆盖机器人基础设施相关内容，如需构建实际的机器人代码：

Teams AI SDK（推荐）：

https://microsoft.github.io/teams-sdk/welcome
内置Teams特性的全量机器人框架
支持TypeScript、JavaScript、Python、C#

Setting Up Development Tunnels

配置开发隧道

Microsoft devtunnels (Recommended):

https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started?tabs=windows
Microsoft's official tunneling solution
Free for development use

ngrok (Alternative):

https://ngrok.com
Popular tunneling service
Free tier available

Microsoft devtunnels（推荐）：

https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started?tabs=windows
微软官方隧道解决方案
开发场景免费使用

ngrok（替代方案）：

https://ngrok.com
流行的隧道服务
提供免费套餐

Teams App Development Documentation

Teams应用开发文档

General Teams app development:

https://learn.microsoft.com/en-us/microsoftteams/platform/

Bot-specific documentation:

https://learn.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots

Teams应用开发总览：

https://learn.microsoft.com/en-us/microsoftteams/platform/

机器人专属文档：

https://learn.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots

Workflow Summary

工作流总结

1. Prerequisites
   ├─ Install CLI: npm install -g <url>
   ├─ Authenticate: teams login
   └─ Prepare endpoint: https://your-domain/api/messages

2. Create Bot
   └─ teams app create --name X --endpoint Y --json

3. Handle Output
   ├─ Display credentials (CLIENT_ID, CLIENT_SECRET, TENANT_ID)
   ├─ Instruct: Add to .env file
   └─ Display install link

4. Verify
   └─ teams app view <teamsAppId> --json

5. Common Operations
   └─ Update endpoint: teams app edit <appId> --endpoint <new-url>

6. Troubleshoot
   ├─ Sideload disabled → Admin enables custom app upload
   └─ AUTH_REQUIRED → teams login, retry

1. 前置条件
   ├─ 安装CLI：npm install -g <url>
   ├─ 认证：teams login
   └─ 准备端点：https://your-domain/api/messages

2. 创建机器人
   └─ teams app create --name X --endpoint Y --json

3. 处理输出
   ├─ 展示凭证（CLIENT_ID、CLIENT_SECRET、TENANT_ID）
   ├─ 告知：添加到.env文件
   └─ 展示安装链接

4. 校验
   └─ teams app view <teamsAppId> --json

5. 常用操作
   └─ 更新端点：teams app edit <appId> --endpoint <new-url>

6. 问题排查
   ├─ 旁加载禁用 → 管理员启用自定义应用上传
   └─ AUTH_REQUIRED → 执行teams login后重试

Out of Scope

超出范围

This skill does NOT cover:

❌ Building bot application code (see Teams AI SDK)
❌ Hosting or deploying bot code (Azure, AWS, etc.)
❌ Setting up devtunnels/ngrok (link provided to docs)
❌ Bot development patterns and best practices
❌ Teams app manifest customization (uses CLI defaults)

For bot code development, start with: https://microsoft.github.io/teams-sdk/welcome

本技能不涵盖以下内容：

❌ 构建机器人应用代码（参考Teams AI SDK）
❌ 托管或部署机器人代码（Azure、AWS等）
❌ 配置devtunnels/ngrok（已提供文档链接）
❌ 机器人开发模式与最佳实践
❌ Teams应用清单自定义（使用CLI默认配置）

如需进行机器人代码开发，可从这里开始：https://microsoft.github.io/teams-sdk/welcome