Table of contents

Create the configuration page for your Microsoft Teams (preview) tab

Richard Taylor|Last Updated: 2/7/2017
2 Contributors

The configuration page is an HTML page that you host. When a user chooses to add - or update - your tab, Microsoft Teams will load the 'configUrl' (that you provided in your manifest) within an iframe inside the Add Tab dialog.

In this page, you present options and gather information from the user about what they want in your tab. For example, you may let the user select existing app resources (such as files or task lists) or even create new such resources just for this tab.

You must include the Microsoft Teams Tab library in your configuration page so that it can communicate with Microsoft Teams.

Note: the example here is solely to illustrate the concept. Your configuration page should have a clean UI that fits with the look and feel of the Microsoft Teams dialog in which it sits.

"Screenshot of the configuration page for a simple example app, giving the user the option of which map type to select."

Configuration page example

The excerpt below shows an example configuration page.

In this case, the user is presented with two radio buttons, which represent a choice of two different resources. Selecting either radio button fires onClick(), which sets microsoftTeams.settings.setValidityState(true), enabling the Save button.

On save, the code determines which radio button was checked, and sets the various parameters of microsoftTeams.settings.setSettings accordingly. Finally, it calls saveEvent.notifySuccess() to specify that the content URL has successfully been determined.

With this as a simple example, let's walk through the steps your configuration page needs to perform to load your tab content.

  <input type="radio" name="maptype" value="bing" onclick="onClick()"> Bing Maps<br>
  <input type="radio" name="maptype" value="google" onclick="onClick()"> Google Maps

<script src=""></script>

<script type="text/javascript">  


    var radios = document.getElementsByName("maptype");
    if (radios[0].checked) {
         entityId: "bing"
         contentUrl: "",
         suggestedDisplayName: "Bing Map",
         websiteUrl: "",
         removeUrl: "",
    } else {
         entityId: "google"
         contentUrl: "",
         suggestedDisplayName: "Google Map",
         websiteUrl: "",
         removeUrl: "",


function onClick() {


Prerequisites for your configuration page

For your configuration page to display within Microsoft Teams, make sure it meets the requirements for tab pages.

In summary: you must host your page on a secure https:// endpoint, ensure your page permits itself to be iframed, include the Microsoft Teams tab library, and call microsoftTeams.initialize();

Collecting user information

Your configuration page needs to perform the following steps:

Obtain context and authenticate

If your page requires context about the user or environment, see Get context information. If it needs to authenticate the user, see Authenticating in your Microsoft Teams tab pages.

Determine when the user has specified all required information

By default, the Save button on the configuration dialog box is disabled. When the user has selected or entered all the required information for your app, you can enable the Save button by calling microsoftTeams.settings.setValidityState(true).

Determine the content to display in the tab

Use microsoftTeams.settings.setSettings({entityId, contentUrl, suggestedTabName, websiteUrl, removeUrl}) to specify the URL of the content page Microsoft Teams should host in the tab. Things to keep in mind:

  • This call may be made at any time the configuration page is displayed, including before or after the user selects the Save button (see below).
  • The entityID uniquely identifies the item that is displayed in the tab.
  • The contentUrl is a required field which specifies the URL of the content Microsoft Teams should host in the tab.
  • The other parameters further customize how your tab works in Microsoft Teams:
    • The optional suggestedTabName parameter sets the initial tab name. Users can rename the tab. The default value is the name specified in the manifest.
    • The optional websiteUrl parameter sets where the user is taken if they click the Go to website button. Typically, this is a link to the same content as displayed on the tab, but within your main web app with its regular chrome and navigation.
    • The optional removeUrl parameter sets the URL for your removal options page.

React when the user clicks the Save button

Often you may not be able to determine the entityId or contentUrl immediately. For example, you may first need create a new resource (a document or a task), and you only want to do this once the user selects Save. To be notified when the user selects Save, you must call microsoftTeams.settings.registerOnSaveHandler(function(saveEvent) { /* ... */ }). Once this is done, when the user selects Save, Microsoft Teams calls the save event handler you registered.

You can return the settings asynchronously if, for example, the user has requested a new resource which will take time for you to create. To do this, store saveEvent for later. If you do not notify the outcome within 30 seconds, Microsoft Teams terminates the operation and displays an error.

Return success or failure result

Finally, in your save handler registered previously, call saveEvent.notifySuccess() or saveEvent.notifyFailure() to notify Microsoft Teams on the outcome of the configuration. If you have no save handler registered, the outcome will immediately and implicitly be success.

Hitting problems? See the troubleshooting guide.

Next Step

© 2017 Microsoft