Previous

Next

Get context in Teams tab

Completed

Your tab requires contextual information to display relevant content. In this unit you'll learn how to get context for your tab.

Overview of user context

Your tab can use contextual information to display relevant content, such as:

• Basic information about the user, team, or company.
• Locale and theme information.
• The page.id and page.subPageId that identify what is in the tab (known as entityId and subEntityId prior to TeamsJS v.2.0.0).

Context about the user, team, or company can be especially useful when:

• You create or associate resources in your app with the specified user or team.
• You initiate an authentication flow from Microsoft Entra ID or other identity provider, and you don't require the user to enter their username again.

Get context

You can access context information in two ways:

• Using URL placeholder values.
• From the Microsoft Teams JavaScript client library context object.

Get context by inserting URL placeholder values

Use placeholders in your configuration or content URLs. Microsoft Teams replaces the placeholders with the relevant values when determining the actual configuration or content URL. The available placeholders include all fields on the context object. Common placeholders include the following properties:

• {page.id}: The developer-defined unique ID for the page defined when first configuring the page. (Known as {entityId} prior to TeamsJS v.2.0.0).
• {page.subPageId}: The developer-defined unique ID for the subpage this content points defined when generating a deep link for a specific item within the page. (Known as {subEntityId} prior to TeamsJS v.2.0.0).
• {user.loginHint}: A value suitable as a sign in hint for Microsoft Entra ID. This is usually the login name of the current user in their home tenant. (Known as {loginHint} prior to TeamsJS v.2.0.0).
• {user.userPrincipalName}: The User Principal Name of the current user in the current tenant. (Known as {userPrincipalName} prior to TeamsJS v.2.0.0).
• {user.id}: The Microsoft Entra object ID of the current user in the current tenant. (Known as {userObjectId} prior to TeamsJS v.2.0.0).
• {app.theme}: The current user interface (UI) theme such as default, dark, or contrast. (Known as {theme} prior to TeamsJS v.2.0.0).
• {team.groupId}: The ID of the Microsoft 365 group in which the tab resides. (Known as {groupId} prior to TeamsJS v.2.0.0)
• {user.tenant.id}: The Microsoft Entra tenant ID of the current user. (Known as {tid} prior to TeamsJS v.2.0.0).
• {app.locale}: The current locale of the user formatted as languageId-countryId, for example en-us. (Known as {locale} prior to TeamsJS v.2.0.0).

Get context by using the Microsoft Teams JavaScript library

You can also retrieve the context information using the Microsoft Teams JavaScript client library. For example, the following code retrieves the name of the host that is running the app:

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

    function updateHubState(hubName) {
        /*...*/
    }
    ...

The following code provides an example of the context object:

{
 "app": {
   "host": {
     "clientType": "The type of host client. Possible values are android, ios, web, desktop, surfaceHub, teamsRoomsAndroid, teamsPhones, teamsDisplays rigel (deprecated, use teamsRoomsWindows instead)",
     "name": "",
     "ringId": "The current ring ID",
     "sessionId": "The unique ID for the current Teams session for use in correlating telemetry data"    },
   "iconPositionVertical": "",
   "locale": "The current locale of the user formatted as languageId-countryId (for example, en-us)",
   "osLocaleInfo": "",
   "parentMessageId": "The parent message ID from which this dialog is launched",
   "sessionId": "The unique ID for the current session used for correlating telemetry data",
   "theme": "The current UI theme: default | dark | contrast",
   "userClickTime": "",
   "userFileOpenPreference": ""  },
 "channel": {
   "defaultOneNoteSectionId": "The OneNote section ID that is linked to the channel",
   "displayName": "The name of the current channel",
   "id": "The channel ID in the format 19:[id]@thread.skype",
   "membershipType": "",
   "ownerGroupId": "",
   "ownerTenantId": "",
   "relativeUrl": "The relative path to the SharePoint folder associated with the channel"  },
 "chat": { "id": "The chat ID in the format 19:[id]@thread.skype" },
 "meeting": {
   "id": "The meeting ID used by tab when running in meeting context"  },
 "page": {
   "frameContext": "The context where tab URL is loaded (for example, content, task, setting, remove, sidePanel)",
   "id": "The developer-defined unique ID for the entity this content points to",
   "isFullScreen": "Indicates if the tab is in full-screen",
   "isMultiWindow": "The indication whether the tab is in a pop out window",
   "sourceOrigin": "",
   "subPageId": "The developer-defined unique ID for the sub-entity this content points to"  },
 "sharepoint": "The SharePoint context is available only when hosted in SharePoint",
 "sharepointSite": {
   "domain": "The domain of the root SharePoint site associated with the team",
   "path": "The relative path to the SharePoint site associated with the team",
   "url": "The root SharePoint site associated with the team"  },
 "team": {
   "displayName": "The name of the current team",
   "groupId": "Guid identifying the current Office 365 Group ID",
   "internalId": "The Microsoft Teams ID in the format 19:[id]@thread.skype",
   "isArchived": "Indicates if team is archived",
   "templateId": "",
   "type": "The type of team",
   "userRole": "The user's role in the team"  },
 "user": {
   "displayName": "",
   "id": "The Azure AD object id of the current user, in the current tenant",
   "isCallingAllowed": "Indicates if calling is allowed for the current logged in user",
   "isPSTNCallingAllowed": "Indicates if PSTN calling is allowed for the current logged in user",
   "licenseType": "The license type for the current user. Possible values are E1, E3, and E5 enterprise plans",
   "loginHint": "A value suitable as a login hint for Azure AD. This is usually the login name of the current user, in their home tenant",
   "tenant": {
     "id": "The Azure AD tenant ID of the current user",
     "teamsSku": "The license type for the current user tenant. Possible values are enterprise, free, edu, unknown"    },
   "userPrincipalName": "The principal name of the current user, in the current tenant"  }
}

For more detailed instructions and additional customization options, review: Get context for your tab.

Continue