What are message extensions?

  • 5 minutes

When you build a message extension, you build an app for Microsoft Teams that is extended across Microsoft 365. Extending the app enables it to show up in Microsoft Outlook and in Microsoft 365 Copilot as a plugin.

An extended Microsoft Teams app is referred to as a Microsoft 365 app. A Microsoft 365 app uses a common app manifest, app packaging format, and developer and admin tools that you use to build an app for Microsoft Teams.

A message extension is an app feature, and they use a bot to communicate between the user and the external system.

Message extension capabilities

The capabilities of your message extension, how it appears in the user interface and the interactions that it can support, are defined in the app manifest.

Commands and message handlers are capabilities that a message extension can have. A message extension can use a combination of search and action commands, and message handlers.

There are two types of commands:

  • Search commands, allow users to search external systems and insert the results of that search into a message in the form of a card.
  • Action commands, allow users to act on messages in Teams, displaying a modal pop-up that can be used to collect or display information.

Infographic that shows the visual and functional differences between a search and action command in the Microsoft Teams user interface.

Message handlers enable your message extension to unfurl links when a URL with a particular domain is pasted into the compose message box.

Screenshot of a link in the Microsoft Teams compose message box. An adaptive card is shown embedded in the message compose area.

Search commands

Search commands are used to search external systems and return results as rich formatted cards. When building a Microsoft 365 Copilot message extension plugin, you need an app that contains a message extension search command.

Screenshot of search results returned by a search based message extension in Microsoft Teams.

How does a message extension work?

Message extensions use a bot registered with Bot Framework to communicate between a client and the external system.

Bot Framework is a platform provided by Microsoft, which gives you the tools and services you need to build, test, deploy, and manage bots.

A message extension consists of a bot resource, a Microsoft Entra app registration, and code that uses the Bot Framework SDK to handle user interactions.

The following image shows a high-level structure of a message extension:

Diagram showing the high level structure of a message extension.

The bot service registers a bot with the Bot Framework, and it receives requests from the client when the user interacts with the message extension. It sends requests on to a web service, which contains the bot code. The web service uses the bot app registration credentials in Microsoft Entra to authenticate with the bot service. It gathers data from the external system and returns the data back to the bot service, which is passed back to the client.

Suppose a user initiates a search using a message extension. The following sequence diagram shows the interactions:

Diagram showing the interactions between message extension components when a user initiates a search and the message extension returns search results back to the user.

  1. User opens the message extension in the client and enters a search query.
  2. The client sends a request to the bot service via a channel endpoint, containing information about the user query.
  3. The bot service sends a request to a messaging endpoint exposed on the web service to handle the user query.
  4. The messaging endpoint receives the request and invokes the bot adapter. The bot adapter uses the bot Microsoft Entra app registration credentials to secure communication between the web service and the bot service.
  5. The bot adapter invokes the OnTeamsMessageExtensionQuery method on the bot activity handler class, which contains the logic to handle the incoming request.
  6. The bot activity handler gets data from the external system. It creates a MessageExtensionResult, which contains the external data as rich formatted cards and creates a MessageExtensionResponse, which contains the MessageExtensionResult.
  7. The bot adapter receives the response from the bot activity handler and creates an HTTP response.
  8. The messaging endpoint returns the response to the bot service.
  9. The bot service returns the response via the channel endpoint back to the message extension.
  10. The message extension renders the response in the client and displays the search results to the user.

Whether your message extension supports, search or action commands, or link unfurling, the same flow occurs. The bot service forwards a request to your web service that handles and responds to it.