Microsoft Teams API Essential Guide

Aug 1, 2024 • 6 minute read

What type of API does Microsoft Teams provide?

Microsoft Teams primarily uses a REST API. Here are the key points about Microsoft Teams' API:

REST API

Microsoft Teams uses the Microsoft Graph REST API for most of its functionality.
The Graph API allows developers to interact with Teams resources like teams, channels, messages, etc. using standard HTTP methods (GET, POST, PATCH, DELETE).

Other API types

While primarily REST-based, Microsoft Teams also supports:
- GraphQL API for some specific scenarios that require more flexible querying
- WebSocket connections for real-time features like live updates

In summary, Microsoft Teams relies heavily on its REST-based Graph API for most integrations and functionality, while also offering GraphQL and WebSocket options for certain use cases. The REST API provides a flexible and standardized way to interact with Teams resources and services.

Does the Microsoft Teams API have webhooks?

The Microsoft Teams API supports webhooks, including Incoming Webhooks and Outgoing Webhooks.

Incoming Webhooks:

Allow external applications to post messages to Teams channels
Expose an HTTPS endpoint that accepts correctly formatted JSON payloads
Can be used to send messages, including Adaptive Cards
Are configured at the channel level

Outgoing Webhooks:

Allow sending text messages from a Teams channel to an external web service
Users can @mention the Outgoing Webhook to send a message
The external service can respond within 10 seconds with text or a card

For more advanced scenarios, Microsoft recommends building a notification bot instead of using webhooks. Notification bots offer more functionality and customization options.

The Microsoft Graph API can be used to get change notifications for certain Teams resources:

You can subscribe to changes in online meeting status using the endpoint: /communications/onlineMeeting/{meeting-id}
This feature is currently in preview and only available in the beta version of the API

Supported events for online meetings include:

Meeting start/end
Participant join/leave
Recording/transcript generation

It's important to note that the APIs for subscribing to meeting events are still in beta and not recommended for production use.

In summary, while Microsoft Teams offers webhook functionality, for more advanced event subscription and notification scenarios, it's recommended to use the Microsoft Graph API or build a custom notification bot.

Rate Limits and other limitations

Here are the key API rate limits for the Microsoft Teams API:

Global Limits

The global limit per app per tenant is 50 requests per second (RPS).
There is also an overall global limit of 130,000 requests per 10 seconds per app across all tenants.

Per-Resource Limits

GET requests for teams, channels, installed apps etc. are generally limited to 30 RPS per app per tenant.
POST/PATCH requests are generally limited to 30 RPS per app per tenant.
DELETE requests are generally limited to 15 RPS per app per tenant.
For many resources like channels and chats, there is an additional limit of 1 RPS per app per tenant per specific resource.

Message Limits

GET channel/chat messages: 20 RPS per app per tenant
POST channel messages: 50 RPS per app per tenant
POST chat messages: 20 RPS per app per tenant

Other Specific Limits

Creating teams: 10 RPS per app per tenant
Sending activity notifications: 5 RPS per app per tenant
Getting team members: 60 RPS per app per tenant

Key Points

Limits apply per app per tenant in most cases.
Different apps have separate rate limits.
A thread refers to a 1:1 conversation, group chat, or channel.
There are additional per-thread limits for bots sending messages.
Exceeding limits results in HTTP 429 errors.

Best Practices

Implement proper backoff and retry logic when receiving 429 errors.
Limit the frequency of messages sent to avoid appearing as spam.
Use pagination and delta queries where available to reduce API calls.
Consider using change notifications instead of frequent polling.

The exact limits are subject to change, so applications should be designed to gracefully handle throttling and adjust dynamically.

Latest API Version

Based on the search results provided, here is the most up-to-date information about the Microsoft Teams API versions:

Current Version

The current generally available (GA) version of the Microsoft Graph API, which includes Teams functionality, is v1.0. This version is accessible at the endpoint https://graph.microsoft.com/v1.0.

Beta Version

There is also a beta version of the Microsoft Graph API available at https://graph.microsoft.com/beta. This version contains new and experimental features that are not yet ready for production use.

Latest SDK Version

The latest version of the Microsoft Teams JavaScript client library (TeamsJS) is 2.25.0, as indicated by the CDN link in the search results.

Key Points to Consider

The v1.0 version contains features that are generally available and ready for production use.
Beta APIs should not be used in production applications as they may undergo breaking changes.
Microsoft provides at least 24 months notice before retiring an API version or removing an individual API from the GA version.
For Microsoft Graph SDKs, only the latest major version is fully supported and updated with new features.

Best Practices

Use the v1.0 endpoint for production applications to ensure stability and support.
Keep an eye on the Microsoft Graph changelog for updates and new features.
When using SDKs, try to upgrade to the latest version whenever possible to access new features and security updates.
Be prepared for potential changes in beta APIs if you choose to use them for testing or development purposes.

In summary, while there isn't a specific "Microsoft Teams API" version mentioned, the Teams functionality is part of the broader Microsoft Graph API. The most recent stable version is v1.0, with new features being developed in the beta version. Always refer to the official Microsoft documentation for the most up-to-date information on API versions and support status.

How to get a Microsoft Teams developer account and API Keys?

To get a developer account for Microsoft Teams and create an API integration, you'll need to follow these steps:

1. Set up a Microsoft 365 developer account

Sign up for the Microsoft 365 Developer Program at https://developer.microsoft.com/en-us/microsoft-365/dev-program
This will give you a free Microsoft 365 E5 developer subscription to use for development purposes

2. Register your application in Microsoft Entra ID

Go to the Azure portal (https://portal.azure.com)
Navigate to Microsoft Entra ID > App registrations
Click "New registration" to register your app
Give it a name and select the appropriate supported account types
Set the redirect URI if needed for authentication

3. Configure API permissions

In your app registration, go to "API permissions"
Add the necessary Microsoft Graph permissions for Teams functionality (e.g. Chat.ReadWrite, User.Read.All)
Grant admin consent for the permissions

4. Get credentials

Go to "Certificates & secrets" and create a new client secret
Note down the Application (client) ID and client secret - you'll need these to authenticate your app

What can you do with the Microsoft Teams API?

Here are the key data models you can interact with using the Microsoft Teams API, along with what's possible for each:

Teams and Groups

Create, read, update, and delete teams and associated Microsoft 365 groups
Manage team settings, members, and owners
List teams a user is a member of
Archive and unarchive teams
Clone existing teams

Channels

Create, read, update, and delete channels within teams
Manage channel settings and members
Get messages in a channel

Chat and Messages

Send messages to chats and channels
Read, update, and delete messages
Get chat history and thread information
Manage chat participants

Apps and Tabs

Install, upgrade, and uninstall apps in teams
Add, configure, and remove tabs in channels
List apps installed in a team

Calls and Online Meetings

Create, retrieve, and update online meetings
Answer, redirect, and transfer calls
Implement interactive voice response (IVR) scenarios
Get meeting attendance reports

Users and Presence

Get user profile information
Check user presence status
Manage user settings in Teams

Files

Access files shared in teams and channels
Upload, download, and manage file permissions

Shifts and Scheduling

Create and manage shifts and schedules
Handle time off requests
Manage workforce integrations

Education-specific Features

Manage classes, assignments, and grades (for education tenants)

Analytics and Reporting

Get usage reports for Teams
Access insights on user behavior and document trends

The API provides comprehensive access to manage and interact with most aspects of the Teams platform programmatically. The exact capabilities may vary slightly between API versions.