microsoftTeams module

Reference

Package:: @microsoft/teams-js

Classes

ChildAppWindow
Communication
GlobalVars
ParentAppWindow

Interfaces

Context
DeepLinkParameters
FrameContext
IAppWindow
LocaleInfo	Represents OS locale info used for formatting date and time data
MessageRequest
MessageResponse
SdkError
ShowNotificationParameters
TabInformation	Represents information about tabs for an app
TabInstance	Represents information about a tab instance
TabInstanceParameters	Indicates information about the tab instance for filtering purposes.
TaskInfo
TeamInformation	Represents Team Information

Enums

ChannelType	The type of the channel with which the content is associated.
ErrorCode
FileOpenPreference	Allowed user file open preferences
FrameContexts
HostClientType
NotificationTypes
TaskModuleDimension	Task module dimension enum
TeamType	Indicates the team type, currently used to distinguish between different team types in Office 365 for Education (team types 1, 2, 3, and 4).
UserTeamRole	Indicates the various types of roles of a user in a team.

Functions

callHandler(string, any[])
compareSDKVersions(string, string)	Compares SDK versions. *
createFile(AssembleAttachment[], string)	Helper function to create a blob from media chunks based on their sequence.
decodeAttachment(MediaChunk, string)	Helper function to convert Media chunks into another object type which can be later assemebled Converts base 64 encoded string to byte array and then into an array of blobs.
enablePrintCapability()	Enable print capability to support printing page using Ctrl+P and cmd+P
ensureInitialized(string[])
executeDeepLink(string, (status: boolean, reason?: string) => void)	execute deep link API.
generateGUID()	Generates a GUID
generateRegExpFromUrls(string[])
getContext((context: Context) => void)	Retrieves the current context the frame is running in.
getGenericOnCompleteHandler(string)
getMruTabInstances((tabInfo: TabInformation) => void, TabInstanceParameters)	Allows an app to retrieve the most recently used tabs for this user.
getTabInstances((tabInfo: TabInformation) => void, TabInstanceParameters)	Allows an app to retrieve for this user tabs that are owned by this app. If no TabInstanceParameters are passed, the app defaults to favorite teams and favorite channels.
handleThemeChange(string)
initialize(() => void, string[])	Initializes the library. This must be called before any other SDK calls but after the frame is loaded successfully.
initializeCommunication(Function, undefined \| string[])
initializeHandlers()
initializePrivateApis()
initializeWithFrameContext(FrameContext, () => void, string[])
isAPISupportedByPlatform(string)	Checks whether the platform has knowledge of this API by doing a comparison on API required version and platform supported version of the SDK.
isApiSupportedOnMobile(string)	Helper function which indicates if current API is supported on mobile or not.
isHostClientMobile()	Helper function to identify if host client is either android or ios
isMediaCallForImageOutputFormats(MediaInputs)	Returns true if the mediaInput params are called for mediatype Image and contains Image outputs formats, false otherwise.
isMediaCallForNonFullScreenVideoMode(MediaInputs)	Returns true if the mediaInput params are called for non-full screen video mode and false otherwise.
isMediaCallForVideoAndImageInputs(MediaInputs)	Returns true if the mediaInput params are called for mediatype VideoAndImage and false otherwise.
isMediaCallSupportedOnMobile(MediaInputs)	Function returns null if the media call is supported on current mobile version, else SdkError.
isVideoControllerRegistered(MediaInputs)	Function returns true if the app has registered to listen to video controller events, else false.
navigateBack((status: boolean, reason?: string) => void)	Navigates back in the Teams client. See registerBackButtonHandler for more information on when it's appropriate to use this method.
navigateCrossDomain(string, (status: boolean, reason?: string) => void)	Navigates the frame to a new cross-domain URL. The domain of this URL must match at least one of the valid domains specified in the validDomains block of the manifest; otherwise, an exception will be * thrown. This function needs to be used only when navigating the frame to a URL in a different domain than the current one in a way that keeps the app informed of the change and allows the SDK to continue working. *
navigateToTab(TabInstance, (status: boolean, reason?: string) => void)	Navigates the Microsoft Teams app to the specified tab instance. *
print()	default print handler
processAdditionalValidOrigins(string[])	Processes the valid origins specifuied by the user, de-duplicates and converts them into a regexp which is used later for message source/origin validation.
registerAppButtonClickHandler(() => void)	Registers a handler for clicking the app button. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
registerAppButtonHoverEnterHandler(() => void)	Registers a handler for entering hover of the app button. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
registerAppButtonHoverLeaveHandler(() => void)	Registers a handler for exiting hover of the app button. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
registerBackButtonHandler(() => boolean)
registerBackButtonHandler(() => boolean)	Registers a handler for user presses of the Team client's back button. Experiences that maintain an internal navigation stack should use this handler to navigate the user back within their frame. If an app finds * that after running its back button handler it cannot handle the event it should call the navigateBack method to ask the Teams client to handle it instead.
registerChangeSettingsHandler(() => void)	Registers a handler for when the user reconfigurated tab *
registerFullScreenHandler((isFullScreen: boolean) => void)	Registers a handler for changes from or to full-screen view for a tab. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
registerHandler(string, Function, boolean, any[])
registerOnThemeChangeHandler((theme: string) => void)
registerOnThemeChangeHandler((theme: string) => void)	Registers a handler for theme changes. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
removeHandler(string)
returnFocus(boolean)	Return focus to the main Teams app. Will focus search bar if navigating forward and app bar if navigating back.
sendMessageEventToChild(string, any[])	Send a custom message object that can be sent to child window, * instead of a response message to a child.
sendMessageToParent(string, any[], Function)	Send a message to parent. Uses nativeInterface on mobile to communicate with parent context.
sendMessageToParent(string, Function)	Send a message to parent. Uses nativeInterface on mobile to communicate with parent context.
setFrameContext(FrameContext)
shareDeepLink(DeepLinkParameters)	Shares a deep link that a user can use to navigate back to a specific state in this page.
uninitializeCommunication()
validateGetMediaInputs(string, FileFormat, string)	Returns true if the get Media params are valid and false otherwise
validatePeoplePickerInput(PeoplePickerInputs)	Returns true if the people picker params are valid and false otherwise
validateScanBarCodeInput(BarCodeConfig)	Returns true if the scan barcode param is valid and false otherwise
validateSelectMediaInputs(MediaInputs)	Returns true if the mediaInput params are valid and false otherwise
validateViewImagesInput(ImageUri[])	Returns true if the view images param is valid and false otherwise
waitForMessageQueue(Window, () => void)

