Microsoft Teams

概览

Microsoft Teams provider 将你的数字员工集成到 Teams 频道和聊天中。它支持：

频道消息
私人聊天
群聊
Adaptive Cards
交互组件
文件附件

前置条件

Microsoft 365 tenant
支持 device-code OAuth 的 public Microsoft Entra application client id
可授予或同意 setup 所需 Graph scopes 的权限
当你希望 setup 创建缺失的 desired channel 时，需要在所选 Team 中创建 channel 的权限

设置

Teams setup 支持两种配置形式：

模式	使用场景	主要字段
Graph channel 模式	你需要基于 Graph 的频道发送和订阅。这是默认 setup 模式。	`tenant_id`, `client_id`, `team_id`, `team_name`, `channel_id`, `channel_name`, `desired_channel_name`
Bot Framework 模式	你已有用于入站 Bot Framework 消息的 Azure Bot 和 Teams app manifest。	`ms_bot_app_id`, `ms_bot_app_password`, `bot_display_name`, `messaging_endpoint`

配置 setup 提示

你可以只使用默认 public client id 运行 setup，也可以提供自己的 client_id。当你希望 setup 查找或创建特定 standard channel 时，请添加 desired_channel_name：
answers.json
```
{
  "setup_answers": {
    "messaging-teams": {
      "client_id": "6c115a7a-f656-49c4-975a-5e831efae833",
      "desired_channel_name": "hr onboarding"
    }
  }
}
```

启动 Teams setup

gtc setup --answers answers.json ./my-bundle

完成 device-code OAuth

setup 会启动 Microsoft device-code flow。复制代码，打开 verification URL，使用可访问目标 Team 的 Microsoft 365 account 登录，并批准请求的 Graph scopes。

返回 terminal，并在 setup 要求验证 Microsoft Teams setup 时继续。随后 Greentic 会轮询 Microsoft Graph，将 delegated tokens 存为 secrets，并运行登录后的 discovery。
选择或验证 Team 和 channel

setup 调用 Microsoft Graph 列出已登录 user 加入的 teams 和 channels。按提示选择 Team 和 channel，或让 desired_channel_name 引导 create-if-missing flow。

setup 会保存 identifiers 和 labels：
- team_id 和 team_name
- channel_id 和 channel_name
IDs 供 runtime sends 和 subscription setup 使用。display names 供 operators 和 setup UIs 使用。
在 Teams 中检查 channel

打开 Microsoft Teams，进入所选 Team 和 channel。如果 setup 创建了 desired_channel_name，请确认 channel 存在且已登录 account 有权访问。

如果所选 Team 尚无该 channel，setup 可以创建 standard channel，然后保存生成的 channel_id 和 channel_name。ID 仍是 runtime sends 和 subscriptions 的权威值。
启动或重启 runtime
Terminal window
```
gtc start ./my-bundle
```
Teams pack 会声明所需 subscription metadata，包括 Graph resource template、component config fields、notification URL template 和 lifecycle notification URL template。hosts 应使用这些 metadata，而不是硬编码 Teams resource paths。
测试目标 channel

在所选 Teams channel 中发送消息，或触发发送到 Teams 的 flow。如果消息未出现，请重新运行 setup，并检查保存的 team_id 和 channel_id 仍与在 Teams 中打开的 channel 匹配。

配置选项

选项	必需	描述
`client_id`	Graph setup 需要	用于 device-code OAuth 的 public Microsoft application client id
`tenant_id`	已生成	从 Microsoft Graph 发现的 tenant id
`team_id`	已生成或已选择	用于 channel sends 和 subscriptions 的 Teams team id
`team_name`	已生成或已选择	所选 Team 的 display name
`channel_id`	已生成或已选择	用于 sends 和 subscriptions 的 channel id
`channel_name`	已生成或已选择	所选 channel 的 display name
`desired_channel_name`	否	默认/搜索提示；支持创建时也作为 channel creation name
`chat_id`	否	适用时用于 chat subscriptions 的 chat id
`ms_bot_app_id`	Bot Framework 模式	Microsoft Bot Framework app id
`ms_bot_app_password`	Bot Framework 模式	Bot Framework app password
`bot_display_name`	Bot Framework 模式	Teams app manifest workflows 中使用的 display name
`messaging_endpoint`	Bot Framework 模式	public Bot Framework messaging endpoint

