app module

Package:

@microsoft/teams-js

Module to interact with app initialization and lifecycle.

Interfaces

AppHostInfo	Represents information about the application's host.
AppInfo	Represents application information.
ChannelInfo	Represents Channel information.
ChatInfo	Represents Chat information.
Context	Represents structure of the received context message.
IExpectedFailureRequest	Represents the failure request sent during an erroneous app initialization.
IFailedRequest	Represents the failed request sent during a failed app initialization.
MeetingInfo	Represents Meeting information.
NotifySuccessResponse	The response of the notify success callback.
PageInfo	Represents Page information.
SharePointSiteInfo	Represents information about a SharePoint site
TeamInfo	Represents Team information.
TenantInfo	Represents Tenant information.
UserInfo	Represents User information.

Type Aliases

HostToAppPerformanceMetricsHandler	This function is passed to registerHostToAppPerformanceMetricsHandler. It is called every time a response is received from the host with metrics for analyzing message delay. See HostToAppPerformanceMetrics to see which metrics are passed to the handler.
themeHandler	This function is passed to registerOnThemeHandler. It is called every time the user changes their theme.

Enums

ExpectedFailureReason	Describes expected errors that occurred during an otherwise successful app initialization
FailedReason	Describes errors that caused app initialization to fail

Functions

getContext()	Retrieves the current context the frame is running in.
getFrameContext()	Gets the Frame Context that the App is running in. See FrameContexts for the list of possible values.
initialize(string[])	Initializes the library.
isInitialized()	Checks whether the Teams client SDK has been initialized.
notifyAppLoaded()	Notifies the frame that app has loaded and to hide the loading indicator if one is shown.
notifyExpectedFailure(IExpectedFailureRequest)	Notifies the frame that app initialized with some expected errors.
notifyFailure(IFailedRequest)	Notifies the frame that app initialization has failed and to show an error page in its place.
notifySuccess()	Notifies the frame that app initialization is successful and is ready for user interaction.
openLink(string)	This function opens deep links to other modules in the host such as chats or channels or general-purpose links (to external websites). It should not be used for navigating to your own or other apps.
registerHostToAppPerformanceMetricsHandler(HostToAppPerformanceMetricsHandler)	Registers a function for handling data of host to app message delay.
registerOnThemeChangeHandler(themeHandler)	Registers a handler for theme changes.

Function Details

getContext()

Retrieves the current context the frame is running in.

function getContext(): Promise<Context>

Returns

Promise<Context>

Promise that will resolve with the Context object.

getFrameContext()

Gets the Frame Context that the App is running in. See FrameContexts for the list of possible values.

function getFrameContext(): FrameContexts | undefined

Returns

FrameContexts | undefined

the Frame Context.

initialize(string[])

Initializes the library.

function initialize(validMessageOrigins?: string[]): Promise<void>

Parameters

validMessageOrigins

string[]

Optionally specify a list of cross-frame message origins. This parameter is used if you know that your app will be hosted on a custom domain (i.e., not a standard Microsoft 365 host like Teams, Outlook, etc.) Most apps will never need to pass a value for this parameter. Any domains passed in the array must have the https: protocol on the string otherwise they will be ignored. Example: https://www.example.com

Returns

Promise<void>

Promise that will be fulfilled when initialization has completed, or rejected if the initialization fails or times out

Remarks

Initialize must have completed successfully (as determined by the resolved Promise) before any other library calls are made

isInitialized()

Checks whether the Teams client SDK has been initialized.

function isInitialized(): boolean

Returns

boolean

whether the Teams client SDK has been initialized.

notifyAppLoaded()

Notifies the frame that app has loaded and to hide the loading indicator if one is shown.

function notifyAppLoaded()

notifyExpectedFailure(IExpectedFailureRequest)

Notifies the frame that app initialized with some expected errors.

function notifyExpectedFailure(expectedFailureRequest: IExpectedFailureRequest)

Parameters

expectedFailureRequest

IExpectedFailureRequest

The expected failure request containing the reason and an optional message

notifyFailure(IFailedRequest)

Notifies the frame that app initialization has failed and to show an error page in its place.

function notifyFailure(appInitializationFailedRequest: IFailedRequest)

Parameters

appInitializationFailedRequest

IFailedRequest

The failure request containing the reason for why the app failed during initialization as well as an optional message.

notifySuccess()

Notifies the frame that app initialization is successful and is ready for user interaction.

function notifySuccess(): Promise<appHelpers.NotifySuccessResponse>

Returns

Promise<NotifySuccessResponse>

openLink(string)

This function opens deep links to other modules in the host such as chats or channels or general-purpose links (to external websites). It should not be used for navigating to your own or other apps.

function openLink(deepLink: string): Promise<void>

Parameters

deepLink

string

The host deep link or external web URL to which to navigate

Returns

Promise<void>

Promise that will be fulfilled when the navigation has initiated. A successful Promise resolution does not necessarily indicate whether the target loaded successfully.

Remarks

If you need to navigate to your own or other apps, use:

• navigateToDefaultPage for navigating to the default page of your own app
• navigateTo for navigating to a section of your own app
• navigateToApp for navigating to other apps besides your own

Many areas of functionality previously provided by deep links are now handled by strongly-typed functions in capabilities. If your app is using a deep link to trigger these specific components, use the strongly-typed alternatives. For example (this list is not exhaustive):

• To open an app installation dialog, use the appInstallDialog capability
• To start a call, use the call capability
• To open a chat, use the chat capability
• To open a dialog, use the dialog capability
• To create a new meeting, use the composeMeeting function
• To open a Stage View, use the stageView capability

In each of these capabilities, you can use the isSupported() function to determine if the host supports that capability. When using a deep link to trigger these components, there's no way to determine whether the host supports it.

For more information on crafting deep links to the host, see Configure deep links

registerHostToAppPerformanceMetricsHandler(HostToAppPerformanceMetricsHandler)

Registers a function for handling data of host to app message delay.

function registerHostToAppPerformanceMetricsHandler(handler: HostToAppPerformanceMetricsHandler)

Parameters

handler

HostToAppPerformanceMetricsHandler

The handler to invoke when the metrics are available on each function response.

Remarks

Only one handler can be registered at a time. A subsequent registration replaces an existing registration.

registerOnThemeChangeHandler(themeHandler)

Registers a handler for theme changes.

function registerOnThemeChangeHandler(handler: themeHandler)

Parameters

handler

themeHandler

The handler to invoke when the user changes their theme.

Remarks

Only one handler can be registered at a time. A subsequent registration replaces an existing registration.