Microsoft Teams

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Plugin đi kèm

openclaw plugins install @openclaw/msteams

openclaw plugins install ./path/to/local/msteams-plugin

​

Thiết lập nhanh

npm install -g @microsoft/teams.cli@preview
teams login
teams status   # verify you're logged in and see your tenant info

# One-time setup (persistent URL across sessions):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot
# Your endpoint: https://<tunnel-id>.devtunnels.ms/api/messages

teams app create \
  --name "OpenClaw" \
  --endpoint "https://<your-tunnel-url>/api/messages"

• Tạo một ứng dụng Entra ID (Azure AD)
• Tạo một client secret
• Xây dựng và tải lên manifest ứng dụng Teams (kèm biểu tượng)
• Đăng ký bot (mặc định do Teams quản lý - không cần gói đăng ký Azure)

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<CLIENT_ID>",
      appPassword: "<CLIENT_SECRET>",
      tenantId: "<TENANT_ID>",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

teams app get <teamsAppId> --install-link

teams app doctor <teamsAppId>

​

Mục tiêu

• Trò chuyện với OpenClaw qua DM Teams, cuộc trò chuyện nhóm hoặc kênh.
• Giữ định tuyến xác định: câu trả lời luôn quay lại kênh mà chúng đến từ đó.
• Mặc định dùng hành vi kênh an toàn (yêu cầu nhắc đến trừ khi được cấu hình khác).

​

Ghi cấu hình

{
  channels: { msteams: { configWrites: false } },
}

​

Kiểm soát truy cập (DM + nhóm)

• Mặc định: channels.msteams.dmPolicy = "pairing". Người gửi không xác định sẽ bị bỏ qua cho đến khi được phê duyệt.
• channels.msteams.allowFrom nên dùng AAD object ID ổn định hoặc nhóm truy cập người gửi tĩnh như accessGroup:core-team.
• Không dựa vào khớp UPN/tên hiển thị cho allowlist - chúng có thể thay đổi. OpenClaw tắt khớp tên trực tiếp theo mặc định; bật rõ ràng bằng channels.msteams.dangerouslyAllowNameMatching: true.
• Trình hướng dẫn có thể phân giải tên thành ID qua Microsoft Graph khi thông tin xác thực cho phép.

• Mặc định: channels.msteams.groupPolicy = "allowlist" (bị chặn trừ khi bạn thêm groupAllowFrom). Dùng channels.defaults.groupPolicy để ghi đè mặc định khi chưa đặt.
• channels.msteams.groupAllowFrom kiểm soát người gửi hoặc nhóm truy cập người gửi tĩnh nào có thể kích hoạt trong cuộc trò chuyện nhóm/kênh (fallback về channels.msteams.allowFrom).
• Đặt groupPolicy: "open" để cho phép mọi thành viên (mặc định vẫn có cổng kiểm soát bằng nhắc đến).
• Để không cho phép kênh nào, đặt channels.msteams.groupPolicy: "disabled".

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["00000000-0000-0000-0000-000000000000", "accessGroup:core-team"],
    },
  },
}

• Giới hạn phạm vi trả lời nhóm/kênh bằng cách liệt kê team và kênh dưới channels.msteams.teams.
• Khóa nên dùng Teams conversation ID ổn định từ liên kết Teams, không dùng tên hiển thị có thể thay đổi.
• Khi groupPolicy="allowlist" và có allowlist team, chỉ team/kênh được liệt kê mới được chấp nhận (có cổng kiểm soát bằng nhắc đến).
• Trình hướng dẫn cấu hình chấp nhận mục Team/Channel và lưu chúng cho bạn.
• Khi khởi động, OpenClaw phân giải tên allowlist team/kênh và người dùng thành ID (khi quyền Graph cho phép) và ghi log ánh xạ; tên team/kênh chưa phân giải được giữ nguyên như đã nhập nhưng mặc định bị bỏ qua khi định tuyến trừ khi bật channels.msteams.dangerouslyAllowNameMatching: true.

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      teams: {
        "My Team": {
          channels: {
            General: { requireMention: true },
          },
        },
      },
    },
  },
}

​

Xác thực liên kết (chứng chỉ cộng với managed identity)

Đã thêm trong 2026.4.11

​

Tùy chọn A: Xác thực dựa trên chứng chỉ

