docs: add Teams API limitations guide

- Explain why channel message deletion isn't supported (HTTP 405)
- Document three workaround options for production
- Clarify this is a Microsoft platform limitation
- Provide references and future guidance

TEAMS_API_LIMITATIONS.md

@@ -0,0 +1,112 @@
+# 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):
+   ```typescript
+   // Example: Interactive login or on-behalf-of flow
+   const userToken = await acquireTokenInteractive();
+   ```
+
+3. **Update Delete Endpoint** to accept delegated tokens:
+   ```typescript
+   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:
+```json
+{
+  "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](https://learn.microsoft.com/en-us/graph/api/chatmessage-update)
+- Graph API Permissions: [ChatMessage Permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#chat-message-permissions)
+- Teams Bot Framework: [Microsoft Teams Bot Framework](https://learn.microsoft.com/en-us/azure/bot-service/channel-connect-teams)
+
+## Future Considerations
+
+Monitor Microsoft's Graph API changelog for potential changes to message deletion restrictions. This limitation may be relaxed in future API versions.