Integrate web apps with Teams

Do you have a web app you think would fit naturally with Teams' social and collaborative features? These guidelines can help you understand how to integrate the following types of apps:

  • Standalone apps: Could be a single-page app or large, complex app you want people to use some aspects of in Teams.
  • Collaboration apps: An app already built for the social and collaborative features inherent to Teams.
  • SharePoint: A SharePoint page you want to surface in Teams.

For each guideline, you can see if it's applicable to your integration scenario.

Get to know Teams platform capabilities

Integration scenarios: Standalone apps, collaboration apps, SharePoint

Your Teams app can include features users want and might expect when collaborating, but you may be unfamiliar with Teams development terminology.

Common app features Teams platform capabilities
Embedded webpage, homepage, or webview Tabs
Share shortcuts and extensions Messaging extensions
Action shortcuts and extensions Messaging extensions
Chatbots Bots
Channel notifications Bots
Incoming webhooks
Office 365 Connectors
Message external services Bots
Outgoing webhooks
Modals Task modules
Content-rich cards Adaptive Cards

Determine a subset of functionality

Integration scenarios: Standalone apps

Integrating all features of an existing application into Teams often leads to a forced or unnatural user experience, particularly in larger apps. Consider starting with the most impactful features and those that will integrate more naturally with Teams. Remember, you can always allow users to launch the main app and access its full set of features.

Before you begin any technical work, do some planning for your Teams app:

  1. Map your app's use cases to Teams platform capabilities.
  2. Determine your app's entry points. Is it for personal use, collaboration, or both?

Understand SharePoint requirements and options

Integration scenarios: SharePoint

You can integrate an existing SharePoint page as a Teams tab. Remember the following:

  • It must be a modern SharePoint Online page
  • Only personal tabs are supported (you can't integrate your page as a channel tab)

Alternatively, you can build a Teams tab using the SharePoint Framework.

Aim towards multi-tenancy

Integration scenarios: Standalone apps, collaboration apps, SharePoint

If your app is used by multiple organizations, consider multi-tenant hosting that would make your product scalable and greatly simplify distribution.

Review your APIs

Integration scenarios: Standalone apps, collaboration apps

Don't assume your app's existing APIs and data structures fully support the app when integrated with Teams. You might need to augment these with contextual information about Teams for identity mapping, deep-link support, and incorporating Microsoft Graph.

Learn more about getting context for your Teams tab or bot.

Understand authentication options

Integration scenarios: Standalone apps, collaboration apps, SharePoint

Azure Active Directory (AD) is the identity provider for Teams. If your app uses a different identity provider, you must either do an identity mapping exercise or federate with Azure AD.

Teams has single sign-on (SSO) mechanisms with Azure AD for third-party apps and guidance for authentication flows to other identity providers using standards such as OAuth and Open ID Connect (OIDC).

For SharePoint pages, you can only use SSO and can't add another Azure AD ID if you want SSO to work for another app (since the ID is the SharePoint app).

Learn more about authentication in Teams.

Follow Teams design guidelines

Integration scenarios: Standalone apps, collaboration apps

In general, your app should feel natural in Teams. You might think migrating existing app content to a Teams tab is sufficient, but we strongly recommend your app follows Teams design guidelines. See also: Fluent Design System.

Maximize deep linking

Integration scenarios: Standalone apps, collaboration apps, SharePoint

Almost everything in Teams can be linked to directly with a deep link. Your app should maximize use of these, including linking to and from specific messages and tab content. Deep links can really tie together multiple pieces of an app for a more native Teams experience.

Be smart when messaging users

Integration scenarios: Standalone apps, collaboration apps, SharePoint

Consider the types of messages your Teams app might send now and in the long term. If you think your app will ever have a multi-threaded conversation, a bot might offer more flexibility than a webhook.

Bots also allow you to send proactive messages to individual users or channels. These are unprompted messages triggered by an outside event and not a message sent to a bot. (For example, your bot can send a welcome message when it's installed or a new user joins a channel.)

Sending proactive messages requires Teams-specific identifiers—you can capture this information by fetching roster or user profile data, subscribing to conversation events, or using Microsoft Graph.

Be careful not to spam users with excessive messages. If the Teams capability supports it, consider letting users configure notification settings for your app (for example, "Don't send me unprompted messages.").

Use SharePoint for file and data storage

Integration scenarios: Standalone apps, collaboration apps, SharePoint pages

When a team is created, a SharePoint site collection is also provisioned to support file and data storage for that team. Your app can and should leverage this feature if it interacts with files. You can also use the site collection to store raw data in SharePoint Lists and Excel.