1. Tạo hoặc lấy chứng chỉ (định dạng PEM với khóa riêng).
2. Trong Entra ID → App Registration → Certificates & secrets → Certificates → Tải lên chứng chỉ công khai.

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      certificatePath: "/path/to/cert.pem",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem

​

Tùy chọn B: Azure Managed Identity

1. Pod/VM của bot có managed identity (system-assigned hoặc user-assigned).
2. Một federated identity credential liên kết managed identity với app registration Entra ID.
3. Khi chạy, OpenClaw dùng @azure/identity để lấy token từ endpoint Azure IMDS (169.254.169.254).
4. Token được chuyển cho Teams SDK để xác thực bot.

• Hạ tầng Azure có bật managed identity (AKS workload identity, App Service, VM)
• Federated identity credential được tạo trên app registration Entra ID
• Quyền truy cập mạng tới IMDS (169.254.169.254:80) từ pod/VM

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      useManagedIdentity: true,
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      useManagedIdentity: true,
      managedIdentityClientId: "<MI_CLIENT_ID>",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id> (chỉ dành cho loại do người dùng gán)

​

Thiết lập danh tính khối lượng công việc AKS

1. Bật danh tính khối lượng công việc trên cụm AKS của bạn.
2. Tạo thông tin xác thực danh tính liên kết trên đăng ký ứng dụng Entra ID:
   az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{
     "name": "my-bot-workload-identity",
     "issuer": "<AKS_OIDC_ISSUER_URL>",
     "subject": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>",
     "audiences": ["api://AzureADTokenExchange"]
   }'
   
3. Chú thích tài khoản dịch vụ Kubernetes bằng ID máy khách của ứng dụng:
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-bot-sa
     annotations:
       azure.workload.identity/client-id: "<APP_CLIENT_ID>"
   
4. Gắn nhãn pod để chèn danh tính khối lượng công việc:
   metadata:
     labels:
       azure.workload.identity/use: "true"
   
5. Đảm bảo quyền truy cập mạng tới IMDS (169.254.169.254) - nếu dùng NetworkPolicy, hãy thêm quy tắc egress cho phép lưu lượng tới 169.254.169.254/32 trên cổng 80.

​

So sánh loại xác thực

​

Phát triển cục bộ (đường hầm)

# One-time setup:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot

teams app update <teamsAppId> --endpoint "https://<new-url>/api/messages"

​

Kiểm thử bot

teams app doctor <teamsAppId>

1. Cài đặt ứng dụng Teams (dùng liên kết cài đặt từ teams app get <id> --install-link)
2. Tìm bot trong Teams và gửi DM
3. Kiểm tra nhật ký Gateway để xem hoạt động gửi đến

​

Biến môi trường

• MSTEAMS_APP_ID
• MSTEAMS_APP_PASSWORD
• MSTEAMS_TENANT_ID
• MSTEAMS_AUTH_TYPE (tùy chọn: "secret" hoặc "federated")
• MSTEAMS_CERTIFICATE_PATH (liên kết + chứng chỉ)
• MSTEAMS_CERTIFICATE_THUMBPRINT (tùy chọn, không bắt buộc cho xác thực)
• MSTEAMS_USE_MANAGED_IDENTITY (liên kết + danh tính được quản lý)
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID (chỉ MI do người dùng gán)

​

Hành động thông tin thành viên

• Quyền RSC Member.Read.Group (đã có trong manifest được khuyến nghị)
• Đối với tra cứu giữa các nhóm: quyền Ứng dụng Graph User.Read.All với sự chấp thuận của quản trị viên

​

Ngữ cảnh lịch sử

• channels.msteams.historyLimit kiểm soát số lượng tin nhắn kênh/nhóm gần đây được đưa vào prompt.
• Quay lui về messages.groupChat.historyLimit. Đặt 0 để tắt (mặc định 50).
• Lịch sử luồng được lấy sẽ được lọc theo danh sách cho phép của người gửi (allowFrom / groupAllowFrom), nên việc gieo ngữ cảnh luồng chỉ bao gồm tin nhắn từ người gửi được phép.
• Ngữ cảnh tệp đính kèm được trích dẫn (ReplyTo* bắt nguồn từ HTML trả lời của Teams) hiện được truyền nguyên như nhận được.
• Nói cách khác, danh sách cho phép kiểm soát ai có thể kích hoạt agent; hiện nay chỉ có các đường dẫn ngữ cảnh bổ sung cụ thể được lọc.
• Lịch sử DM có thể được giới hạn bằng channels.msteams.dmHistoryLimit (lượt người dùng). Ghi đè theo người dùng: channels.msteams.dms["<user_id>"].historyLimit.