功能

文本消息

- id: reply
  type: reply
  config:
    message: "Hello! How can I help you today?"

Markdown 格式

Teams 支持部分 Markdown：

- id: formatted
  type: reply
  config:
    message: |
      **Bold** *Italic*
      - Bullet 1
      - Bullet 2
      [Link](https://example.com)

Adaptive Cards

Teams 通过 Bot Framework attachments 原生支持 Adaptive Card。请使用目标 Teams 客户端和操作模型支持的版本；Universal Actions 等 Adaptive Cards 1.4 功能仅适用于受支持的机器人场景。

- id: send_card
  type: adaptive-card
  config:
    card:
      type: AdaptiveCard
      version: "1.4"
      body:
        - type: TextBlock
          text: "Welcome!"
          size: Large
          weight: Bolder
        - type: TextBlock
          text: "How can I assist you today?"
        - type: ActionSet
          actions:
            - type: Action.Submit
              title: "Get Help"
              data:
                action: "help"
            - type: Action.Submit
              title: "Create Ticket"
              data:
                action: "ticket"

Hero Cards

- id: hero_card
  type: reply
  config:
    hero_card:
      title: "Support Bot"
      subtitle: "Your AI Assistant"
      text: "I can help with technical issues, billing questions, and more."
      images:
        - url: "https://example.com/bot-image.png"
      buttons:
        - type: messageBack
          title: "Get Started"
          text: "get started"
          displayText: "Getting started..."

建议操作（Quick Replies）

- id: suggestions
  type: reply
  config:
    message: "What would you like to do?"
    suggested_actions:
      - title: "Check Status"
        value: "status"
      - title: "Create Ticket"
        value: "ticket"
      - title: "Contact Human"
        value: "human"

文件附件

- id: send_file
  type: reply
  config:
    message: "Here's your report"
    attachments:
      - contentType: "application/pdf"
        contentUrl: "https://example.com/report.pdf"
        name: "report.pdf"

处理 Card Actions

name: handle_card_action
version: "1.0"

nodes:
  - id: route_action
    type: branch
    config:
      conditions:
        - expression: "data.action == 'help'"
          to: show_help
        - expression: "data.action == 'ticket'"
          to: create_ticket
      default: unknown_action

  - id: show_help
    type: reply
    config:
      message: "Here's how I can help..."

triggers:
  - type: invoke
    name: "adaptiveCard/action"
    target: route_action

频道配置

团队频道

tenants:
  demo:
    teams:
      support:
        channels:
          teams:
            provider: messaging-teams
            config:
              team_id: "19:xxx@thread.tacv2"
              channel_id: "19:yyy@thread.tacv2"

私人聊天

对于 1:1 私人聊天，不需要额外的频道配置。谁给 bot 发消息，bot 就回复谁。

主动消息

无需用户先发起也可以发送消息：

- id: proactive
  type: reply
  config:
    message: "Reminder: Your ticket #123 needs attention"
    conversation_reference:
      conversation_id: "{{stored_conversation_id}}"
      service_url: "{{stored_service_url}}"

故障排查

Bot 无响应

在 Azure Bot Service 中检查 endpoint 配置
确认 SSL 证书有效
检查 app 凭证是否正确
在 Azure 中查看 activity logs

`Unauthorized` 错误

确认 App ID 和 Password
检查单租户 app 的 tenant ID
确保 bot 已在 Teams channel 中启用

Card 未渲染

使用 Adaptive Cards Designer 校验 card JSON
检查 Teams 是否支持该 card 版本
确认所有必填字段都已提供

消息延迟

Teams 可能会批量处理消息；这是正常现象
检查你的服务器性能
确认没有触发速率限制

安全

Greentic 会自动校验：

JWT 签名
Issuer 和 audience claims
Token 过期时间

下一步

Adaptive Cards Designer - 可视化设计卡片
Slack Provider - 添加 Slack 集成
WebChat Provider - 嵌入到网站中