Explore tab development

  • 4 minutes

There are several options for implementing tabs in Microsoft Teams. In this unit, you'll learn the requirements and core concepts related to building tabs for Microsoft Teams.

Declare your tab

To create a custom tab, it needs to be declared in the app manifest of your app package. For each webpage you want included as a tab in your app, you define a URL and a scope.

When you use Teams Toolkit to build your tab, Teams Toolkit will automatically generate an app manifest for your project using environment variables to streamline development.

Tab scope

Teams determines where a tab can be used based on its scope. Scope is set in the app manifest and can be one of three values:

  • team: For channel tabs. When these tabs are added to a team, a user configures the content of your tab experience when the tab is first added to a channel.

  • groupchat: For tabs that can be accessed in group chats. These are conversations between two or more users.

  • personal: For personal tabs that are only relevant to individual users.

For example, the following code defines a static tab that can be accessed as a personal app:

    "staticTabs": [
        {
            "entityId": "index0",
            "name": "Personal Tab",
            "contentUrl": "${{TAB_ENDPOINT}}/index.html#/tab",
            "websiteUrl": "${{TAB_ENDPOINT}}/index.html#/tab",
            "scopes": [
                "personal"
            ]
        }
    ],

Define the content URL

For static tabs, the content URL is defined in your Teams app manifest using the contentUrl property in the staticTabs array. Your static tab's content is the same for all users.

For channel or group tabs, you can also create an extra configuration page. This page allows users to configure the content page URL, typically by using URL query string parameters to load the appropriate content for that context. This is because your channel or group tab can be added to multiple teams or group chats. On each subsequent install, your users can configure the tab, allowing you to tailor the experience as required. When users add or configure a tab, a URL is associated with the tab that is presented in the Teams user interface. Configuring a tab simply adds more parameters to that URL. For example, when a user adds the Azure Boards tab, the configuration page allows them to choose which board the tab loads.

To specify the configuration page URL, define the configurationUrl property in the configurableTabs array in your app manifest.

For example, the following code defines a configurable tab that can be accessed in channels and group chats and defines the configuration URL:

 microsoftTeams.app.initialize().then(function () {
    microsoftTeams.app.getContext().then(function (context) {
      if (context?.app?.host?.name) {
        updateHubState(context.app.host.name);
      }
    });
  });

Visit Create a configuration page to learn more.

Implement your tab

Your tab will need to present an HTML page in an <iframe>. This page will be displayed in Teams as your tab content. You can include any valid web content in this page.

Use the Microsoft Teams JavaScript client SDK

To enable your tab to interact with Teams, you'll need to include the Microsoft Teams JavaScript client SDK in your project. After your page loads, call microsoftTeams.initialize() to initialize the SDK.

For example, the following code initializes the SDK before using it to retrieve tab context:

 microsoftTeams.app.initialize().then(function () {
    microsoftTeams.app.getContext().then(function (context) {
      if (context?.app?.host?.name) {
        updateHubState(context.app.host.name);
      }
    });
  });