Microsoft Teams

​

Bundled plugin

openclaw plugins install @openclaw/msteams

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

​

Quick setup

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"

{
  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>

​

Goals

• Talk to OpenClaw via Teams DMs, group chats, or channels.
• Keep routing deterministic: replies always go back to the channel they arrived on.
• Default to safe channel behavior (mentions required unless configured otherwise).

​

Config writes

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

​

Access control (DMs + groups)

• Default: channels.msteams.dmPolicy = "pairing". Unknown senders are ignored until approved.
• channels.msteams.allowFrom should use stable AAD object IDs or static sender access groups such as accessGroup:core-team.
• Do not rely on UPN/display-name matching for allowlists; they can change. OpenClaw disables direct name matching by default; opt in with channels.msteams.dangerouslyAllowNameMatching: true.
• The wizard can resolve names to IDs via Microsoft Graph when credentials allow.

• Default: channels.msteams.groupPolicy = "allowlist" (blocked unless you add groupAllowFrom). channels.defaults.groupPolicy can override the shared default when channels.msteams.groupPolicy is unset.
• channels.msteams.groupAllowFrom controls which senders or static sender access groups can trigger in group chats/channels (falls back to channels.msteams.allowFrom).
• Set groupPolicy: "open" to allow any member (still mention-gated by default).
• To block all channels, set channels.msteams.groupPolicy: "disabled".

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

• Scope group/channel replies by listing teams and channels under channels.msteams.teams.
• Use stable Teams conversation IDs from Teams links as keys, not mutable display names (see Team and Channel IDs).
• When groupPolicy="allowlist" and a teams allowlist is present, only listed teams/channels are accepted (mention-gated).
• The configure wizard accepts Team/Channel entries and stores them for you.
• On startup, OpenClaw resolves team/channel and user allowlist names to IDs (when Graph permissions allow) and logs the mapping. Unresolved names are kept as typed but ignored for routing unless channels.msteams.dangerouslyAllowNameMatching: true is set.

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

​

Federated authentication (certificate plus managed identity)

​

Option A: Certificate-based authentication

1. Generate or obtain a certificate (PEM format with private key).
2. Entra ID → App Registration → Certificates & secrets → Certificates → upload the public certificate.

{
  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

​

Option B: Azure Managed Identity

1. The bot pod/VM has a managed identity (system- or user-assigned).
2. A federated identity credential links the managed identity to the Entra ID app registration.
3. At runtime, OpenClaw uses @azure/identity to acquire tokens from the Azure IMDS endpoint.
4. The token is passed to the Teams SDK for bot authentication.

• Azure infrastructure with managed identity enabled (AKS workload identity, App Service, VM).
• Federated identity credential created on the Entra ID app registration.
• Network access to IMDS (169.254.169.254:80) from the pod/VM.

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

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id> (user-assigned only)

​

AKS Workload Identity setup

1. Enable workload identity on your AKS cluster.
2. Create a federated identity credential on the Entra ID app registration:
   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. Annotate the Kubernetes service account with the app client ID:
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-bot-sa
     annotations:
       azure.workload.identity/client-id: "<APP_CLIENT_ID>"
   
4. Label the pod for workload identity injection:
   metadata:
     labels:
       azure.workload.identity/use: "true"
   
5. Allow network access to IMDS (169.254.169.254): if using NetworkPolicy, add an egress rule for 169.254.169.254/32 on port 80.

​

Auth type comparison

​

Local development (tunneling)

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

​

Testing the bot

teams app doctor <teamsAppId>

1. Install the Teams app (install link from teams app get <id> --install-link).
2. Find the bot in Teams and send a DM.
3. Check gateway logs for incoming activity.

​

Environment variables

​

Member info action

• Member.Read.Group RSC permission (already in the recommended manifest).
• For cross-team lookups: User.Read.All Graph Application permission with admin consent.

​

History context

• channels.msteams.historyLimit controls how many recent channel/group messages are wrapped into the prompt. Falls back to messages.groupChat.historyLimit, then defaults to 50. Set 0 to disable.
• Fetched thread history is filtered by sender allowlists (allowFrom / groupAllowFrom), so thread context seeding only includes messages from allowed senders.
• Quoted attachment context (parsed from the Skype Reply-schema HTML in a reply’s own attachments) is passed through unfiltered; only thread-history seeding applies the sender-allowlist filter today.
• DM history can be limited with channels.msteams.dmHistoryLimit (user turns). Per-user overrides: channels.msteams.dms["<user_id>"].historyLimit.

​

Current Teams RSC permissions (manifest)

• ChannelMessage.Read.Group (Application) - receive all channel messages without @mention
• ChannelMessage.Send.Group (Application)
• Member.Read.Group (Application)
• Owner.Read.Group (Application)
• ChannelSettings.Read.Group (Application)
• TeamMember.Read.Group (Application)
• TeamSettings.Read.Group (Application)

• ChatMessage.Read.Chat (Application) - receive all group chat messages without @mention

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

​

Example Teams manifest (redacted)

{
  $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" },
      ],
    },
  },
}

