Adding a Business App to Teams: Tabs, Bots and Message Extensions

Choosing between tabs, bots, message extensions and webhooks when bringing a web app or Power App into Teams; blank tabs, SSO errors, the manifest and deployment policies.
Technical summary
Technology
Microsoft Teams, Teams JavaScript SDK, Bot Framework, Adaptive Cards, Microsoft Entra ID, Microsoft Graph
Topic
Ways to integrate business applications into Teams
Level
Intermediate–advanced
Prerequisites
  • Knowledge of Entra ID app registrations
  • A web application published over HTTPS
  • Access to the Teams admin center
In this article7 sections

If users spend their day in Teams, making them open business applications such as leave requests, purchase approvals or service tickets in a separate browser tab is reason enough for that app not to be used. But “adding it to Teams” isn’t a single operation. Tabs, bots, message extensions and notification mechanisms solve different problems and bring different development and management loads. When the wrong surface is chosen, either unnecessary bot infrastructure is built or the user still has to go to the app to approve. Below, we explain which surface to choose when integrating an existing web application or Power App into Teams, the points that break most often in the field and how to manage deployment.

App surfaces in Teams

A Teams app is actually an app package: a ZIP consisting of a manifest.json file and two icons (color and outline). The manifest defines which surfaces the app uses; the same package can carry several surfaces together, for example both a personal tab and a bot.

  • Personal tab (static tab): A user-specific web page opened from the left app bar. For views such as “My requests” and “Pending approvals”.
  • Channel/group tab (configurable tab): A tab added to a channel, chat or meeting, with its context chosen on a configuration page. For a team’s shared board or a project view.
  • Bot: A service that receives and sends messages through chat. Proactive notifications and in-place actions with Adaptive Cards are its strengths.
  • Message extension: Invoked from the compose box or a message’s menu. The search-based kind turns a record in the app into a card and adds it to the chat; the action-based kind creates a record from a message. Link unfurling is also part of this surface.
  • Webhook and workflow notifications: Sending messages to a channel without an app package. Microsoft has announced a retirement process for classic Office 365 connectors (including incoming webhooks); for new work, prefer webhooks created with the Workflows app in Teams (Power Automate-based), and verify the current timeline in Microsoft’s documentation. Notifications tied to the old connector will one day stop silently.

Comparing tabs, bots and message extensions

Surface Best-fit scenario Development load Point to watch
Personal tab Opening an existing web app in Teams Low Frame (iframe) permissions, SSO
Channel tab A shared view in a team context Low to medium Configuration page, context-dependent data
Bot Notification + approval via a card Medium–high Bot registration, messaging endpoint, state management
Message extension Sharing a record into a chat, creating a record from a message Intermediate Requires bot infrastructure
Workflows webhook One-way notification to a channel Very low Limited interaction back

The decision order is simple. Will the user do work in the app, or will the app notify the user of an event? The first needs a tab, the second a notification channel. If the notification expects a decision from the user (approve/reject), a bot and an Adaptive Card together give the experience with the fewest clicks. If telling a team “a new record has been opened” is enough, a webhook will do; there’s no need to build a bot. A message extension does real work in teams where record numbers constantly circulate in chats (support, sales). In other teams it often goes unused.

Adding an existing web application as a tab

A tab is an ordinary web page loaded inside an iframe in the Teams client. The complaint we get most often in the field is “the tab opens blank”, and the cause is almost always the same: the app refuses to open in a frame. An app that sends an X-Frame-Options: DENY or SAMEORIGIN header shows a white screen in Teams. Instead, the Teams and Microsoft 365 client domains are allowed with the frame-ancestors directive in the Content-Security-Policy header. Take the domain list from the Teams developer documentation, not from memory; it keeps expanding across Microsoft 365 apps. For apps behind a reverse proxy or WAF, also check that the header isn’t coming from the intermediate layer rather than the app.

The second step is for the page to load the Teams JavaScript client library (@microsoft/teams-js) and call app.initialize(). Then context information such as theme, language and the current team and channel is obtained with app.getContext(). With this context, the app can, for example, show only that project’s records in a channel tab. If initialize isn’t called, no context comes.

A personal tab definition in the manifest looks like the following. The values are examples; for brevity, required fields such as developer, description, icons and accentColor have been omitted. For manifestVersion, choose the current schema version supported by your toolchain, and run the package through validation in the Developer Portal.

{
  "manifestVersion": "1.17",
  "id": "00000000-0000-0000-0000-000000000000",
  "version": "1.0.0",
  "name": { "short": "Request Center", "full": "Request Center" },
  "staticTabs": [
    {
      "entityId": "my-requests",
      "name": "My Requests",
      "contentUrl": "https://requests.example.com/teams/my-requests",
      "scopes": [ "personal" ]
    }
  ],
  "validDomains": [ "requests.example.com" ],
  "webApplicationInfo": {
    "id": "<entra-app-client-id>",
    "resource": "api://requests.example.com/<entra-app-client-id>"
  }
}