​

Quyền RSC hiện tại của Teams (manifest)

• ChannelMessage.Read.Group (Ứng dụng) - nhận tất cả tin nhắn kênh mà không cần @mention
• ChannelMessage.Send.Group (Ứng dụng)
• Member.Read.Group (Ứng dụng)
• Owner.Read.Group (Ứng dụng)
• ChannelSettings.Read.Group (Ứng dụng)
• TeamMember.Read.Group (Ứng dụng)
• TeamSettings.Read.Group (Ứng dụng)

• ChatMessage.Read.Chat (Ứng dụng) - nhận tất cả tin nhắn trò chuyện nhóm mà không cần @mention

teams app rsc add <teamsAppId> ChannelMessage.Read.Group --type Application

​

Ví dụ manifest Teams (đã lược bỏ thông tin nhạy cảm)

{
  $schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",
  manifestVersion: "1.23",
  version: "1.0.0",
  id: "00000000-0000-0000-0000-000000000000",
  name: { short: "OpenClaw" },
  developer: {
    name: "Your Org",
    websiteUrl: "https://example.com",
    privacyUrl: "https://example.com/privacy",
    termsOfUseUrl: "https://example.com/terms",
  },
  description: { short: "OpenClaw in Teams", full: "OpenClaw in Teams" },
  icons: { outline: "outline.png", color: "color.png" },
  accentColor: "#5B6DEF",
  bots: [
    {
      botId: "11111111-1111-1111-1111-111111111111",
      scopes: ["personal", "team", "groupChat"],
      isNotificationOnly: false,
      supportsCalling: false,
      supportsVideo: false,
      supportsFiles: true,
    },
  ],
  webApplicationInfo: {
    id: "11111111-1111-1111-1111-111111111111",
  },
  authorization: {
    permissions: {
      resourceSpecific: [
        { name: "ChannelMessage.Read.Group", type: "Application" },
        { name: "ChannelMessage.Send.Group", type: "Application" },
        { name: "Member.Read.Group", type: "Application" },
        { name: "Owner.Read.Group", type: "Application" },
        { name: "ChannelSettings.Read.Group", type: "Application" },
        { name: "TeamMember.Read.Group", type: "Application" },
        { name: "TeamSettings.Read.Group", type: "Application" },
        { name: "ChatMessage.Read.Chat", type: "Application" },
      ],
    },
  },
}

​

Lưu ý về manifest (các trường bắt buộc)

• bots[].botId phải khớp với ID ứng dụng Azure Bot.
• webApplicationInfo.id phải khớp với ID ứng dụng Azure Bot.
• bots[].scopes phải bao gồm các bề mặt bạn định sử dụng (personal, team, groupChat).
• bots[].supportsFiles: true là bắt buộc để xử lý tệp trong phạm vi cá nhân.
• authorization.permissions.resourceSpecific phải bao gồm đọc/gửi kênh nếu bạn muốn lưu lượng kênh.

​

Cập nhật ứng dụng hiện có

# Download, edit, and re-upload the manifest
teams app manifest download <teamsAppId> manifest.json
# Edit manifest.json locally...
teams app manifest upload manifest.json <teamsAppId>
# Version is auto-bumped if content changed

​

Khả năng: chỉ RSC so với Graph

​

Với chỉ Teams RSC (ứng dụng đã cài đặt, không có quyền Graph API)

• Đọc nội dung văn bản của tin nhắn kênh.
• Gửi nội dung văn bản của tin nhắn kênh.
• Nhận tệp đính kèm trong cá nhân (DM).

• Nội dung hình ảnh hoặc tệp của kênh/nhóm (payload chỉ bao gồm stub HTML).
• Tải xuống tệp đính kèm được lưu trong SharePoint/OneDrive.
• Đọc lịch sử tin nhắn (ngoài sự kiện Webhook trực tiếp).

​

Với Teams RSC + quyền Ứng dụng Microsoft Graph

• Tải xuống nội dung được lưu trữ (hình ảnh được dán vào tin nhắn).
• Tải xuống tệp đính kèm được lưu trong SharePoint/OneDrive.
• Đọc lịch sử tin nhắn kênh/trò chuyện qua Graph.

