New integration: Microsoft teams 🎉

Description

Add Microsoft Teams integration to sync team channels, messages, meetings, and collaboration activity into CORE via Microsoft Graph API.

Reference Implementations

Existing Integrations (use as templates)

• integrations/slack/ - Similar team messaging platform
• integrations/github/ - Similar event-driven system
• integrations/linear/ - Project management integration

Required Files Structure

integrations/teams/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Microsoft Graph API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Microsoft Graph API (Teams) Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code Grant) via Microsoft Identity Platform
• Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
• Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
• Required scopes:
  • Team.ReadBasic.All - Read teams the user is a member of
  • Channel.ReadBasic.All - Read channel names and descriptions
  • ChannelMessage.Read.All - Read channel messages
  • ChannelMessage.Send - Send messages to channels
  • Chat.Read - Read user's chats
  • Chat.ReadWrite - Read and send chat messages
  • ChatMessage.Read - Read chat messages
  • OnlineMeetings.Read - Read online meeting details
  • User.Read - Read user profile
  • offline_access - Refresh token support
  • openid - OpenID Connect sign-in
  • Group.Read.All - Read group info (teams are Microsoft 365 groups)

Base URL

• https://graph.microsoft.com/v1.0
• Beta endpoint: https://graph.microsoft.com/beta

Key Endpoints

Teams

• GET /me/joinedTeams - List teams the user has joined
• GET /teams/{team-id} - Get team details
• GET /teams/{team-id}/members - List team members
• GET /groups/{group-id}/team - Get team from group

Channels

• GET /teams/{team-id}/channels - List channels in a team
• GET /teams/{team-id}/channels/{channel-id} - Get channel details
• POST /teams/{team-id}/channels - Create a channel
• PATCH /teams/{team-id}/channels/{channel-id} - Update a channel
• DELETE /teams/{team-id}/channels/{channel-id} - Delete a channel
• GET /teams/{team-id}/channels/{channel-id}/members - List channel members

Channel Messages

• GET /teams/{team-id}/channels/{channel-id}/messages - List channel messages
• GET /teams/{team-id}/channels/{channel-id}/messages/{message-id} - Get a message
• POST /teams/{team-id}/channels/{channel-id}/messages - Send a message to channel
• GET /teams/{team-id}/channels/{channel-id}/messages/{message-id}/replies - List replies
• POST /teams/{team-id}/channels/{channel-id}/messages/{message-id}/replies - Reply to a message
• GET /teams/{team-id}/channels/{channel-id}/messages/delta - Delta query for messages

Chats (1:1 and Group)

• GET /me/chats - List user's chats
• GET /chats/{chat-id} - Get a chat
• GET /chats/{chat-id}/messages - List chat messages
• POST /chats/{chat-id}/messages - Send a chat message
• GET /chats/{chat-id}/members - List chat members

Online Meetings

• GET /me/onlineMeetings - List online meetings
• POST /me/onlineMeetings - Create an online meeting
• GET /me/onlineMeetings/{meeting-id} - Get meeting details
• GET /me/onlineMeetings/{meeting-id}/attendanceReports - Get attendance reports

Subscriptions (Webhooks)

• POST /subscriptions - Create change notification subscription
• GET /subscriptions - List active subscriptions
• PATCH /subscriptions/{id} - Renew a subscription
• DELETE /subscriptions/{id} - Delete a subscription

Events to Track

1. Channel Message Events

   • Message posted in channel
   • Message replied to
   • Message edited
   • Message deleted
   • Mention in channel message

2. Chat Events

   • Chat message received
   • Chat message sent
   • New chat started
   • Member added/removed from chat

3. Team/Channel Events

   • Channel created
   • Channel updated/renamed
   • Channel deleted
   • Member added/removed from team
   • Team settings updated

4. Meeting Events

   • Meeting created
   • Meeting started/ended
   • Participant joined/left
   • Meeting recording available

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts with Microsoft Identity Platform
• Create Microsoft Graph API utilities in utils.ts (can share with Outlook integration)
• Implement sync logic in schedule.ts for channels, messages, and meetings
• Set up Graph API subscriptions (webhooks) for real-time message notifications
• Convert Teams events to CORE activity format
• Handle delta queries for efficient incremental message sync
• Implement pagination with @odata.nextLink
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Microsoft Graph API v1.0 is the stable endpoint; beta has newer features but may change
• Teams are built on Microsoft 365 Groups - a team ID is also a group ID
• Sending messages to channels requires delegated permissions (not application); app-only tokens cannot post messages in real-time
• Channel message subscriptions require ChannelMessage.Read.All scope
• Delta queries available for channel messages (/messages/delta) for incremental sync
• Subscriptions (webhooks) must be renewed before expiry (max lifetime varies by resource)
• Access tokens expire after ~1 hour; refresh tokens last 90 days with continuous use
• Rate limiting: Varies by endpoint; typically 30 requests/second for messaging
• Consider sharing Graph API utilities with Microsoft Outlook integration
• Rich message formatting uses HTML or Adaptive Cards
• Attachments in messages require additional handling (hosted content)

Resources

• Microsoft Teams API Overview
• List Channel Messages
• Microsoft Graph API Overview
• Microsoft Graph Auth Overview
• Graph API Permissions Reference
• Teams Scopes Guide
• Change Notifications / Subscriptions
• Graph API Teams Integration (nBold)

Labels

enhancement, integration, new-feature

Start by reading integrations/github/src/index.ts and comparing the integrations/slack/, integrations/linear/, and any Outlook Graph utilities mentioned. Use the specified integrations/teams/ files and endpoint requirements to plan OAuth, synchronization, subscriptions, pagination, and activity conversion. Done means the Teams integration is documented, added to integrations/README.md, and covers the listed implementation tasks.