​

Manifest caveats (must-have fields)

• bots[].botId must match the Azure Bot App ID.
• webApplicationInfo.id must match the Azure Bot App ID.
• bots[].scopes must include the surfaces you plan to use (personal, team, groupChat).
• bots[].supportsFiles: true is required for file handling in personal scope.
• authorization.permissions.resourceSpecific must include channel read/send for channel traffic.

​

Updating an existing app

# 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

​

Capabilities: RSC only vs Graph

​

With Teams RSC only (app installed, no Graph API permissions)

• Read channel message text content.
• Send channel message text content.
• Receive personal (DM) file attachments.

• Channel/group image or file contents (payload only includes an HTML stub).
• Downloading attachments stored in SharePoint/OneDrive.
• Reading message history beyond the live webhook event.

​

With Teams RSC + Microsoft Graph Application permissions

• Downloading hosted content (images pasted into messages).
• Downloading file attachments stored in SharePoint/OneDrive.
• Reading channel/chat message history via Graph.

​

RSC vs Graph API

​

Graph-enabled media + history (required for channels)

1. Entra ID (Azure AD) App Registration → add Graph Application permissions:
   • ChannelMessage.Read.All (channel attachments + history)
   • Chat.Read.All or ChatMessage.Read.All (group chats)
2. Grant admin consent for the tenant.
3. Bump the Teams app manifest version, re-upload, and reinstall the app in Teams.
4. Fully quit and relaunch Teams to clear cached app metadata.

​

Known limitations

​

Webhook timeouts

• Teams retrying the message (causing duplicates).
• Dropped replies.

​

Teams cloud and service URL support

• channels.msteams.cloud selects the Teams SDK cloud preset for authentication, JWT validation, token services, and Graph scope.
• channels.msteams.serviceUrl selects the Bot Connector endpoint boundary used to validate stored conversation references before proactive sends, edits, deletes, cards, polls, file-consent messages, and queued long-running replies. It is required for USGov and DoD SDK clouds. For China/21Vianet, OpenClaw uses the SDK China preset and accepts stored/configured service URLs only on Azure China Bot Framework channel hosts.

{
  "channels": {
    "msteams": {
      "serviceUrl": "https://smba.infra.gcc.teams.microsoft.com/teams"
    }
  }
}

{
  "channels": {
    "msteams": {
      "cloud": "USGov",
      "serviceUrl": "https://smba.infra.gov.teams.microsoft.us/teams"
    }
  }
}

​

Formatting

• Basic formatting works: bold, italic, code, links.
• Complex markdown (tables, nested lists) may not render correctly.
• Adaptive Cards are supported for polls and semantic presentation sends (see below).

​

Configuration

