Microsoft Teams Extension

  1. Microsoft Teams Extensions
  2. Microsoft Teams Extension Grid View

The Microsoft Teams Toolkit helps you set up the following components for your messaging extension: App configurations and scaffolding relevant to messaging extensions Bot for your messaging extension that's automatically registered with the Microsoft Azure Bot Service To create your app project. Need a more compact view of channels and teams? Need to add 100+ people in a channel,.manually.? Features: - Bulk insert users into a Team (members and guests) - Display teams and channels on 2 columns (optional) - Merge 'General' channel into the Team name, if it is alone in a Team (optional) For the 2-columns display, you need to switch from the 'Grid' to the 'List' view.

-->

Messaging extensions allow the users to interact with your web service through buttons and forms in the Microsoft Teams client. They can search or initiate actions in an external system from the compose message area, the command box, or directly from a message. You can send back the results of that interaction to the Microsoft Teams client in the form of a richly formatted card. This document gives an overview of the messaging extension, tasks performed under different scenarios, working of messaging extension, action and search commands, and link unfurling.

The following image displays the locations from where messaging extensions are invoked:

Scenarios where messaging extensions are used

ScenarioExample
You want some external system to do an action and the result of the action to be sent back to your conversation.Reserve a resource and allow the channel to know the reserved time slot.
You want to find something in an external system, and share the results with the conversation.Search for a work item in Azure DevOps, and share it with the group as an Adaptive Card.
You want to complete a complex task involving multiple steps or lots of information in an external system, and share the results with a conversation.Create a bug in your 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.

Understand how messaging extensions work

A messaging extension consists of a web service that you host and an app manifest, which defines where your web service is invoked from in the Microsoft Teams client. The web service takes advantage of the Bot Framework's messaging schema and secure communication protocol, so you must register your web service as a bot in the Bot Framework.

Note

Though you can create the web service manually, use Bot Framework SDK to work with the protocol.

In the app manifest for Microsoft Teams app, a single messaging extension is defined with up to ten different commands. Each command defines a type, such as action or search and the locations in the client from where it is invoked. The invoke locations are compose message area, command bar, and message. On invoke, the web service receives an HTTPS message with a JSON payload including all the relevant information. Respond with a JSON payload, allowing the Teams client to know the next interaction to enable.

Types of messaging extension commands

There are two types of messaging extension commands, action command and search command. The messaging extension command type defines the UI elements and interaction flows available to your web service. Some interactions, such as authentication and configuration are available for both types of commands.

Action commands

Action commands are used to present the users with a modal popup to collect or display information. When the user submits the form, your web service responds by inserting a message into the conversation directly or by inserting a message into the compose message area. After that the user can submit the message. You can chain multiple forms together for more complex workflows.

The action commands are triggered from the compose message area, the command box, or from a message. When the command is invoked from a message, the initial JSON payload sent to your bot includes the entire message it was invoked from. The following image displays the messaging extension action command task module:

Search commands

Search commands allow the users to search an external system for information either manually through a search box, or by pasting a link to a monitored domain into the compose message area, and insert the results of the search into a message. In the most basic search command flow, the initial invoke message includes the search string that the user submitted. You respond with a list of cards and card previews. The Teams client renders a list of card previews for the user. When the user selects a card from the list, the full-size card is inserted into the compose message area.

The cards are triggered from the compose message area or the command box and not triggered from a message. They can not be triggered from a message.The following image displays the messaging extension search command task module:

Note

For more information on cards, see what are cards.

Link unfurling

A web service is invoked when a URL is pasted in the compose message area. This functionality is known as link unfurling. You can subscribe to receive an invoke when URLs containing a particular domain are pasted into the compose message area. Your web service can 'unfurl' the URL into a detailed card, providing more information than the standard website preview card. You can add buttons to allow the users to immediately take action without leaving the Microsoft Teams client.The following images display link unfurling feature when a link is pasted in messaging extension:

Code sample

Sample nameDescription.NETNode.jsPython
Messaging extension with action-based commandsThis sample illustrates how to build an action-based messaging extension.ViewViewView
Messaging extension with search-based commandsThis sample illustrates how to build a Search-based Messaging Extension.ViewViewView

See also

Next step

-->

Important

The articles in this section are based on the v3 Bot Framework SDK. If you're looking for current documentation (version 4.6 or later version of the SDK) see the Task-oriented interactions with Messaging Extensions section.