​

RSC so với Graph API

​

Phương tiện + lịch sử có Graph (bắt buộc cho kênh)

1. Trong Đăng ký ứng dụng Entra ID (Azure AD), thêm quyền Ứng dụng Microsoft Graph:
   • ChannelMessage.Read.All (tệp đính kèm kênh + lịch sử)
   • Chat.Read.All hoặc ChatMessage.Read.All (trò chuyện nhóm)
2. Cấp sự chấp thuận của quản trị viên cho tenant.
3. Tăng phiên bản manifest của ứng dụng Teams, tải lên lại và cài đặt lại ứng dụng trong Teams.
4. Thoát hoàn toàn rồi mở lại Teams để xóa siêu dữ liệu ứng dụng được lưu trong bộ nhớ đệm.

​

Hạn chế đã biết

​

Hết thời gian chờ Webhook

• Gateway hết thời gian chờ
• Teams thử gửi lại tin nhắn (gây trùng lặp)
• Phản hồi bị bỏ

​

Định dạng

• Định dạng cơ bản hoạt động: in đậm, in nghiêng, code, liên kết
• Markdown phức tạp (bảng, danh sách lồng nhau) có thể không hiển thị đúng
• Adaptive Cards được hỗ trợ cho thăm dò ý kiến và các lượt gửi trình bày ngữ nghĩa (xem bên dưới)

​

Cấu hình

