Job-Form/TEAMS_API_LIMITATIONS.md

Microsoft Teams API Limitations & Workarounds

Problem: Cannot Delete Channel Messages

When attempting to delete Teams channel messages via the Microsoft Graph REST API, you'll receive an HTTP 405 (Method Not Allowed) error.

Root Cause

Microsoft Teams Graph API does not support deletion of channel messages through the standard REST API endpoint:

DELETE /teams/{teamId}/channels/{channelId}/messages/{messageId}

This is a platform limitation by Microsoft, not an application error.

Why This Limitation Exists

• Security & Compliance: Teams maintains message immutability for audit/compliance purposes in many organizations.
• Design Decision: Microsoft intentionally restricts programmatic message deletion to prevent data loss.
• Channel vs. Chat: The limitation applies specifically to channel messages; 1:1 chat messages have different permission models.

Workarounds

Option 1: Delete via Teams Client (Recommended for Testing)

1. Open Microsoft Teams
2. Navigate to the channel
3. Right-click on the message
4. Select "Delete"
5. Confirm deletion

This works because Teams client has special privileges that REST API doesn't.

Option 2: Use Delegated Permissions (For Production Apps)

If you need programmatic deletion, you can:

1. Configure Azure AD App Registration with delegated permissions:

   • Add permission: ChatMessage.ReadWrite.All (delegated)
   • Requires admin consent
   • Must use user authentication (not app-only)

2. Obtain User's Access Token (instead of app-only token):

   // Example: Interactive login or on-behalf-of flow
   const userToken = await acquireTokenInteractive();
   

3. Update Delete Endpoint to accept delegated tokens:

   const client = Client.init({ 
     authProvider: (done) => done(null, userToken) 
   });
   

4. Test Deletion:

   • Provide the user token in the Authorization header
   • Note: May still fail if user lacks permissions in the team/channel

Option 3: Use Microsoft Teams Bot

Create a Teams bot with ChatMessage.ReadWrite.All permission in bot-specific context. This requires:

• Registering a Teams bot
• Setting up bot credentials
• Handling message events through bot framework

More complex but potentially the most flexible long-term solution.

Current Application Status

What Works ✅

• List Teams channels
• List channel messages with full details
• Preview message content and Adaptive Cards
• Select and mark messages for deletion

What Doesn't Work ❌

• Delete channel messages via REST API (Microsoft limitation)
• No workaround without changing auth strategy

Recommended Approach

For testing/cleanup scenarios:

• Use the Teams client UI to manually delete test messages
• Or use the UI to identify which messages to delete, then delete them manually

For production scenarios:

• Implement delegated token authentication with user consent
• OR use a Teams bot with appropriate permissions
• OR accept that message deletion requires Teams client interaction

Error Response

When deletion is attempted:

{
  "success": false,
  "message": "Teams API limitation: Channel message deletion not supported via REST API. Delete manually from Teams client or grant ChatMessage.ReadWrite.All delegated permission with user token.",
  "isTeamsLimitation": true
}

The isTeamsLimitation flag helps distinguish between actual errors and known platform limitations.

References

• Microsoft Teams Documentation: Update a chatMessage
• Graph API Permissions: ChatMessage Permissions
• Teams Bot Framework: Microsoft Teams Bot Framework

Future Considerations

Monitor Microsoft's Graph API changelog for potential changes to message deletion restrictions. This limitation may be relaxed in future API versions.