Action-based messaging extensions allow your users to trigger actions in external services while inside of Teams.

The following sections describe how to do this.

Add a messaging extension to your app

A messaging extension is a cloud-hosted service that listens to user requests and responds with structured data, such as a card. You integrate your service with Microsoft Teams via Bot Framework Activity objects. Our .NET and Node.js extensions for the Bot Builder SDK can help you add messaging extension functionality to your app.

Register in the Bot Framework

If you haven’t done so already, you must first register a bot with the Microsoft Bot Framework. The Microsoft app ID and callback endpoints for your bot, as defined there, will be used in your messaging extension to receive and respond to user requests. Remember to enable the Microsoft Teams channel for your bot.

Record your bot app ID and app password, you will need to supply the app ID in your app manifest.

Update your app manifest

As with bots and tabs, you update the manifest of your app to include the messaging extension properties. These properties govern how your messaging extension appears and behaves in the Microsoft Teams client. Messaging extensions are supported beginning with v1.0 of the manifest.

Declare your messaging extension

To add a messaging extension, include a new top-level JSON structure in your manifest with the composeExtensions property. Currently, you are limited to creating a single messaging extension for your app.

Note

The manifest refers to messaging extensions as composeExtensions. This is to maintain backward compatibility.

The extension definition is an object that has the following structure:

Property namePurposeRequired?
botIdThe unique Microsoft app ID for the bot as registered with the Bot Framework. This should typically be the same as the ID for your overall Teams app.Yes
scopesArray declaring whether this extension can be added to personal or team scopes (or both).Yes
canUpdateConfigurationEnables Settings menu item.No
commandsArray of commands that this messaging extension supports. You are limited to 10 commands.Yes

Define commands

Your messaging extension should declare one command, which appears when the user selects your app from the More options () button in the compose box.

In the app manifest, your command item is an object with the following structure:

Property namePurposeRequired?Minimum manifest version
idUnique ID that you assign to this command. The user request will include this ID.Yes1.0
titleCommand name. This value appears in the UI.Yes1.0
descriptionHelp text indicating what this command does. This value appears in the UI.Yes1.0
typeSet the type of command. Possible values include query and action. If not present the default value is set to queryNo1.4
initialRunOptional parameter, used with query commands. If set to true, indicates this command should be executed as soon as the user chooses this command in the UI.No1.0
fetchTaskOptional parameter, used with action commands. Set to true to fetch the adaptive card or web url to display within the task module. This is used when the inputs to the action command is dynamic as opposed to a static set of parameters. Note that the if set to true the static parameter list for the command is ignoredNo1.4
parametersStatic list of parameters for the command.Yes1.0
parameter.nameThe name of the parameter. This is sent to your service in the user request.Yes1.0
parameter.descriptionDescribes this parameter’s purposes or example of the value that should be provided. This value appears in the UI.Yes1.0
parameter.titleShort user-friendly parameter title or label.Yes1.0
parameter.inputTypeSet to the type of input required. Possible values include text, textarea, number, date, time, toggle. Default is set to textNo1.4
contextOptional array of values that defines the context the message action is available in. Possible values are message, compose, or commandBox. Default is ['compose', 'commandBox'].No1.5

Action type message extensions

To initiate actions from a messaging extension set the type parameter to action. Below is an example of a manifest with a search and a create command. A single messaging extension can have up to 10 different commands. This can include both multiple search and multiple action-based commands.

Complete app manifest example

Initiate actions from messages

In addition to initiating actions from the compose message area, you can also use your messaging extension to initiate an action from a message. This will allow you to send the contents of the message to your bot for processing, and optionally reply to that message with a response using the method described in Responding to submit. The response will be inserted as a reply to the message that your users can edit before submitting. Your users can access your messaging extension from the overflow ... menu and then selecting Take action as in the image below.

To enable your messaging extension to work from a message you'll need to add the context parameter to your messaging extension's commands object in your app manifest as in the example below. Valid strings for the context array are 'message', 'commandBox', and 'compose'. The default value is ['compose', 'commandBox']. See the define commands section for complete details on the context parameter.

Below is an example of the value object containing the message details that will be sent as part of the composeExtension request be sent to your bot.

Test via uploading

You can test your messaging extension by uploading your app. See Uploading your app in a team for details.

To open your messaging extension, navigate to any of your chats or channels. Choose the More options () button in the compose box, and choose your messaging extension.

Microsoft

Collecting input from users

There are three ways to collect information from an end user in Teams.

Static parameter list

In this method, all you need to do is define a static list of parameters in the manifest as shown above in the 'Create To Do' command. To use this method ensure fetchTask is set to false and that you define your parameters in the manifest.

When a user chooses a command with static parameters, Teams will generate a form in a Task Module with the parameters defined in the manifest. On hitting Submit a composeExtension/submitAction is sent to the bot. See the topic Responding to submit for more information on the expected set of responses.

Dynamic input using an adaptive card

In this method, your service can define a custom adaptive card to collect the end user input. For this approach, set the fetchTask parameter to true in the manifest. Note that if you set fetchTask to true any static parameters defined for the command will be ignored.

In this method your service will receive a composeExtension/fetchTask event and needs to respond with an adaptive card based task module response. Below is an sample response with an adaptive card:

The bot can also respond with an auth/config response if the user needs to authenticate or configure the extension before getting the user input.

Dynamic input using a web view

In this method your service can show an <iframe> based widget to show any custom UI and collect user input. For this approach, set the fetchTask parameter to true in the manifest.

Just like in the adaptive card flow your service will be send a fetchTask event and needs to respond with a URL based task module response. Below is an sample response with an Adaptive card:

Request to install your conversational bot

Microsoft Teams Extensions

If your app also contains a conversational bot, it may be necessary to ensure that your bot is installed in the conversation before loading your task module. This can be useful in situations where you need to get additional context for you task module. For example, you may need to fetch the roster to populate a people picker control, or the list of channels in a team.

To facilitate this flow, when your messaging extension first receives the composeExtension/fetchTask invoke check to see if your bot is installed in the current context (you could accomplish this by attempting the get roster call, for example). If your bot is not installed, you return an Adaptive Card with an action that requests the user to install your bot See the example below. Note that this requires the user to have permission to install apps in that location; if they cannot they will be presented with a message asking them to contact their administrator.

Here's an example of the response:

Once the user completes the installation, your bot will receive another invoke message with name = composeExtension/submitAction, and value.data.msteams.justInTimeInstall = true.

Here's an example of the invoke:

You should respond to this invoke with the same task response you would have responded with if the bot was already installed.

Responding to submit

Once a user completes entering their input your bot will receive a composeExtension/submitAction event with the command id and parameter values set.

These are the different expected responses to a submitAction.

Task Module response

This is used when your extension needs to chain dialogs together to get more information. The response is exactly the same as fetchTask mentioned earlier.

Compose extension auth/config response

This is used when your extension needs to either authenticate or configure in order to continue. See authentication section in the search section for more details.

Compose extension result response

This used to insert a card into the compose box as a result of a the command. It's the same response that's used in the search command, but it's limited to one card or one result in the array.

Respond with an adaptive card message sent from a bot

You can also respond to the submit action by inserting a message with an Adaptive Card into the channel with a bot. Your user will be able to preview the message before submitting it, and potentially edit/interact with it as well. This can be very useful in scenarios where you need to gather information from your users before creating an adaptive card response. The following scenario shows how you can use this flow to configure a poll without including the configuration steps in the channel message.

  1. The user clicks the messaging extension to trigger the task module.
  2. The user uses the task module to configure the poll.
  3. After submitting the configuration task module the app uses the information provided in the task module to craft an adaptive card and sends it as a botMessagePreview response to the client.
  4. The user can then preview the adaptive card message before the bot will inserts it into the channel. If the bot is not already a member of the channel, clicking Send will add the bot.
  5. Interacting with the adaptive card will change the message before sending it.
  6. Once the user clicks Send the bot will post the message to the channel.

To enable this flow your task module should respond as in the example below, which will present the preview message to the user.

Note

The activityPreview must contain a message activity with exactly 1 adaptive card attachment.

Your message extension will now need to respond to two new types of interactions, value.botMessagePreviewAction = 'send' and value.botMessagePreviewAction = 'edit'. Below is an example of the value object you will need to process:

Microsoft Teams Extension Grid View

When responding to the edit request you should respond with a task response with the values populated with the information the user has already submitted. When responding to the send request you should send a message to the channel containing the finalized adaptive card.

See alsoBot Framework samples.

This sample shows this flow using the Microsoft.Bot.Connector.Teams SDK (v3).