• channels.msteams.enabled: enable/disable the channel.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: bot credentials.
• channels.msteams.cloud: Teams SDK cloud environment (Public, USGov, USGovDoD, or China; default Public). Set with serviceUrl for USGov/DoD SDK clouds; China uses the SDK preset and stored Azure China Bot Framework conversation references, with Graph-backed helpers disabled until Azure China Graph routing ships.
• channels.msteams.serviceUrl: Bot Connector service URL boundary for SDK proactive operations. Public cloud uses the SDK default; set for GCC (https://smba.infra.gcc.teams.microsoft.com/teams), GCC High, or DoD. China accepts Azure China Bot Framework channel hosts when the stored conversation reference comes from Teams operated by 21Vianet.
• channels.msteams.webhook.port (default 3978).
• channels.msteams.webhook.path (default /api/messages).
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (default pairing).
• channels.msteams.allowFrom: DM allowlist (AAD object IDs recommended). The wizard resolves names to IDs during setup when Graph access is available.
• channels.msteams.dangerouslyAllowNameMatching: break-glass toggle to re-enable mutable UPN/display-name matching and direct team/channel name routing.
• channels.msteams.textChunkLimit: outbound text chunk size in characters (default 4000, and hard-capped at 4000 regardless of a higher configured value).
• channels.msteams.chunkMode: length (default) or newline to split on blank lines (paragraph boundaries) before length chunking.
• channels.msteams.mediaAllowHosts: allowlist for inbound attachment hosts (defaults to Microsoft/Teams domains: Graph, SharePoint/OneDrive, Teams CDN, Bot Framework, Azure Media Services).
• channels.msteams.mediaAuthAllowHosts: allowlist for attaching Authorization headers on media retries (defaults to Graph + Bot Framework hosts).
• channels.msteams.mediaMaxMb: per-channel media size limit override in MB. Falls back to agents.defaults.mediaMaxMb when unset.
• channels.msteams.requireMention: require @mention in channels/groups (default true).
• channels.msteams.replyStyle: thread | top-level (see Reply style).
• channels.msteams.teams.<teamId>.replyStyle: per-team override.
• channels.msteams.teams.<teamId>.requireMention: per-team override.
• channels.msteams.teams.<teamId>.tools: default per-team tool policy overrides (allow/deny/alsoAllow) used when a channel override is missing.
• channels.msteams.teams.<teamId>.toolsBySender: default per-team per-sender tool policy overrides ("*" wildcard supported).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: per-channel override.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: per-channel override.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: per-channel tool policy overrides (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: per-channel per-sender tool policy overrides ("*" wildcard supported).
• toolsBySender keys should use explicit prefixes: channel:, id:, e164:, username:, name: (legacy unprefixed keys still map to id: only).
• channels.msteams.authType: authentication type - "secret" (default) or "federated".
• channels.msteams.certificatePath: path to PEM certificate file (federated + certificate auth).
• channels.msteams.certificateThumbprint: certificate thumbprint; accepted, not required for auth.
• channels.msteams.useManagedIdentity: enable managed identity auth (federated mode).
• channels.msteams.managedIdentityClientId: client ID for user-assigned managed identity.
• channels.msteams.sharePointSiteId: SharePoint site ID for file uploads in group chats/channels (see Sending files in group chats).
• channels.msteams.welcomeCard, channels.msteams.groupWelcomeCard, channels.msteams.promptStarters: welcome Adaptive Card shown on first DM/group contact, and its suggested prompt buttons.
• channels.msteams.responsePrefix: text prefixed to outbound replies.
• channels.msteams.feedbackEnabled (default true), channels.msteams.feedbackReflection (default true), channels.msteams.feedbackReflectionCooldownMs: thumbs-up/down feedback on replies and the negative-feedback reflection follow-up.
• channels.msteams.sso, channels.msteams.delegatedAuth: Bot Framework OAuth connection and delegated Graph scopes for SSO-backed flows; sso.enabled: true requires sso.connectionName.

​

Routing and sessions

• Session keys follow the standard agent format (see /concepts/session):
  • Direct messages share the main session (agent:<agentId>:<mainKey>).
  • Channel/group messages use conversation id:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Reply style: threads vs posts

• thread in a Threads-style channel → replies appear nested awkwardly.
• top-level in a Posts-style channel → replies appear as separate top-level posts instead of in-thread.

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

​

Resolution precedence

1. Per-channel - channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. Per-team - channels.msteams.teams.<teamId>.replyStyle
3. Global - channels.msteams.replyStyle
4. Implicit default - derived from requireMention:
   • requireMention: true → thread
   • requireMention: false → top-level

​

Thread context preservation

​

Attachments and images

• DMs: images and file attachments work via Teams bot file APIs.
• Channels/groups: attachments live in M365 storage (SharePoint/OneDrive). The webhook payload only includes an HTML stub, not the actual file bytes. Graph API permissions are required to download channel attachments.
• For explicit file-first sends, use action=upload-file with media / filePath / path; optional message becomes the accompanying text/comment, and filename (or title) overrides the uploaded name.

​

Sending files in group chats

​

Why group chats need SharePoint

​

Setup

1. Add Graph API permissions in Entra ID (Azure AD) → App Registration:
   • Sites.ReadWrite.All (Application) - upload files to SharePoint.
   • Chat.Read.All (Application) - optional, enables per-user sharing links.
2. Grant admin consent for the tenant.
3. Get your SharePoint site ID:
   # 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. Configure OpenClaw:
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Sharing behavior

​

Fallback behavior

​

Files stored location

​

Polls (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> --poll-question "..." --poll-option "..." --poll-option "...".
• Votes are recorded by the gateway in OpenClaw plugin-state SQLite under state/openclaw.sqlite.
• Existing msteams-polls.json files are imported by openclaw doctor --fix, not by the running plugin.
• The gateway must stay online to record votes.
• Polls do not auto-post result summaries, and there is no poll-results CLI yet.

​

Presentation cards

{
  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!"}]}'

​

Target formats

# 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" }],
  },
}

​

Proactive messaging

• Proactive messages are only possible after a user has interacted, because OpenClaw stores conversation references at that point.
• See /gateway/configuration for dmPolicy and allowlist gating.

​

Team and Channel IDs (Common Gotcha)

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)

• Team key = path segment after /team/ (URL-decoded, e.g., 19:Bk4j...@thread.tacv2; older tenants may show @thread.skype, which is also valid).
• Channel key = path segment after /channel/ (URL-decoded).
• Ignore the groupId query parameter for OpenClaw routing. It is the Microsoft Entra group ID, not the Bot Framework conversation ID used in incoming Teams activities.

​

Private channels

1. Use standard channels for bot interactions.
2. Use DMs; users can always message the bot directly.
3. Use Graph API for historical access (requires ChannelMessage.Read.All).

​

Troubleshooting

​

Common issues

• Images not showing in channels: Graph permissions or admin consent missing. Reinstall the Teams app and fully quit/reopen Teams.
• No responses in channel: mentions are required by default; set channels.msteams.requireMention=false or configure per team/channel.
• Version mismatch (Teams still shows old manifest): remove + re-add the app and fully quit Teams to refresh.
• 401 Unauthorized from webhook: expected when testing manually without an Azure JWT; means the endpoint is reachable but auth failed. Use Azure Web Chat to test properly.

​

Manifest upload errors

• “Icon file cannot be empty”: the manifest references icon files that are 0 bytes. Create valid PNG icons (32x32 for outline.png, 192x192 for color.png).
• “webApplicationInfo.Id already in use”: the app is still installed in another team/chat. Find and uninstall it first, or wait 5-10 minutes for propagation.
• “Something went wrong” on upload: upload via https://admin.teams.microsoft.com instead, open browser DevTools (F12) → Network tab, and check the response body for the actual error.
• Sideload failing: try “Upload an app to your org’s app catalog” instead of “Upload a custom app”; this often bypasses sideload restrictions.

​

RSC permissions not working

1. Verify webApplicationInfo.id matches your bot’s App ID exactly.
2. Re-upload the app and reinstall in the team/chat.
3. Check if your org admin has blocked RSC permissions.
4. Confirm you are using the right scope: ChannelMessage.Read.Group for teams, ChatMessage.Read.Chat for group chats.

​

References

• Create Azure Bot - Azure Bot setup guide
• Teams Developer Portal - create/manage Teams apps
• Teams app manifest schema
• Receive channel messages with RSC
• RSC permissions reference
• Teams bot file handling (channel/group requires Graph)
• Proactive messaging
• @microsoft/teams.cli - Teams CLI for bot management

​

Related

• Channels Overview - all supported channels
• Pairing - DM authentication and pairing flow
• Groups - group chat behavior and mention gating
• Channel Routing - session routing for messages
• Security - access model and hardening