Function Details

callHandler(string, any[])

function callHandler(name: string, args?: any[]): [true, any] | [false, undefined]

Parameters

name: string

args: any[]

Returns

[true, any] | [false, undefined]

compareSDKVersions(string, string)

Compares SDK versions. *

function compareSDKVersions(v1: string, v2: string): number

Parameters

v1: string

first version *

v2: string

second version returns NaN in case inputs are not in right format, -1 if v1 < v2, 1 if v1 > v2, 0 otherwise. For example, compareSDKVersions('1.2', '1.2.0') returns 0 compareSDKVersions('1.2a', '1.2b') returns NaN compareSDKVersions('1.2', '1.3') returns -1 compareSDKVersions('2.0', '1.3.2') returns 1 compareSDKVersions('2.0', 2.0) returns NaN

Returns

number

createFile(AssembleAttachment[], string)

Helper function to create a blob from media chunks based on their sequence.

function createFile(assembleAttachment: AssembleAttachment[], mimeType: string): Blob

Parameters

assembleAttachment: @microsoft/teams-js.@microsoft.teams-js.media.AssembleAttachment[]

mimeType: string

Returns

Blob

decodeAttachment(MediaChunk, string)

Helper function to convert Media chunks into another object type which can be later assemebled Converts base 64 encoded string to byte array and then into an array of blobs.

function decodeAttachment(attachment: MediaChunk, mimeType: string): media.AssembleAttachment

Parameters

attachment: @microsoft/teams-js.@microsoft.teams-js.media.MediaChunk

mimeType: string

Returns

@microsoft/teams-js.@microsoft.teams-js.media.AssembleAttachment

enablePrintCapability()

Enable print capability to support printing page using Ctrl+P and cmd+P

function enablePrintCapability()

ensureInitialized(string[])

function ensureInitialized(expectedFrameContexts: string[])

Parameters

expectedFrameContexts: string[]

executeDeepLink(string, (status: boolean, reason?: string) => void)

execute deep link API.

function executeDeepLink(deepLink: string, onComplete?: (status: boolean, reason?: string) => void)

Parameters

deepLink: string

deep link.

onComplete: (status: boolean, reason?: string) => void

generateGUID()

