Microsoft Teams

Ringkasan

Provider Microsoft Teams mengintegrasikan digital worker Anda dengan channel dan chat Teams. Provider ini mendukung:

• Pesan channel
• Chat pribadi
• Chat grup
• Adaptive Cards
• Komponen interaktif
• Lampiran file

Prasyarat

• Tenant Microsoft 365
• Public Microsoft Entra application client id yang mendukung OAuth device-code
• Izin untuk memberikan atau menyetujui scope Graph yang digunakan setup
• Izin untuk membuat channel di Team yang dipilih jika setup perlu membuat desired channel yang belum ada

Penyiapan

Setup Teams memiliki dua bentuk konfigurasi yang didukung:

Mode	Gunakan saat	Field utama
Mode channel Graph	Anda ingin pengiriman channel dan subscription berbasis Graph. Ini adalah mode setup default.	tenant_id, client_id, team_id, team_name, channel_id, channel_name, desired_channel_name
Mode Bot Framework	Anda memiliki Azure Bot dan manifest app Teams untuk pesan masuk Bot Framework.	ms_bot_app_id, ms_bot_app_password, bot_display_name, messaging_endpoint

1. Konfigurasikan petunjuk setup

   Anda dapat menjalankan setup hanya dengan client id publik default, atau menyediakan client_id sendiri. Tambahkan desired_channel_name jika Anda ingin setup menemukan atau membuat channel standar tertentu:

   answers.json

   {
     "setup_answers": {
       "messaging-teams": {
         "client_id": "6c115a7a-f656-49c4-975a-5e831efae833",
         "desired_channel_name": "hr onboarding"
       }
     }
   }

2. Mulai setup Teams

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

3. Selesaikan OAuth device-code

   Setup memulai flow Microsoft device-code. Salin kode, buka URL verifikasi, masuk dengan akun Microsoft 365 yang dapat mengakses Team target, lalu setujui scope Graph yang diminta.

   Kembali ke terminal dan lanjutkan saat setup meminta Anda memverifikasi setup Microsoft Teams. Greentic kemudian melakukan polling Microsoft Graph, menyimpan delegated tokens sebagai secret, dan menjalankan discovery setelah login.

4. Pilih atau verifikasi Team dan channel

   Setup memanggil Microsoft Graph untuk menampilkan joined teams dan channels milik user yang masuk. Pilih Team dan channel saat diminta, atau biarkan desired_channel_name mengarahkan flow create-if-missing.

   Setup menyimpan identifier dan label:

   • team_id dan team_name
   • channel_id dan channel_name

   ID digunakan oleh pengiriman runtime dan setup subscription. Display name digunakan untuk operator dan UI setup.

5. Periksa channel di Teams

   Buka Microsoft Teams dan masuk ke Team serta channel yang dipilih. Jika setup membuat desired_channel_name, pastikan channel ada dan akun yang masuk memiliki akses.

   Jika Team yang dipilih belum memiliki channel itu, setup dapat membuat channel standar lalu menyimpan channel_id dan channel_name yang dihasilkan. ID tetap menjadi acuan untuk pengiriman runtime dan subscription.

6. Mulai atau restart runtime

   gtc start ./my-bundle

   Pack Teams mendeklarasikan metadata subscription yang diinginkan, termasuk template resource Graph, field config komponen, template URL notifikasi, dan template URL notifikasi lifecycle. Host harus menggunakan metadata ini alih-alih hard-coding path resource Teams.

7. Uji channel target

   Kirim pesan di channel Teams yang dipilih atau picu flow yang mengirim ke Teams. Jika pesan tidak muncul, jalankan setup lagi dan periksa bahwa team_id dan channel_id yang tersimpan masih cocok dengan channel yang Anda buka di Teams.

Opsi Konfigurasi

Opsi	Wajib	Deskripsi
client_id	Ya untuk setup Graph	Public Microsoft application client id yang digunakan untuk OAuth device-code
tenant_id	Dibuat	Tenant id yang ditemukan dari Microsoft Graph
team_id	Dibuat atau dipilih	Teams team id yang digunakan untuk pengiriman channel dan subscription
team_name	Dibuat atau dipilih	Display name untuk Team yang dipilih
channel_id	Dibuat atau dipilih	Channel id yang digunakan untuk pengiriman dan subscription
channel_name	Dibuat atau dipilih	Display name untuk channel yang dipilih
desired_channel_name	Tidak	Petunjuk default/pencarian, dan nama pembuatan channel saat pembuatan didukung
chat_id	Tidak	Chat id untuk subscription chat jika berlaku
ms_bot_app_id	Mode Bot Framework	Microsoft Bot Framework app id
ms_bot_app_password	Mode Bot Framework	Bot Framework app password
bot_display_name	Mode Bot Framework	Display name yang digunakan dalam workflow manifest app Teams
messaging_endpoint	Mode Bot Framework	Endpoint messaging Bot Framework publik

Catatan

Egress Teams dan setup subscription menggunakan ID, bukan display name. Label disimpan untuk operator dan UI setup, tetapi channel_id, team_id, atau chat_id tetap menjadi identifier runtime.

Perhatian

Membuat channel Teams yang belum ada memerlukan delegated Graph permission Channel.Create dan user yang masuk yang diizinkan membuat channel di Team yang dipilih.

Fitur

Pesan Teks

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

Pemformatan Markdown

Teams mendukung subset Markdown:

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

Adaptive Cards

Teams memiliki dukungan Adaptive Card native melalui attachment Bot Framework. Gunakan versi yang didukung oleh client Teams target dan model action Anda; fitur Adaptive Cards 1.4 seperti Universal Actions hanya berlaku untuk skenario bot yang didukung.

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

Saran (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"

Lampiran File

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

Menangani Aksi Card

flows/on_card_action.ygtc

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

Konfigurasi Channel

Team Channel

greentic.demo.yaml

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

Chat Pribadi

Untuk chat pribadi 1:1, tidak diperlukan konfigurasi channel. Bot akan merespons siapa pun yang mengirim pesan kepadanya.

Pesan Proaktif

Kirim pesan tanpa inisiasi pengguna:

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

Catatan

Simpan conversation reference saat pengguna pertama kali berinteraksi dengan bot Anda untuk mengaktifkan pesan proaktif nanti.

Troubleshooting

Bot Tidak Merespons

1. Periksa konfigurasi endpoint di Azure Bot Service
2. Verifikasi sertifikat SSL valid
3. Periksa kredensial app sudah benar
4. Tinjau activity logs di Azure

Error “Unauthorized”

• Verifikasi App ID dan Password
• Periksa tenant ID untuk app single-tenant
• Pastikan bot diaktifkan di Teams channel

Card Tidak Muncul

• Validasi JSON card dengan Adaptive Cards Designer
• Periksa apakah Teams mendukung versi card tersebut
• Verifikasi semua field wajib tersedia

Pesan Terlambat

• Teams dapat mengelompokkan pesan; ini normal
• Periksa performa server Anda
• Verifikasi tidak ada rate limiting

Keamanan

Perhatian

Selalu validasi token autentikasi Bot Framework pada request masuk untuk memastikan request tersebut berasal dari Microsoft.

Greentic secara otomatis memvalidasi:

• Tanda tangan JWT
• Klaim issuer dan audience
• Kedaluwarsa token

Langkah Selanjutnya

• Adaptive Cards Designer - Rancang card secara visual
• Provider Slack - Tambahkan integrasi Slack
• Provider WebChat - Sematkan di website