Skip to main content

Microsoft Teams

Microsoft Teams is a collaboration platform that combines workplace chat, video meetings, file storage, and application integration. This connector enables AI assistants to interact with Teams channels, send messages, manage team memberships, schedule meetings, and monitor presence status through the Microsoft Graph API.

Authentication Types​

Microsoft Teams supports OAuth 2.0 authentication via the Microsoft identity platform:

  • OAuth - Standard OAuth 2.0 authorization flow
    • Pros: Secure delegated access, supports granular permissions, automatic token refresh
    • Cons: Requires user consent, needs Azure app registration
    • Best for: Production applications, user-specific operations

Setting up OAuth​

To use the Microsoft Teams connector, you need to register an application in Azure and configure OAuth credentials.

1. Register an Application in Azure Portal​

  1. Go to Azure Portal

  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

  3. In the left sidebar, click App registrations

  4. Click New registration

  5. Fill in the application details:

    • Name: Choose a descriptive name (e.g., "My Teams Integration")
    • Supported account types: Select the appropriate option:
      • "Accounts in this organizational directory only" for single-tenant apps
      • "Accounts in any organizational directory" for multi-tenant apps
      • "Accounts in any organizational directory and personal Microsoft accounts" for the widest support
    • Redirect URI: Select "Web" and enter your redirect URI (e.g., https://yourapp.com/oauth/callback)

  6. Click Register

2. Configure API Permissions​

  1. In your app registration, click API permissions in the left sidebar

  2. Click Add a permission

  3. Select Microsoft Graph

  4. Choose Delegated permissions

  5. Add the permissions your application needs. Common permissions include:

    • Team.ReadBasic.All - Read basic team information
    • Channel.ReadBasic.All - Read basic channel information
    • ChannelMessage.Read.All - Read channel messages
    • ChannelMessage.Send - Send messages to channels
    • TeamMember.Read.All - Read team members
    • OnlineMeetings.ReadWrite - Create and manage meetings
    • Presence.Read.All - Read user presence

  6. Click Add permissions

tip

Some permissions require admin consent. If you see "Admin consent required" next to a permission, ask your tenant administrator to grant consent by clicking Grant admin consent for [Your Organization].

3. Create Client Secret​

  1. In your app registration, click Certificates & secrets in the left sidebar

  2. Under Client secrets, click New client secret

  3. Add a description (e.g., "Teams Connector Secret")

  4. Choose an expiration period (recommended: 12 months or 24 months)

  5. Click Add

  6. Important: Copy the secret Value immediately - it will only be shown once!

warning

Store the client secret securely. If you lose it, you'll need to create a new one.

4. Get Your Credentials​

You'll need these values to configure the connector:

  1. Application (client) ID: Found on the app registration Overview page
  2. Client Secret: The value you copied in the previous step
  3. Tenant ID (optional): Also found on the Overview page, useful for single-tenant apps

5. Configure Redirect URI in Your Application​

Make sure your application is configured to handle the OAuth callback at the redirect URI you specified. When users authorize the connection, they'll be redirected to this URL with an authorization code.

Troubleshooting​

Insufficient Privileges Error​

Cause: The application doesn't have the required permissions, or admin consent hasn't been granted.

Solution:

  1. Verify that you've added all necessary Microsoft Graph permissions in the Azure portal
  2. Check if any permissions require admin consent
  3. Ask your tenant administrator to grant admin consent for the application
  4. Ensure the user authorizing the app has the necessary permissions in Teams

Tenant Not Found​

Cause: The tenant ID is incorrect or the user doesn't have access to the specified tenant.

Solution:

  1. Verify the tenant ID is correct (found in Azure Portal > Microsoft Entra ID > Overview)
  2. For multi-tenant apps, use common as the tenant instead of a specific tenant ID
  3. Ensure the user has access to the Microsoft 365 organization

Rate Limiting​

Cause: Your application has exceeded Microsoft Graph's rate limits.

Solution:

  • Microsoft Graph has a limit of approximately 2,000 requests per app per second per tenant
  • For channel messages, there's a specific limit of 10 messages per 10 seconds per channel
  • Implement exponential backoff when you receive 429 (Too Many Requests) responses
  • Consider batching operations when possible

Team or Channel Not Found​

Cause: The team or channel ID is incorrect, or the user doesn't have access.

Solution:

  1. Verify the team/channel ID is correct
  2. Ensure the user is a member of the team
  3. For private channels, verify the user has been added to that specific channel
  4. Use the "List Joined Teams" tool to discover available teams

Cannot Send Messages​

Cause: Missing permissions or the channel doesn't allow posting.

Solution:

  1. Ensure the app has the ChannelMessage.Send permission
  2. Verify the user has permission to post in the channel
  3. Check if the channel is archived (archived channels are read-only)
  4. Respect the rate limit of 10 messages per 10 seconds per channel

Async Operations Timing Out​

Cause: Some Teams operations (like creating teams) are asynchronous and may take time.

Solution:

  • Team creation can take 5-10 seconds or longer to complete
  • The API returns 202 Accepted for async operations
  • Poll the resource periodically to check if the operation has completed
  • Don't retry too quickly; wait at least 5-10 seconds between checks

Common Use Cases​

Send Notifications to Teams Channels​

Automatically post updates, alerts, or notifications to specific Teams channels. Perfect for build notifications, monitoring alerts, or automated status updates.

1. Use "List Joined Teams" to find your team
2. Use "List Channels" to find the target channel
3. Use "Send Channel Message" to post your notification

Create Teams for New Projects​

Automatically create new Teams when projects are initiated, complete with standard channels and initial members.

1. Use "Create Team" with project name and description
2. Use "Create Channel" to add project-specific channels
3. Use "Add Team Member" to add team members with appropriate roles

Schedule Meetings Automatically​

Create Teams meetings programmatically for recurring events, project milestones, or automated scheduling.

1. Use "Create Online Meeting" with meeting details
2. Share the join URL with participants
3. Use "List User Meetings" to track scheduled meetings

Monitor Team Activity​

Track messages, member changes, and team status for compliance, analytics, or integration purposes.

1. Use "List Channel Messages" to retrieve recent messages
2. Use "List Team Members" to audit team membership
3. Use "Get User Presence" to check team member availability

Integrate with External Systems​

Connect Teams with your existing tools and workflows by posting messages based on external events or syncing data.

Example: When a support ticket is created:
1. Use "Send Channel Message" to notify the support team channel
2. Include ticket details and links in the message
3. Use "Reply to Message" to post updates as the ticket progresses

Best Practices​

Permissions​

  • Principle of Least Privilege: Only request the permissions your application actually needs
  • User vs Application Permissions: Use delegated permissions (user context) when possible; application permissions require admin consent and run with elevated privileges
  • Incremental Consent: Request permissions as needed rather than all at once upfront

Rate Limits​

  • Respect Limits: Stay under 2,000 requests per second per tenant
  • Message Posting: Don't exceed 10 messages per 10 seconds per channel
  • Implement Backoff: Use exponential backoff when you hit rate limits (429 responses)
  • Batch When Possible: Use batch requests for multiple operations when the API supports it

Error Handling​

  • Retry Transient Errors: Implement retry logic for network errors and 5xx responses
  • Handle 429 Gracefully: Respect the Retry-After header when rate limited
  • Validate IDs: Verify team and channel IDs before making requests
  • Check Permissions: Catch insufficient permissions errors and provide helpful messages

Security​

  • Secure Credentials: Never expose client secrets in client-side code or version control
  • Use HTTPS: Always use secure connections for OAuth redirects
  • Token Storage: Store access tokens securely and refresh them before expiration
  • Audit Access: Regularly review which applications have access to your tenant

Additional Resources​