Generates a GUID

function generateGUID(): string

Returns

string

generateRegExpFromUrls(string[])

function generateRegExpFromUrls(urls: string[]): RegExp

Parameters

urls: string[]

Returns

RegExp

getContext((context: Context) => void)

Retrieves the current context the frame is running in.

function getContext(callback: (context: Context) => void)

Parameters

callback: (context: Context) => void

The callback to invoke when the Context object is retrieved.

getGenericOnCompleteHandler(string)

function getGenericOnCompleteHandler(errorMessage?: string): (success: boolean, reason?: string) => void

Parameters

errorMessage: string

Returns

(success: boolean, reason?: string) => void

getMruTabInstances((tabInfo: TabInformation) => void, TabInstanceParameters)

Allows an app to retrieve the most recently used tabs for this user.

function getMruTabInstances(callback: (tabInfo: TabInformation) => void, tabInstanceParameters?: TabInstanceParameters)

Parameters

callback: (tabInfo: TabInformation) => void

The callback to invoke when the TabInformation object is retrieved. *

tabInstanceParameters: @microsoft/teams-js.@microsoft.teams-js.TabInstanceParameters

OPTIONAL Ignored, kept for future use

getTabInstances((tabInfo: TabInformation) => void, TabInstanceParameters)

Allows an app to retrieve for this user tabs that are owned by this app. If no TabInstanceParameters are passed, the app defaults to favorite teams and favorite channels.

function getTabInstances(callback: (tabInfo: TabInformation) => void, tabInstanceParameters?: TabInstanceParameters)

Parameters

callback: (tabInfo: TabInformation) => void

The callback to invoke when the TabInstanceParameters object is retrieved. *

tabInstanceParameters: @microsoft/teams-js.@microsoft.teams-js.TabInstanceParameters

OPTIONAL Flags that specify whether to scope call to favorite teams or channels.

handleThemeChange(string)

function handleThemeChange(theme: string)

Parameters

theme: string

initialize(() => void, string[])

Initializes the library. This must be called before any other SDK calls but after the frame is loaded successfully.

function initialize(callback?: () => void, validMessageOrigins?: string[])

Parameters

callback: () => void

Optionally specify a callback to invoke when Teams SDK has successfully initialized

validMessageOrigins: string[]

Optionally specify a list of cross frame message origins. There must have https: protocol otherwise they will be ignored. Example: https://www.example.com

initializeCommunication(Function, undefined | string[])

function initializeCommunication(callback: Function, validMessageOrigins: undefined | string[])

Parameters

callback: Function

validMessageOrigins: undefined | string[]

initializeHandlers()

function initializeHandlers()

initializePrivateApis()

function initializePrivateApis()

initializeWithFrameContext(FrameContext, () => void, string[])

function initializeWithFrameContext(frameContext: FrameContext, callback?: () => void, validMessageOrigins?: string[])

Parameters

frameContext: @microsoft/teams-js.@microsoft.teams-js.FrameContext

callback: () => void

validMessageOrigins: string[]

isAPISupportedByPlatform(string)

Checks whether the platform has knowledge of this API by doing a comparison on API required version and platform supported version of the SDK.

function isAPISupportedByPlatform(requiredVersion?: string): boolean

Parameters

requiredVersion: string

SDK version required by the API

Returns

boolean

isApiSupportedOnMobile(string)

Helper function which indicates if current API is supported on mobile or not.

function isApiSupportedOnMobile(requiredVersion?: string): SdkError

Parameters

requiredVersion: string

Returns

@microsoft/teams-js.@microsoft.teams-js.SdkError

SdkError if host client is not android/ios or if the requiredVersion is not supported by platform or not. Null is returned in case of success.

isHostClientMobile()

Helper function to identify if host client is either android or ios

function isHostClientMobile(): boolean

Returns

boolean

isMediaCallForImageOutputFormats(MediaInputs)

Returns true if the mediaInput params are called for mediatype Image and contains Image outputs formats, false otherwise.

function isMediaCallForImageOutputFormats(mediaInputs: MediaInputs): boolean

Parameters

mediaInputs: @microsoft/teams-js.@microsoft.teams-js.media.MediaInputs

Returns

boolean

isMediaCallForNonFullScreenVideoMode(MediaInputs)

Returns true if the mediaInput params are called for non-full screen video mode and false otherwise.

function isMediaCallForNonFullScreenVideoMode(mediaInputs: MediaInputs): boolean

