Define an action command

Completed

Recall that action commands allow users to perform actions in an external system from within Microsoft Teams, and share the results of the action in the form of a Teams message. In this unit, you'll learn how to plan your action-based message extension functionality and register an action command appropriately.

Plan your extension functionality

Action command interaction flow

Here's the basic interaction flow for an action-based message extension:

1. The user invokes the message extension.
2. Microsoft Teams displays a modal pop-up (implemented as a task module) to collect information.
3. The user submits the form (For more complex workflows, you can link multiple forms together).
4. Your web service responds with a Teams message inserted into the conversation or inserted into the Compose message area for the user to submit.

Implementation options

Before creating the action command, you must decide how your extension should function. The following decisions influence the implementation details for your extension:

• Where can the action command be triggered from? Action commands can be triggered from the message area, the command box, or a message. If the command is invoked from a message, the initial JSON payload sent to your bot includes the entire message from which it was invoked.

• How should the task module be created? Task modules, when triggered from an action-based messaging extension, can be implemented in one of three ways:

  • Embedded web view: an HTML page enables developers complete control over the UI and controls in the task module
  • Adaptive Card: an Adaptive Card simplifies implementing the UI, but provides less control over the UI, formatting options, and available controls
  • Static parameters: the message extension in the app manifest includes a static list of parameters that are rendered in the task module, but developers have no control over the formatting or UI

  If you use either the embedded web view or Adaptive Card option to implement your task module, your web service must respond with the task module. The Microsoft Teams client renders this task module for the user.

  To learn more about task modules, review this article.

Note

The last option for implementing a task module, static parameters, is unique to messaging extensions.

Register your command

After you plan the implementation details for your extension, you can register action commands with the appropriate properties. Here's an example of an action command:

"composeExtensions": [
  {
    "id": "createAdaptiveCard",
    "type": "action",
    "context": [ "compose" ],
    "description": "Command to run action to create a Card from Compose Box",
    "title": "Adaptive Card",
    "parameters": [
      {
        "name": "title",
        "title": "Name",
        "description": "Name of the User",
        "inputType": "text"
      },
      {
        "name": "subTitle",
        "title": "Designation",
        "description": "Designation of the User",
        "inputType": "text"
      },
      {
        "name": "text",
        "title": "Description",
        "description": "Description",
        "inputType": "textarea"
      }
    ]
  }
]

The type property defines the command as an action command or search command.

The context property defines where the messaging extension can be invoked from. Any combination of compose, commandBox, message.

The fetchTask property should be set to true when implementing the task module as an embedded web view or Adaptive Card. Set it to false when you're using a static list of parameters.