How to Pass Query Parameters When App Runs Inside Microsoft Teams?

[jaideep-maersk]

Hi team,

We have a scenario where our application is running inside Microsoft Teams (as a Tab app), and we’d like to pass query parameters to our app when it loads.

Use cases include:

• Tracking where users are coming from when they open the tab
• Passing custom data or context on app launch
• Enabling deep-linking–style behavior with additional parameters

Question:
Is there an official or recommended way to pass query parameters to our tab when it is opened inside Teams?
For example:

• Can we include custom query params in the contentUrl?
• Is there a Teams-specific mechanism for sending custom data to the tab (e.g., via context)?
• Does Teams strip or sanitize query parameters from the URL?

Any guidance or examples on how to handle custom parameters within Teams tabs would be extremely helpful.

Thanks!

[sayali-MSFT]

Hello @jaideep-maersk ,
Thank you for bringing this issue to our attention. We will look into it and get back to you shortly.

[sayali-MSFT]

Hello @jaideep-maersk ,
Teams tab apps can receive parameters only through supported mechanisms. The contentUrl can include built-in placeholders (e.g., {app.theme}, {app.locale}, {page.id}, {page.subPageId}), which Teams automatically replaces at load time.

For custom parameters, you must use deep links, where context is passed through the deep link URL and retrieved via microsoftTeams.app.getContext() or by parsing the URL. These are the officially supported methods; arbitrary query parameters in the manifest are not.

Deep links allow you to pass custom context:
https://teams.microsoft.com/l/entity/{appId}/{entityId}?webUrl={encodedWebUrl}&context={encodedContext}

Example-

const encodedWebUrl = encodeURIComponent('https://yourapp.com/details?id=123');
const encodedContext = encodeURIComponent(JSON.stringify({ subEntityId: '123' }));
const deepLink = `https://teams.microsoft.com/l/entity/${appId}/${entityId}?webUrl=${encodedWebUrl}&context=${encodedContext}`;

Reference Document-
1.https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/deep-link-application?tabs=format1%2Cteamsjs-v2%2Cformat2%2Cspecific%2Cformat3%2Cformat4%2Cformat5
2.https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/access-teams-context?tabs=Json-v2%2Cteamsjs-v2%2Cdefault

---

Does Teams Strip Query Parameters?

No, Teams does not strip query parameters from contentUrl or deep links, but:

• You must URI-encode special characters (&, =).
• For deep links, encode both webUrl and context values.

Reference Document-
https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/deep-link-application?tabs=format1%2Cteamsjs-v2%2Cformat2%2Cspecific%2Cformat3%2Cformat4%2Cformat5

[sayali-MSFT]

Could you please confirm if your issue has resolved with provided suggestions or still looking for any help?