On the Power Apps side, most of these steps are automatic: the Add to Teams option in the app menu in the Power Apps portal adds the app directly or downloads it as a package for an admin to upload. SharePoint pages and lists are added without code via Teams’ built-in SharePoint tab. For custom development, Microsoft’s tools (Teams Toolkit, now called Microsoft 365 Agents Toolkit) and the Teams Developer Portal make manifest editing and validation easier.

SSO and identity inside Teams

Asking the user to sign in a second time in a tab means pop-up problems inside an iframe and user complaints. Teams tab SSO solves this: the tab calls authentication.getAuthToken(), and the Teams client produces an access token for your app using the user’s Entra ID session. Setup takes five steps, and most errors occur in the first three.

  1. Create an app registration in Entra ID and define the Application ID URI in the form api://<domain>/<client-id>.
  2. Expose a scope (usually access_as_user).
  3. Add the client IDs of the Teams desktop/mobile and Teams web clients as pre-authorized clients for this scope; copy the ID values from Microsoft’s documentation, don’t type them by hand.
  4. Write the same client ID and URI in the webApplicationInfo field in the manifest. A single character difference breaks SSO.
  5. Validate the token on the server side. If you need to access Microsoft Graph on the user’s behalf, exchange this token for a Graph token with the on-behalf-of flow; don’t send the token received on the client directly to Graph.

Keeping Graph permissions at the narrowest scope needed also shortens the consent process; we detailed this design in the Microsoft Graph API permissions guide. If the app will also be opened outside Teams, see the OIDC sign-in with Entra ID article for how to use the same app registration with OIDC.

App upload, approval and deployment policies

Internal apps are published in Teams as “custom apps” and managed from the Teams admin center. Preparing the package is half the job; policies determine who sees it.

  • Upload: The package is uploaded to the organization catalog under Teams apps > Manage apps in the Teams admin center. A package submitted by a developer from the Teams client, on the other hand, creates a publishing request awaiting admin approval.
  • Access: Who can use the app is determined by app permission policies or, if enabled in your tenant, app-centric management settings. Start with a pilot group; you catch problems in a limited audience.
  • Pinning: App setup policies pin the app to the app bar of specific users and preinstall it. For an app using a bot, preinstallation is also required; if the user has never opened the app, proactive notifications don’t go out.
  • Custom app upload permission: Whether a developer can upload a package for testing depends on the custom app upload setting in the setup policy. Give this permission to the developer group, not to all users.
  • Version updates: A package uploaded without incrementing the version value in the manifest isn’t recognized as an update. An update that includes scope or permission changes may ask users for consent again.

Notification scenarios and limitations

Most of a business app’s value in Teams comes from notifications. There are three main paths, each answering a different need:

Method Target Requirements
Workflows webhook Channel or chat Power Automate flow, webhook URL
Bot proactive message Person, chat, channel Bot registration, the app installed at the target
Activity feed notification The user’s Teams activity feed Graph sendActivityNotification, the app installed for the user

A webhook URL is a secret: anyone who knows the URL can send messages to the channel. Don’t keep it in plain text in source code or a configuration file; store it in a secrets vault. When the user clicks “Approve” on an Adaptive Card sent by a bot, the action takes place in your bot service. Re-check on the server the authorization of the person performing the card’s action; don’t assume everyone who receives the card can approve. Cards can be forwarded.

Build the known limitations into the design from the start:

  • The tab area is narrow in the Teams mobile client; test the mobile view of the tab page separately.
  • An app inside an iframe must use the methods provided by the Teams JS SDK for file downloads, opening new windows and authentication pop-ups; it doesn’t behave as it does in a browser.
  • Guests and external users see the app only if their own tenant policies and your app policies allow it.
  • Microsoft’s rate limits apply to bot and webhook messages; queueing and retry logic are essential for bulk notifications.

If you’d like to see an implemented model, see the helpdesk setup with Microsoft 365 article, where request management is combined with Teams. For bringing internal apps into Teams and the notification architecture, you can review our Teams and corporate integrations service. The reference for the manifest schema and the current capabilities of the surfaces is the Microsoft Teams developer documentation.

Frequently asked questions

Does adding a Power App to Teams require development?

Usually not. The Add to Teams option in the Power Apps portal adds the app as a personal app or produces a package for an admin to upload to the organization catalog. Extra development is needed when custom notifications, a bot or a message extension are wanted.

My tab appears blank in Teams; what should I check first?

First check whether the app sends an X-Frame-Options header and whether the Content-Security-Policy frame-ancestors directive allows the Teams domains. Then verify that the page loads the Teams JS library and calls app.initialize(), and that the domain is in the validDomains list in the manifest.

Should I use a bot or a webhook for notifications?

If one-way channel notifications are enough, a Workflows-based webhook is the fastest solution. If personal notifications, approval via a card or interaction within a chat are needed, a bot is required. A bot needs more infrastructure, but the user completes the task without leaving Teams.

What does the user see if SSO doesn’t work in a Teams tab?

The getAuthToken call returns an error. In that case the app should direct the user to an interactive sign-in using Teams’ authentication window method. The most common causes are a mismatch between the Application ID URI and the resource value in the manifest, and the Teams clients not being pre-authorized.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles