メインコンテンツまでスキップ

Microsoft Teams

Updated: 2026-01-21

Status: text + DM attachments are supported; channel/group file sending requires sharePointSiteId + Graph permissions (see Sending files in group chats). Polls are sent via Adaptive Cards.

ClawCentral connects to Microsoft Teams via the Bot Framework. You register an Azure Bot, point its messaging endpoint at your ClawCentral webhook URL, and enter the credentials in the Admin UI. No local server, tunnel, or CLI installation is required — ClawCentral's managed platform handles all incoming webhook traffic.

Webhook URL​

https://<your-tenant>.clawcentral.io/webhooks/teams

Replace <your-tenant> with your ClawCentral tenant slug.

Required credentials​

Set these in Admin UI → Settings → Tenant Settings → Secrets:

SecretDescription
TEAMS_APP_IDMicrosoft App ID (from Azure Bot resource)
TEAMS_APP_PASSWORDClient secret (App password) from the App Registration

ClawCentral verifies JWT tokens from the Bot Framework JWKS automatically on every inbound request.

Goals​

  • Talk to ClawCentral 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).

Azure Bot Setup​

Before configuring ClawCentral, you need to create an Azure Bot resource.

Step 1: Create Azure Bot​

  1. Go to Create Azure Bot

  2. Fill in the Basics tab:

    FieldValue
    Bot handleYour bot name, e.g., clawcentral-teams (must be unique)
    SubscriptionSelect your Azure subscription
    Resource groupCreate new or use existing
    Pricing tierFree for dev/testing
    Type of AppSingle Tenant (recommended — see note below)
    Creation typeCreate new Microsoft App ID

Deprecation notice: Creation of new multi-tenant bots was deprecated after 2025-07-31. Use Single Tenant for new bots.

  1. Click Review + create → Create (wait ~1-2 minutes)

Step 2: Get Credentials​

  1. Go to your Azure Bot resource → Configuration
  2. Copy Microsoft App ID — this is your TEAMS_APP_ID
  3. Click Manage Password → go to the App Registration
  4. Under Certificates & secrets → New client secret → copy the Value — this is your TEAMS_APP_PASSWORD

Step 3: Configure Messaging Endpoint​

  1. In Azure Bot → Configuration
  2. Set Messaging endpoint to: 
    https://<your-tenant>.clawcentral.io/webhooks/teams

Step 4: Enable Teams Channel​

  1. In Azure Bot → Channels
  2. Click Microsoft Teams → Configure → Save
  3. Accept the Terms of Service

Step 5: Enter Credentials in Admin UI​

  1. Open your Admin UI at https://<your-tenant>.clawcentral.io/
  2. Go to Settings → Tenant Settings → Secrets
  3. Add TEAMS_APP_ID and TEAMS_APP_PASSWORD as key-value pairs
  4. Save each secret

Step 6: Build and Install the Teams App Package​

  1. Create a Teams app manifest that references your bot:
    • bots[].botId = your Azure Bot App ID
    • bots[].scopes: personal, team, groupChat
    • bots[].supportsFiles: true for DM file handling
    • Add RSC permissions (see RSC Permissions below)
  2. Create icons: outline.png (32×32) and color.png (192×192)
  3. Zip manifest.json, outline.png, color.png together
  4. Install the app in Teams (sideload or org catalog)

Teams Developer Portal (Alternative)​

Instead of manually creating a manifest ZIP, use the Teams Developer Portal:

  1. Click + New app
  2. Fill in basic info (name, description, developer info)
  3. Go to App features → Bot
  4. Select Enter a bot ID manually and paste your Azure Bot App ID
  5. Check scopes: Personal, Team, Group Chat
  6. Click Distribute → Download app package
  7. In Teams: Apps → Manage your apps → Upload a custom app → select the ZIP

Testing the Bot​

Option A: Azure Web Chat (verify webhook first)

  1. In Azure Portal → your Azure Bot resource → Test in Web Chat
  2. Send a message — you should see a response
  3. This confirms your webhook endpoint is correctly configured before Teams setup

Option B: Teams (after app installation)

  1. Install the Teams app (sideload or org catalog)
  2. Find the bot in Teams and send a DM

Current Teams RSC Permissions (Manifest)​

These resourceSpecific permissions are needed in the Teams app manifest. They only apply inside the team/chat where the app is installed.

For channels (team scope):

  • 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)

For group chats:

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

Example Teams Manifest (redacted)​

Minimal, valid example with the required fields. Replace IDs and URLs.