• channels.msteams.enabled: bật/tắt kênh.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: thông tin xác thực bot.
• channels.msteams.webhook.port (mặc định 3978)
• channels.msteams.webhook.path (mặc định /api/messages)
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (mặc định: pairing)
• channels.msteams.allowFrom: danh sách cho phép DM (khuyến nghị dùng ID đối tượng AAD). Trình hướng dẫn sẽ phân giải tên thành ID trong quá trình thiết lập khi có quyền truy cập Graph.
• channels.msteams.dangerouslyAllowNameMatching: công tắc phá kính để bật lại việc khớp UPN/tên hiển thị có thể thay đổi và định tuyến trực tiếp theo tên nhóm/kênh.
• channels.msteams.textChunkLimit: kích thước đoạn văn bản gửi đi.
• channels.msteams.chunkMode: length (mặc định) hoặc newline để tách theo dòng trống (ranh giới đoạn văn) trước khi tách theo độ dài.
• channels.msteams.mediaAllowHosts: danh sách cho phép đối với máy chủ tệp đính kèm đến (mặc định là các miền Microsoft/Teams).
• channels.msteams.mediaAuthAllowHosts: danh sách cho phép để đính kèm header Authorization khi thử lại media (mặc định là các máy chủ Graph + Bot Framework).
• channels.msteams.requireMention: yêu cầu @mention trong kênh/nhóm (mặc định là true).
• channels.msteams.replyStyle: thread | top-level (xem Kiểu trả lời).
• channels.msteams.teams.<teamId>.replyStyle: ghi đè theo từng nhóm.
• channels.msteams.teams.<teamId>.requireMention: ghi đè theo từng nhóm.
• channels.msteams.teams.<teamId>.tools: các ghi đè chính sách công cụ mặc định theo từng nhóm (allow/deny/alsoAllow) được dùng khi thiếu ghi đè theo kênh.
• channels.msteams.teams.<teamId>.toolsBySender: các ghi đè chính sách công cụ mặc định theo từng nhóm, theo từng người gửi (hỗ trợ ký tự đại diện "*").
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: ghi đè theo từng kênh.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: ghi đè theo từng kênh.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: các ghi đè chính sách công cụ theo từng kênh (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: các ghi đè chính sách công cụ theo từng kênh, theo từng người gửi (hỗ trợ ký tự đại diện "*").
• Khóa toolsBySender nên dùng tiền tố rõ ràng: channel:, id:, e164:, username:, name: (các khóa cũ không có tiền tố vẫn chỉ ánh xạ tới id:).
• channels.msteams.actions.memberInfo: bật hoặc tắt hành động thông tin thành viên được hỗ trợ bởi Graph (mặc định: bật khi có thông tin xác thực Graph).
• channels.msteams.authType: loại xác thực - "secret" (mặc định) hoặc "federated".
• channels.msteams.certificatePath: đường dẫn tới tệp chứng chỉ PEM (xác thực liên kết + chứng chỉ).
• channels.msteams.certificateThumbprint: dấu vân tay chứng chỉ (tùy chọn, không bắt buộc để xác thực).
• channels.msteams.useManagedIdentity: bật xác thực managed identity (chế độ liên kết).
• channels.msteams.managedIdentityClientId: ID máy khách cho managed identity do người dùng gán.
• channels.msteams.sharePointSiteId: ID site SharePoint để tải tệp lên trong chat nhóm/kênh (xem Gửi tệp trong chat nhóm).

​

Định tuyến và phiên

• Khóa phiên tuân theo định dạng agent tiêu chuẩn (xem /concepts/session):
  • Tin nhắn trực tiếp dùng chung phiên chính (agent:<agentId>:<mainKey>).
  • Tin nhắn kênh/nhóm dùng conversation id:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Kiểu trả lời: luồng so với bài đăng

• thread trong kênh kiểu Luồng → trả lời xuất hiện lồng nhau một cách gượng ép
• top-level trong kênh kiểu Bài đăng → trả lời xuất hiện thành các bài đăng cấp cao nhất riêng biệt thay vì trong luồng

{
  channels: {
    msteams: {
      replyStyle: "thread",
      teams: {
        "19:abc...@thread.tacv2": {
          channels: {
            "19:xyz...@thread.tacv2": {
              replyStyle: "top-level",
            },
          },
        },
      },
    },
  },
}

​

Thứ tự ưu tiên phân giải

1. Theo từng kênh — channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. Theo từng nhóm — channels.msteams.teams.<teamId>.replyStyle
3. Toàn cục — channels.msteams.replyStyle
4. Mặc định ngầm định — suy ra từ requireMention:
   • requireMention: true → thread
   • requireMention: false → top-level

​

Bảo toàn ngữ cảnh luồng

​

Tệp đính kèm và hình ảnh

• DM: Hình ảnh và tệp đính kèm hoạt động qua Teams bot file APIs.
• Kênh/nhóm: Tệp đính kèm nằm trong bộ nhớ M365 (SharePoint/OneDrive). Payload Webhook chỉ bao gồm một HTML stub, không phải byte tệp thực tế. Cần quyền Graph API để tải xuống tệp đính kèm trong kênh.
• Với các lượt gửi rõ ràng ưu tiên tệp, dùng action=upload-file với media / filePath / path; message tùy chọn trở thành văn bản/bình luận đi kèm, và filename ghi đè tên đã tải lên.

​

Gửi tệp trong chat nhóm

​

Vì sao chat nhóm cần SharePoint

​

Thiết lập

1. Thêm quyền Graph API trong Entra ID (Azure AD) → App Registration:
   • Sites.ReadWrite.All (Application) - tải tệp lên SharePoint
   • Chat.Read.All (Application) - tùy chọn, bật liên kết chia sẻ theo từng người dùng
2. Cấp sự đồng ý của quản trị viên cho tenant.
3. Lấy ID site SharePoint của bạn:
   # Via Graph Explorer or curl with a valid token:
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
   
   # Example: for a site at "contoso.sharepoint.com/sites/BotFiles"
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
   
   # Response includes: "id": "contoso.sharepoint.com,guid1,guid2"
   
4. Cấu hình OpenClaw:
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Hành vi chia sẻ

​

Hành vi dự phòng

​

Vị trí lưu trữ tệp

​

Thăm dò ý kiến (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> ...
• Phiếu bầu được Gateway ghi lại trong ~/.openclaw/msteams-polls.json.
• Gateway phải duy trì trực tuyến để ghi lại phiếu bầu.
• Hiện các cuộc thăm dò chưa tự động đăng tóm tắt kết quả (kiểm tra tệp lưu trữ nếu cần).

​

Thẻ trình bày

{
  action: "send",
  channel: "msteams",
  target: "user:<id>",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello!" }],
  },
}

openclaw message send --channel msteams \
  --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello!"}]}'

​

Định dạng đích

# Send to a user by ID
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"

# Send to a user by display name (triggers Graph API lookup)
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"

# Send to a group chat or channel
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"

# Send a presentation card to a conversation
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}'

{
  action: "send",
  channel: "msteams",
  target: "user:John Smith",
  message: "Hello!",
}

{
  action: "send",
  channel: "msteams",
  target: "conversation:19:abc...@thread.tacv2",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello" }],
  },
}

​

Nhắn tin chủ động

• Tin nhắn chủ động chỉ có thể thực hiện sau khi người dùng đã tương tác, vì tại thời điểm đó chúng tôi lưu trữ tham chiếu cuộc trò chuyện.
• Xem /gateway/configuration để biết dmPolicy và kiểm soát bằng danh sách cho phép.

​

ID Team và Channel (lỗi thường gặp)

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    Team conversation ID (URL-decode this)

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      Channel ID (URL-decode this)

• Khóa team = đoạn đường dẫn sau /team/ (đã giải mã URL, ví dụ 19:Bk4j...@thread.tacv2; các tenant cũ hơn có thể hiển thị @thread.skype, cũng hợp lệ)
• Khóa channel = đoạn đường dẫn sau /channel/ (đã giải mã URL)
• Bỏ qua tham số truy vấn groupId cho định tuyến OpenClaw. Đây là ID nhóm Microsoft Entra, không phải ID cuộc trò chuyện Bot Framework được dùng trong hoạt động Teams đến.

​

Kênh riêng tư

1. Dùng kênh tiêu chuẩn cho tương tác bot
2. Dùng DM - người dùng luôn có thể nhắn trực tiếp cho bot
3. Dùng Graph API để truy cập lịch sử (yêu cầu ChannelMessage.Read.All)

​

Khắc phục sự cố

​

Sự cố thường gặp

• Hình ảnh không hiển thị trong kênh: Thiếu quyền Graph hoặc sự đồng ý của quản trị viên. Cài đặt lại ứng dụng Teams và thoát hoàn toàn/mở lại Teams.
• Không có phản hồi trong kênh: mặc định yêu cầu nhắc đến; đặt channels.msteams.requireMention=false hoặc cấu hình theo từng team/channel.
• Không khớp phiên bản (Teams vẫn hiển thị manifest cũ): gỡ bỏ + thêm lại ứng dụng và thoát hoàn toàn Teams để làm mới.
• 401 Unauthorized từ webhook: Dự kiến xảy ra khi kiểm thử thủ công không có Azure JWT - nghĩa là endpoint có thể truy cập được nhưng xác thực thất bại. Dùng Azure Web Chat để kiểm thử đúng cách.

​

Lỗi tải manifest lên

• “Icon file cannot be empty”: Manifest tham chiếu đến các tệp biểu tượng có kích thước 0 byte. Tạo biểu tượng PNG hợp lệ (32x32 cho outline.png, 192x192 cho color.png).
• “webApplicationInfo.Id already in use”: Ứng dụng vẫn được cài đặt trong team/chat khác. Tìm và gỡ cài đặt trước, hoặc chờ 5-10 phút để thay đổi lan truyền.
• “Something went wrong” khi tải lên: Thay vào đó hãy tải lên qua https://admin.teams.microsoft.com, mở DevTools của trình duyệt (F12) → tab Network, rồi kiểm tra phần thân phản hồi để xem lỗi thực tế.
• Sideload thất bại: Thử “Upload an app to your org’s app catalog” thay vì “Upload a custom app” - cách này thường vượt qua được các hạn chế sideload.

​

Quyền RSC không hoạt động

1. Xác minh webApplicationInfo.id khớp chính xác với App ID của bot
2. Tải lại ứng dụng lên và cài đặt lại trong team/chat
3. Kiểm tra xem quản trị viên tổ chức của bạn có chặn quyền RSC không
4. Xác nhận bạn đang dùng đúng phạm vi: ChannelMessage.Read.Group cho teams, ChatMessage.Read.Chat cho group chats

​

Tham khảo

• Tạo Azure Bot - hướng dẫn thiết lập Azure Bot
• Teams Developer Portal - tạo/quản lý ứng dụng Teams
• Lược đồ manifest ứng dụng Teams
• Nhận tin nhắn kênh với RSC
• Tham chiếu quyền RSC
• Xử lý tệp của bot Teams (kênh/nhóm yêu cầu Graph)
• Nhắn tin chủ động
• @microsoft/teams.cli - Teams CLI để quản lý bot

​

Liên quan

• Tổng quan kênh - tất cả kênh được hỗ trợ
• Ghép nối - xác thực DM và luồng ghép nối
• Nhóm - hành vi trò chuyện nhóm và kiểm soát yêu cầu nhắc đến
• Định tuyến kênh - định tuyến phiên cho tin nhắn
• Bảo mật - mô hình truy cập và gia cố