Microsoft Graph: Developer Blog

Microsoft Teams Adaptive cards

Take actions right from messages in Microsoft Teams

Messages are at the core of collaboration in Microsoft Teams, but collaboration is more than just messaging. Quite often messages are only the beginning of an interaction; they need to be followed-up on, turned into notes, or used to kick-off workflows in other systems. With Message Actions your app can initiate those actions directly from the message, closing the collaboration loop and keeping the communication lines alive.

You can already define actions as part of a messaging extension initiated from the compose box. Now with message actions (currently in Developer Preview) you can define actions users can initiate directly from a message. When a user takes an action from a message your app gets the message content as part of the command invocation as well and can choose what it wants to do with it, and can respond with a message or card that can be added as a response to the message from which the action was taken.

With message actions you can enable complex collaborative workflows like:

  • Close the request action – action taken loop, providing a short-cut to take the action, then automatically notifying the conversation that action has been taken.
  • Ensure the context of the conversation isn’t lost; insert a deep link to the conversation so you can refer back to it.
  • Use a message as a starting point for an action outside Teams. For instance to create an opportunity in Dynamics etc

Message actions are built on the same framework as messaging extensions and bots, allowing you to leverage your existing Teams integration easily, and potentially re-using your existing logic.

How to add a message action to your app?

Note: The rest of this article assumes that you already have an app with a messaging extension, if not please look at our documentation on messaging extensions to get started.

Built on the existing actions framework, message actions are added by defining a new context property within the messaging extension commands.

"commands": [
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Create To Do",
        "type": "Action",
        "context": ["message"],
        "fetchTask": true
    }]
    ...

Once installed, any command that has a context of message will show up for the user under the Take Actions menu of the … overflow menu.

When a user chooses your action, your bot will receive a submitAction event including the complete message details. An example of the value object containing the message details that will be sent as part of the composeExtension request sent to your bot is below.

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
  ...
  "value": {
    "commandId": "setReminder",
    "commandContext": "message",
    "messagePayload": {
      "id": "1111111111",
      "replyToId": null,
      "createdDateTime": "2019-03-12T21:53:01.687Z",
      "lastModifiedDateTime": null,
      "deleted": false,
      "subject": "",
      "summary": null,
      "importance": "normal",
      "locale": "en-us",
      "body": {
        "contentType": "text",
        "content": "Could you please review the spec by end of day?"
      },
      "from": {
        "device": null,
        "conversation": null,
        "user": {
          "userIdentityType": "aadUser",
          "id": "11111111-1111-1111-1111-11111111111",
          "displayName": "Harysh Menon"
        },
        "application": null
      },
      "reactions": [],
      "mentions": []
    },
    "context": {
      "theme": "default"
    },
  },
  "textLocale": "en-US",
  "sourceEvent": {
    "channel": {
      "id": "19:1111111111111111111111111111111@thread.skype"
    },
    "team": {
      "id": "19:1111111111111111111111111111111@thread.skype"
    },
    "tenant": {
      "id": "111111111111111111111111111111111"
    },
    "source": {
      "name": "compose"
    }
  },
  "text": "",
  "attachments": [],
  "address": {
    "id": "f:4326607497322699628",
    "channelId": "msteams",
    "user": {
      "id": "29:1-S5LwOgiCcg-q5JHC-JS8aVyvYNLOuHYfglIF-Zk1M3EoiTh9Z9X-IZyhwUoUv4kdt854_LPaTigsKSlW_LDpw",
      "name": "Harysh Menon",
      "aadObjectId": "11111111-1111-1111-1111-11111111111"
    },
    "conversation": {
      "isGroup": true,
      "conversationType": "channel",
      "id": "19:1111111111111111111111111111111@thread.skype;messageid=1552427581687"
    },
    "bot": {
      "id": "28:11111111-1111-1111-1111-11111111111",
      "name": "CAP-Reminder-Bot"
    },
    "serviceUrl": "https://smba.trafficmanager.net/amer/"
  },
  "source": "msteams"
}

Your bot will need to process the request following the exact pattern followed by actions initiated by messaging extensions, and using a task module to interact with the user and additional collect information. You can then optionally post a message back to the thread, closing the collaboration loop.

Try it out yourself!

Message actions are in Developer preview today do try it out and reach out to us for any questions or issues you run into.

filter-icon