Microsoft Teams

概要

Microsoft Teams provider は digital worker を Teams の channel と chat に統合します。次をサポートします:

channel message
personal chat
group chat
Adaptive Cards
interactive component
file attachment

前提条件

Microsoft 365 tenant
device-code OAuth をサポートする public Microsoft Entra application client id
setup が使う Graph scopes を付与または同意できる権限
setup に不足している desired channel を作成させる場合、選択した Team で channel を作成できる権限

セットアップ

Teams setup では 2 つの設定形式がサポートされています:

Mode	使用する場合	主なフィールド
Graph channel mode	Graph ベースの channel sends と subscriptions を使う場合。これはデフォルトの setup mode です。	`tenant_id`, `client_id`, `team_id`, `team_name`, `channel_id`, `channel_name`, `desired_channel_name`
Bot Framework mode	inbound Bot Framework messages 用の 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 を指定できます。特定の standard channel を setup に検索または作成させたい場合は、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 の authoritative value のままです。
runtime を開始または再起動する
Terminal window
```
gtc start ./my-bundle
```
Teams pack は、Graph resource template、component config fields、notification URL template、lifecycle notification URL template を含む desired subscription metadata を宣言します。hosts は Teams resource paths を hard-code せず、この metadata を使用する必要があります。
対象 channel をテストする

選択した Teams channel に message を送るか、Teams に送信する flow をトリガーします。messages が表示されない場合は 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`	いいえ	default/search hint、および作成がサポートされる場合の channel creation name
`chat_id`	いいえ	該当する場合の chat subscriptions 用 chat id
`ms_bot_app_id`	Bot Framework mode	Microsoft Bot Framework app id
`ms_bot_app_password`	Bot Framework mode	Bot Framework app password
`bot_display_name`	Bot Framework mode	Teams app manifest workflows で使う display name
`messaging_endpoint`	Bot Framework mode	public Bot Framework messaging endpoint

機能

テキストメッセージ

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

Markdown Formatting

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 client と action model がサポートするバージョンを使用してください。Universal Actions などの Adaptive Cards 1.4 機能は、サポート対象の bot シナリオに固有です。

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

Suggestions（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"

File Attachments

- 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 Action の処理

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

Channel 設定

Team Channel

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

Personal Chat

個人の 1:1 chat では channel 設定は不要です。bot はメッセージを送った相手に応答します。

Proactive Messaging

user からの開始を待たずにメッセージを送信します:

- 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 certificate が有効であることを確認する
app credentials が正しいことを確認する
Azure の activity log を確認する

”Unauthorized” Error

App ID と Password を確認する
single-tenant app の場合は tenant ID を確認する
bot が Teams channel で有効になっていることを確認する

Card が表示されない

Adaptive Cards Designer で card JSON を検証する
Teams がその card version をサポートしていることを確認する
必須 field がすべて存在することを確認する

メッセージが遅延する

Teams では message がまとめて配送されることがあり、これは正常です
server の performance を確認する
rate limit が発生していないことを確認する

セキュリティ

Greentic は次を自動検証します:

JWT signature
issuer と audience claim
token expiration

次のステップ

Adaptive Cards Designer - card を視覚的に設計する
Slack Provider - Slack integration を追加する
WebChat Provider - website に埋め込む