Refresh an actionable message when the user opens it

Important

Onboarding of new Actionable Messages providers with a Global scope is temporarily paused until Jun 30th, 2024 due to service upgrades. Existing Global scoped providers and onboarding of Organization and Test scope providers are not impacted. For more details, see Frequently asked questions for Actionable Messages.

Actionable messages allow users to take quick actions on an email message, often based on data presented in the card. However, sometimes data changes after the actionable message has been sent. For example, your service might send an actionable message to multiple approvers asking them to approve or reject a request. One approver approves the request, but the actionable message in the other approver's mailbox still asks for approval. Now, with the autoInvokeAction property on actionable messages, you can provide an HTTP endpoint to retrieve an up-to-date Adaptive Card payload with the latest information when the user opens the email in Outlook.

Important

Refreshing the actionable message when the user opens it has a direct impact on the perceived performance of your actionable message solution. It is crucial that your service that supplies the updated card meet the performance requirements described in Implementing the Web API.

Registration requirements

Actionable Messages services registered in the developer dashboard with the Test Users or Organization scope can use this feature as soon as they are approved. If your service is registered with the Global scope, you must contact onboardoam@microsoft.com to enable this feature.

Using autoInvokeAction

In order to use this feature, your card must use the Adaptive Card format. The autoInvokeAction property is an Outlook-specific property added to the AdaptiveCard type. The value of this property is an Action.Http action with the method set to POST. The url property specifies a Web API endpoint in your service that will provide the updated Adaptive Card payload.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [...],
  "actions": [...],
  "autoInvokeAction": {
    "method": "POST",
    "url": "https://actionablemessages.contoso.com/api/getupdatedcard",
    "body": "",
    "type": "Action.Http"
  }
}

Crafting the initial Adaptive Card

When using autoInvokeAction, it is very important that the initial card included with the message still be valuable to the end user and, ideally, be actionable. The autoInvokeAction might fail, or network conditions might slow it down, in which case the initial card is all the end user will see.

• Do not send an empty initial card with just an autoInvokeAction. Such cards will be rejected by the Actionable Message platform.
• Do not send an initial card that is just a placeholder asking the user to wait.
• Do send an initial card that presents the information in its current state, even if that means the user might see outdated data by the time they open your message.

Implementing the Web API

The Action.Http action specified in the autoInvokeAction property works exactly the same as any other Action.Http action. For details on implementing the endpoint for this action, see Implementing the Web API.

The endpoint for an autoInvokeAction must also meet the following additional requirements.

• Requests must return within 2 seconds.
• Requests that take longer will be ignored by the client, and the original card will continue to display. The message will still be updated on the server.
• Successful responses should include a CARD-UPDATE-IN-BODY header with value true and an Adaptive Card JSON payload.

On success, the Adaptive Card returned will completely replace the existing card in the email message. If the URL returns an error or times out, the existing card will continue to display.

Example approval scenario

Consider this example vacation request card generated by a leave request tool and sent to the employee's manager.

Tip

You can access the JSON and modify this card sample by selecting the Vacation Approval sample in the Actionable Message Designer.

The card includes information to help the manager make a decision, including the dates requested and how much leave the employee has remaining. This information was accurate when the message was generated and sent. However, the data could change before the manager checks his email. For example, the employee might edit his request in the leave request tool to change the requested dates.

By including an autoInvokeAction property on the actionable message generated by the tool, your card with the original data is replaced by a new card with new data when the manager opens it. The URL specified in the autoInvokeAction returns the same JSON payload, with new values for the requested vacation dates.