Prepare to build a message extension

  • 3 minutes

Message extensions can be implemented in various ways to support different user scenarios. In this unit, you'll explore options for implementing message extensions so that you can decide which implementation meets your project's needs.

Message extension scenarios

Message extensions are appropriate when you need to allow users to interact with an external web service within Microsoft Teams and share the results of the interaction within a Teams conversation.

Below are the main scenarios for message extensions, with examples:

Scenario Example
A user requests for an external system to perform an action and return the result to the conversation. Create a work item in a system like Azure DevOps and share the work item details with a Teams channel.
A user needs to search for something in an external system and share the results with the conversation. Search for a promotional product image in a design repository and share with the marketing team in a channel.
A user wants to complete a complex task involving multiple steps or large amount of information in an external system and share the results with a conversation. Create a bug in a tracking system based on a Teams message, assign that bug to Bob, and send a card to the conversation thread with the bug's details.

Message extension types

There are two types of message extensions: action-based and search-based. Different UI elements and interaction flows are available to your web service based on the type of extension you implement. Certain interactions, such as authentication and configuration, are available for both types.

  • Action-based message extensions allow your app to collect input or display information via a modal pop-up. When a user submits the form, your web service responds by generating a message in Teams that the user can post to the conversation. For more complex workflows, you can link multiple forms together.

  • Search-based message extensions allow users to search an external system for information then insert the results of the search into a message.

  • Your app can also implement link unfurling. Link unfurling is the process of taking a hyperlink pasted into a message and performing an action based on the result of processing the link. This allows users to paste links into a message instead of invoking your message extension by typing or selecting an action.

    Screenshot of Microsoft Teams. There is a URL in the Compose message area, with a thumbnail card displaying an image and the following text: More details about the image link.

Message extension user experience

Users can invoke message extensions from several places within the Teams client. When you build a message extension, you need to decide which of these invoke locations to support.

Screenshot of the Teams desktop client that depicts a Teams channel with posts. The area at the bottom of the Compose message area with buttons is highlighted.

Users can invoke message extensions from:

  1. The command box by @mentioning your app in the command box.
  2. The Compose message area. The buttons at bottom of the Compose message area (highlighted in the picture above) allow users to invoke message extensions. A few are built in, such as Emoji, gif, and Sticker. Choose the More Options (⋯) button to see other message extensions, including those you add from the app gallery or upload yourself.
  3. Directly from an existing message through the ... overflow menu on a message.

Building message extensions

To build a message extension, you'll need to host a web service and create an app manifest (formerly known as a Teams app manifest).

Note

There are two ways to build message extensions: using an existing API (API-based) or using Bot Framework (bot-based). API-based message extensions are available only in public developer preview. This module focuses on bot-based messaged extensions.

Your app manifest

In your app manifest, you'll define up to 10 different commands for your message extension. Each command specifies the type of message extension (action or search) and the supported invoke locations.

Note

While message extensions are registered using the Bot Framework, you don't need to register the bot in the app manifest for your app. When you define a message extension in the app manifest, Teams exposes the customization as a message extension and not as an installable bot.

Your web service

Message extensions use the Bot Framework to handle communication with your web service. You must register your web service as a bot in the Bot Framework and use the Bot Framework's messaging schema and secure communication protocol.

When the message extension is invoked, Microsoft Teams will send, via the Bot Framework, an HTTPS message with a JSON payload that includes all relevant information. Your web service will respond with a JSON payload, via the Bot Framework, that informs the Microsoft Teams client what interaction to enable next.

While you can create the message extension web service by hand, you can also use the Bot Framework SDKs that simplify implementing the protocol and expected message types sent from the Bot Framework. Teams Toolkit simplifies the process by scaffolding a solution that you can customize.