Parameters

mediaInputs: @microsoft/teams-js.@microsoft.teams-js.media.MediaInputs

Returns

boolean

isMediaCallForVideoAndImageInputs(MediaInputs)

Returns true if the mediaInput params are called for mediatype VideoAndImage and false otherwise.

function isMediaCallForVideoAndImageInputs(mediaInputs: MediaInputs): boolean

Parameters

mediaInputs: @microsoft/teams-js.@microsoft.teams-js.media.MediaInputs

Returns

boolean

isMediaCallSupportedOnMobile(MediaInputs)

Function returns null if the media call is supported on current mobile version, else SdkError.

function isMediaCallSupportedOnMobile(mediaInputs: MediaInputs): SdkError

Parameters

mediaInputs: @microsoft/teams-js.@microsoft.teams-js.media.MediaInputs

Returns

@microsoft/teams-js.@microsoft.teams-js.SdkError

isVideoControllerRegistered(MediaInputs)

Function returns true if the app has registered to listen to video controller events, else false.

function isVideoControllerRegistered(mediaInputs: MediaInputs): boolean

Parameters

mediaInputs: @microsoft/teams-js.@microsoft.teams-js.media.MediaInputs

Returns

boolean

navigateBack((status: boolean, reason?: string) => void)

Navigates back in the Teams client. See registerBackButtonHandler for more information on when it's appropriate to use this method.

function navigateBack(onComplete?: (status: boolean, reason?: string) => void)

Parameters

onComplete: (status: boolean, reason?: string) => void

navigateCrossDomain(string, (status: boolean, reason?: string) => void)

Navigates the frame to a new cross-domain URL. The domain of this URL must match at least one of the valid domains specified in the validDomains block of the manifest; otherwise, an exception will be * thrown. This function needs to be used only when navigating the frame to a URL in a different domain than the current one in a way that keeps the app informed of the change and allows the SDK to continue working. *

function navigateCrossDomain(url: string, onComplete?: (status: boolean, reason?: string) => void)

Parameters

url: string

The URL to navigate the frame to.

onComplete: (status: boolean, reason?: string) => void

navigateToTab(TabInstance, (status: boolean, reason?: string) => void)

Navigates the Microsoft Teams app to the specified tab instance. *

function navigateToTab(tabInstance: TabInstance, onComplete?: (status: boolean, reason?: string) => void)

Parameters

tabInstance: @microsoft/teams-js.@microsoft.teams-js.TabInstance

The tab instance to navigate to.

onComplete: (status: boolean, reason?: string) => void

print()

default print handler

function print()

processAdditionalValidOrigins(string[])

Processes the valid origins specifuied by the user, de-duplicates and converts them into a regexp which is used later for message source/origin validation.

function processAdditionalValidOrigins(validMessageOrigins: string[])

Parameters

validMessageOrigins: string[]

registerAppButtonClickHandler(() => void)

Registers a handler for clicking the app button. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.

function registerAppButtonClickHandler(handler: () => void)

Parameters

handler: () => void

The handler to invoke when the personal app button is clicked in the app bar.

registerAppButtonHoverEnterHandler(() => void)

Registers a handler for entering hover of the app button. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.

function registerAppButtonHoverEnterHandler(handler: () => void)

Parameters

handler: () => void

The handler to invoke when entering hover of the personal app button in the app bar.

registerAppButtonHoverLeaveHandler(() => void)

Registers a handler for exiting hover of the app button. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.

function registerAppButtonHoverLeaveHandler(handler: () => void)

Parameters

handler: () => void

The handler to invoke when exiting hover of the personal app button in the app bar.

registerBackButtonHandler(() => boolean)

function registerBackButtonHandler(handler: () => boolean)

Parameters

handler: () => boolean

registerBackButtonHandler(() => boolean)

Registers a handler for user presses of the Team client's back button. Experiences that maintain an internal navigation stack should use this handler to navigate the user back within their frame. If an app finds * that after running its back button handler it cannot handle the event it should call the navigateBack method to ask the Teams client to handle it instead.

function registerBackButtonHandler(handler: () => boolean)

Parameters

handler: () => boolean

The handler to invoke when the user presses their Team client's back button.

registerChangeSettingsHandler(() => void)

Registers a handler for when the user reconfigurated tab *

function registerChangeSettingsHandler(handler: () => void)

Parameters

handler: () => void

The handler to invoke when the user click on Settings.

registerFullScreenHandler((isFullScreen: boolean) => void)

Registers a handler for changes from or to full-screen view for a tab. Only one handler can be registered at a time. A subsequent registration replaces an existing registration.

function registerFullScreenHandler(handler: (isFullScreen: boolean) => void)

Parameters

handler: (isFullScreen: boolean) => void

The handler to invoke when the user toggles full-screen view for a tab.

registerHandler(string, Function, boolean, any[])

function registerHandler(name: string, handler: Function, sendMessage?: boolean, args?: any[])

Parameters

name: string

handler: Function

sendMessage: boolean

args: any[]

registerOnThemeChangeHandler((theme: string) => void)

function registerOnThemeChangeHandler(handler: (theme: string) => void)

Parameters

handler: (theme: string) => void

registerOnThemeChangeHandler((theme: string) => void)

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

function registerOnThemeChangeHandler(handler: (theme: string) => void)

Parameters

handler: (theme: string) => void

The handler to invoke when the user changes their theme.

removeHandler(string)

function removeHandler(name: string)

Parameters

name: string

returnFocus(boolean)

Return focus to the main Teams app. Will focus search bar if navigating forward and app bar if navigating back.

function returnFocus(navigateForward?: boolean)

Parameters

navigateForward: boolean

Determines the direction to focus in teams app.

sendMessageEventToChild(string, any[])

Send a custom message object that can be sent to child window, * instead of a response message to a child.

function sendMessageEventToChild(actionName: string, args?: any[])

Parameters

actionName: string

args: any[]

sendMessageToParent(string, any[], Function)

Send a message to parent. Uses nativeInterface on mobile to communicate with parent context.

function sendMessageToParent(actionName: string, args: any[], callback?: Function)

Parameters

actionName: string

args: any[]

callback: Function

sendMessageToParent(string, Function)

Send a message to parent. Uses nativeInterface on mobile to communicate with parent context.

function sendMessageToParent(actionName: string, callback?: Function)

Parameters

actionName: string

callback: Function

setFrameContext(FrameContext)

function setFrameContext(frameContext: FrameContext)

Parameters

frameContext: @microsoft/teams-js.@microsoft.teams-js.FrameContext

shareDeepLink(DeepLinkParameters)

Shares a deep link that a user can use to navigate back to a specific state in this page.

function shareDeepLink(deepLinkParameters: DeepLinkParameters)

Parameters

deepLinkParameters: @microsoft/teams-js.@microsoft.teams-js.DeepLinkParameters

ID and label for the link and fallback URL.

uninitializeCommunication()

function uninitializeCommunication()

validateGetMediaInputs(string, FileFormat, string)

Returns true if the get Media params are valid and false otherwise

function validateGetMediaInputs(mimeType: string, format: FileFormat, content: string): boolean

Parameters

mimeType: string

format: @microsoft/teams-js.@microsoft.teams-js.media.FileFormat

content: string

Returns

boolean

validatePeoplePickerInput(PeoplePickerInputs)

Returns true if the people picker params are valid and false otherwise

function validatePeoplePickerInput(peoplePickerInputs: PeoplePickerInputs): boolean

Parameters

peoplePickerInputs: @microsoft/teams-js.@microsoft.teams-js.people.PeoplePickerInputs

Returns

boolean

validateScanBarCodeInput(BarCodeConfig)

Returns true if the scan barcode param is valid and false otherwise

function validateScanBarCodeInput(barCodeConfig: BarCodeConfig): boolean

Parameters

barCodeConfig: @microsoft/teams-js.@microsoft.teams-js.media.BarCodeConfig

Returns

boolean

validateSelectMediaInputs(MediaInputs)

Returns true if the mediaInput params are valid and false otherwise

function validateSelectMediaInputs(mediaInputs: MediaInputs): boolean

Parameters

mediaInputs: @microsoft/teams-js.@microsoft.teams-js.media.MediaInputs

Returns

boolean

validateViewImagesInput(ImageUri[])

Returns true if the view images param is valid and false otherwise

function validateViewImagesInput(uriList: ImageUri[]): boolean

Parameters

uriList: @microsoft/teams-js.@microsoft.teams-js.media.ImageUri[]

Returns

boolean

waitForMessageQueue(Window, () => void)

function waitForMessageQueue(targetWindow: Window, callback: () => void)

Parameters

targetWindow: Window

callback: () => void