Building tabs and other hosted experiences with the Microsoft Teams JavaScript client SDK

The Microsoft Teams JavaScript client SDK can help you create hosted experiences in Teams, which means displaying your app content in an iframe.

The SDK is helpful for developing apps with any of the following Teams capabilities:

For example, the SDK can make your tab react to theme changes your users make in the Teams client.

Getting started

Do one of the following depending on your development preferences:

Common SDK functions

See the following tables to understand commonly used SDK functions. The SDK reference documentation provides more comprehensive information.

Basic functions

Function Description Documentation
microsoftTeams.initialize() Initializes the SDK. This function must be called before any other SDK calls. function
microsoftTeams.getContext(callback: (context: Context) Gets the current state in which the page is running. The callback retrieves the Context object. function
context obj
microsoftTeams.initializeWithContext({contentUrl: string, websiteUrl: string}) Initializes the Teams library and sets the tab's frame context depending on the contentUrl and websiteUrl. This ensures the go-to-website/reload functionality operates on the correct URL. function
microsoftTeams.setFrameContext({contentUrl: string, websiteUrl: string}) Sets the tab's frame context depending on the contentUrl and websiteUrl. This ensures the go-to-website/reload functionality operates on the correct URL. function
microsoftTeams.registerFullScreenHandler(handler: (isFullScreen: boolean) The handler that is registered when the user toggles a tab's full-screen/windowed view. function
boolean
microsoftTeams.registerChangeSettingsHandler() The handler that is registered when the user selects the enabled Settings button to reconfigure a tab. function
microsoftTeams.getTabInstances(callback: (tabInfo: TabInformation),tabInstanceParameters?: TabInstanceParameters,) Gets the tabs owned by the app. The callback retrieves the TabInformation object. The TabInstanceParameters object is an optional parameter. function
tabInfo obj
microsoftTeams.getMruTabInstances(callback: (tabInfo: TabInformation),tabInstanceParameters?: TabInstanceParameters) Gets the most recently used tabs for the user. The callback retrieves the TabInformation object. The TabInstanceParameters object is an optional parameter. function
tabInfo obj
tabInstance obj
microsoftTeams.shareDeepLink(deepLinkParameters: DeepLinkParameters) Takes the DeepLinkParameters object as input and shares a deep link dialog box that a user can use to navigate to content within the tab. function
deepLink obj
microsoftTeams.executeDeepLink(deepLink: string, onComplete?: (status: boolean, reason?: string)) Takes a required deepLink as input and navigates user to a URL or triggers a client action—such as opening or installing—an app within Teams. function
microsoftTeams.navigateToTab(tabInstance: TabInstance, onComplete?: (status: boolean, reason?: string)) Takes the TabInstance object as input and navigates to a specified tab instance. function
tabInstance obj

Authentication namespace

Function Description Documentation
microsoftTeams.authentication.authenticate(authenticateParameters?: AuthenticateParameters) Initiates an authentication request that opens a new window with the parameters provided by the caller. Optional input values are defined by the AuthenticateParameters object. function
auth obj
microsoftTeams.authentication.notifySuccess(result?: string, callbackUrl?: string) Notifies the frame that initiated the authentication request that the request was successful and closes the authentication window function
microsoftTeams.authentication.notifyFailure(reason?: string, callbackUrl?: string) Notifies the frame that initiated the authentication request that the request failed and closes the authentication window. function

Settings namespace

Function Description Documentation
microsoftTeams.settings.setValidityState(validityState: boolean) The initial value is false. Activates the Save or Remove button when the validity state is true. function
microsoftTeams.settings.getSettings(callback: (instanceSettings: Settings) Gets the settings for the current instance. The callback retrieves the Settings object. function
settings obj
microsoftTeams.settings.setSettings(instanceSettings: Settings, onComplete?: (status: boolean, reason?: string) Configures the settings for the current instance. Valid settings are defined by the Settings object. function
settings obj
microsoftTeams.settings.registerOnSaveHandler(handler: (evt: SaveEvent) The handler that is registered when the user selects the Save button. This handler should be used to create or update the underlying resource powering the content. function
microsoftTeams.settings.registerOnRemoveHandler(handler: (evt: RemoveEvent) The handler that is registered when the user selects the Remove button. This handler should be used to remove the underlying resource powering the content. function

Task modules namespace

Function Description Documentation
microsoftTeams.tasks.startTask(taskInfo: TaskInfo, submitHandler?: (err: string, result: string) Takes the TaskInfo object as input and allows an app to open the task module. The optional submitHandler is registered when the task module is completed. function
taskInfo obj
microsoftTeams.tasks.submitTask(result?: string | object, appIds?: string | string[]) Submits the task module. The optional result string parameter is the result sent to the bot or the app and is typically a JSON object or serialization; The optional appIds string or string array parameter aids in validating that the call originated from the same appId as the one that invoked the task module. function