{
  "$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": "ClawCentral" },
  "developer": {
    "name": "Your Org",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com/privacy",
    "termsOfUseUrl": "https://example.com/terms"
  },
  "description": { "short": "ClawCentral in Teams", "full": "ClawCentral 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 if you want channel traffic.

Updating an existing app​

To update an already-installed Teams app (e.g., to add RSC permissions):

  1. Update your manifest.json with the new settings
  2. Increment the version field (e.g., 1.0.0 → 1.1.0)
  3. Re-zip the manifest with icons (manifest.json, outline.png, color.png)
  4. Upload the new zip:
    • Option A (Teams Admin Center): Teams Admin Center → Teams apps → Manage apps → find your app → Upload new version
    • Option B (Sideload): In Teams → Apps → Manage your apps → Upload a custom app
  5. For team channels: Reinstall the app in each team for new permissions to take effect
  6. Fully quit and relaunch Teams (not just close the window) to clear cached app metadata

Capabilities: RSC only vs Graph​

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

Works:

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

Does NOT work:

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

With Teams RSC + Microsoft Graph Application permissions​

Adds:

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

RSC vs Graph API​

CapabilityRSC PermissionsGraph API
Real-time messagesYes (via webhook)No (polling only)
Historical messagesNoYes (can query history)
Setup complexityApp manifest onlyRequires admin consent + token flow
Works offlineNo (must be running)Yes (query anytime)

Bottom line: RSC is for real-time listening; Graph API is for historical access. For catching up on missed messages while offline, you need Graph API with ChannelMessage.Read.All (requires admin consent).

Graph-enabled media + history (required for channels)​

If you need images/files in channels or want to fetch message history, you must enable Microsoft Graph permissions and grant admin consent.

  1. In Entra ID (Azure AD) App Registration, add Microsoft 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.

Additional permission for user mentions: User @mentions work out of the box for users in the conversation. However, if you want to dynamically search and mention users who are not in the current conversation, add User.Read.All (Application) permission and grant admin consent.

Sending files in group chats​

Bots can send files in DMs using the FileConsentCard flow (built-in). However, sending files in group chats/channels requires additional setup:

ContextHow files are sentSetup needed
DMsFileConsentCard → user accepts → bot uploadsWorks out of the box
Group chats/channelsUpload to SharePoint → share linkRequires sharePointSiteId + Graph permissions
Images (any context)Base64-encoded inlineWorks out of the box

Why group chats need SharePoint​

Bots don't have a personal OneDrive drive (the /me/drive Graph API endpoint doesn't work for application identities). To send files in group chats/channels, the bot uploads to a SharePoint site and creates a sharing link.

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/contoso.sharepoint.com:/sites/BotFiles"
    # Response includes: "id": "contoso.sharepoint.com,guid1,guid2"

  4. Enter the SharePoint site ID in Admin UI → Settings → Channels → Teams (the TEAMS_APP_ID / TEAMS_APP_PASSWORD settings page includes this field).

Sharing behavior​

PermissionSharing behavior
Sites.ReadWrite.All onlyOrganization-wide sharing link (anyone in org can access)
Sites.ReadWrite.All + Chat.Read.AllPer-user sharing link (only chat members can access)

Known Limitations​

Webhook timeouts​

Teams delivers messages via HTTP webhook. If processing takes too long (e.g., slow model responses), you may see gateway timeouts or Teams retrying the message (causing duplicates). ClawCentral returns HTTP 200 immediately and processes the reply asynchronously, which minimizes this risk.

Formatting​

Teams markdown is more limited than Slack or Discord:

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

Reply Style: Threads vs Posts​

Teams recently introduced two channel UI styles over the same underlying data model:

StyleDescription
Posts (classic)Messages appear as cards with threaded replies underneath
Threads (Slack-like)Messages flow linearly, more like Slack

The Teams API does not expose which UI style a channel uses. Contact support if replies appear in unexpected positions in your channels.

Access Control​

DM access

  • Unknown senders are ignored until a pairing code is approved via the Admin UI.
  • Use stable AAD object IDs for allowlists. UPNs/display names are mutable.

Group access

  • Group messages require @mention by default.
  • Groups can be allowlisted by team/channel ID via the Admin UI.

Team and Channel IDs (Common Gotcha)​

The groupId query parameter in Teams URLs is NOT the team ID. Extract IDs from the URL path:

Team URL:

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

Channel URL:

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

Private Channels​

Bots have limited support in private channels:

FeatureStandard ChannelsPrivate Channels
Bot installationYesLimited
Real-time messages (webhook)YesMay not work
RSC permissionsYesMay behave differently
@mentionsYesIf bot is accessible
Graph API historyYesYes (with permissions)

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. Configure per-team/channel settings via the Admin UI.
  • 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 Azure JWT — means 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 (32×32 for outline.png, 192×192 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 and check the browser DevTools Network tab for the actual error.
  • Sideload failing: Try "Upload an app to your org's app catalog" instead — 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're using the right scope: ChannelMessage.Read.Group for teams, ChatMessage.Read.Chat for group chats

References​