Nov 20, 2020 In 2019/20 there were over 402 thousand burglaries in England and Wales, a decline of almost 40 thousand when compared with the previous reporting year. Microsoft 365 has all the familiar Office apps and more in one place. Work, learn, collaborate, connect, and create with Microsoft 365. Outlook.com is a free personal email service from Microsoft that doesn't scan your email for the purpose of serving you ads. Automatically file emails and share photos easily. Dell OptiPlex 7020 Desktop Tower Computer, Intel Quad Core i5-4590 3.3GHz PC, 16GB RAM, 1TB HDD, Microsoft Windows 10 Professional, Microsoft Office 365 Personal, DVD, Keyboard, Mouse, WiFi (Renewed) 3.8 out of 5 stars 28.

Note

This document describes the original JSON format for the actionable message card format. For actionable messages sent via email, this has been replaced with the Adaptive Card format. Microsoft recommends that new actionable message integrations use the Adaptive Card format, and existing integrations consider updating to Adaptive Card format. The Adaptive Card format is required to support Outlook on iOS and Android. However, if you are sending actionable messages via an Office connector, or to a Microsoft Teams connector, you must continue to use the message card format.

Cards are meant to provide easy to read, at-a-glance information that users can very quickly decipher and act upon when appropriate. As such, the guiding principle for designing great card is 'content over chrome,' which means cards are straight to the point and minimize the use of anything that would be distracting such as icons or custom colors.

Card playground

Ready to experiment with your card design? Head to the Card Playground which allows you to see what your card will look like as you edit the associated JSON payload.

Note

The Card Playground loads Adaptive Card examples by default. You can find message card format examples by selecting the Select a sample dropdown in the playground.

Design guidelines

Text formatting

All text fields in a card and its section can be formatted using Markdown. We support basic Markdown.

Important

Since all fields are processed as Markdown, be sure to escape Markdown special characters (such as * or #) if needed.

Tip

Follow these guidelines when formatting text fields.

• Do use Markdown to format text.
• Don't use HTML markup in your cards. HTML is ignored and treated as plain text.

Using sections

If your card represents a single 'entity', you may be able to get away with not using any section. That said, sections support the concept of an 'activity' which is often a good way to represent data in a card.

If your card represents multiple 'entities' or is, for instance, a digest for a particular news source, you will definitely want to use multiple sections, one per 'entity.'

Tip

Follow these guidelines when planning the layout of your card.

• Do use sections to logically group data together.
• Sometimes, multiple sections MAY be used to represent a single logical group of data; this allows for more flexibility on ordering the information presented in the card. For example, it makes it possible to display a list of facts before an activity.
• Don't include more than 10 sections. Cards are meant to be easy to read; if there is too much information in a card, it will be lost on the user.
• For digest-like cards, consider adding a 'View full digest' action at the end of the card.

Card fields

Outlook 3560

Section fields

Image object

Defines an image as used by the heroImage and images property of a section.

Actions

Cards are very powerful in the sense that they allow users to take quick actions without leaving their email client. When designing cards, consider making them actionable, as that will increase user engagement and productivity.

Actions are specified using the potentialAction property which is available both on the card itself and on each section. There are five types of actions:

There can be a maximum of 4 actions (whatever their type) in a potentialAction collection.

• Do include actions that will make the biggest impact for the end user, like the most repetitive ones.
• Don't add 4 actions just because you can. In many cases, fewer actions will lead to a better experience.
• Don't craft your cards in an effort to replace an external application. Cards are meant to complement such applications, not to replace them.

OpenUri action

Opens a URI in a separate browser or app.

Although links can be achieved through Markdown, an OpenUri action has the advantage of allowing you to specify different URIs for different operating systems, which makes it possible to open the link in an app on mobile devices.

• Consider using an OpenUri action rather than a link in Markdown if there is a clear advantage for your users in their ability to open the link in an app on their mobile device.
• Do include at least an OpenUri action to view the entity in the external app it comes from.
• Do make the OpenUri action the last one in the potentialAction collection.

Note

Microsoft Teams and Outlook on the web only support HTTP/HTTPS URLs in the targets array for an OpenUri action.

HttpPOST action

Makes a call to an external Web service.

When an HttpPOST action is executed, a POST request is made to the URL in the target field, and the target service needs to authenticate the caller. This can be done in a variety of ways, including via a Limited Purpose Token embedded in the target URL. For more information and help on choosing the security mechanism that works best for your particular scenario, please see Security requirements for actionable messages.

Header

The Header object is a name/value pair that represents an HTTP header.

Reporting an action's execution success or failure

HttpPOST actions can include the CARD-ACTION-STATUS HTTP header in their response. This header is meant to contain text that indicates the outcome of the action's execution, whether it has succeeded or failed.

The value of the header will be displayed in a consistent way in a reserved area of the card. It is also saved with the card so it can be displayed later on, so users can be reminded of the actions that have already been executed on a given card.

Tip

Follow these guidelines when returning a response to HttpPOST actions.

• Do return the CARD-ACTION-STATUS header in your responses.
• Do make the message in that header as informative and meaningful as possible. For instance, for an 'approve' action on an expense report:
  • In case of success, don't return 'The action was successful', instead return 'The expense was approved'
  • In case of failure, don't return 'The action failed', instead return 'The expense couldn't be approved at this time. Please try again later'
• Don't mention either the name of the person taking the action nor the time the action is being taken in your CARD-ACTION-STATUS header. Both these pieces of information will be automatically added for you and displayed in a consistent way.

Refresh cards

Refresh cards are a very powerful mechanism that allow HttpPOST actions to fully update the card on the fly as the action successfully completes. There are many scenarios that benefit from refresh cards:

• Approval scenario (e.g. expense report)
  • Once the request is approved or rejected, the card is refreshed to remove the approve/decline actions and update its content so it reflects the fact that it's been approved or declined
• Task status
  • When an action is taken on a task, such as setting its due date, the card refreshes to include the updated due date in its facts
• Survey
  • Once the question has been answered, the card is refreshed so:
    • It no longer allows the user to respond
    • It shows updated status, like 'Thanks for responding to this survey' alongside the user's actual response
    • Potentially include a new OpenUri action that allows the user to consult the survey online

To refresh a card as a result of an HttpPOST action, a service needs to do the following:

• Include the JSON payload of the new card in the body of the response to the HTTP POST request it received.
• Add the CARD-UPDATE-IN-BODY: true HTTP header to the response, in order to let the receiving client know that it should parse the response body and extract a new card (this is to avoid unnecessary processing when no refresh card is included.)

Tip

Follow these guidelines when returning refresh cards.

Outlook Login

• Do use refresh cards with actions that can only be taken a single time. In those cases, the refresh card would not include any action that cannot be taken anymore
• Do use refresh cards with actions that change the state of the entity they are performed on. In those cases, the refresh card should include updated information about the entity, and MAY change the set of actions that can be performed
• Don't use refresh cards to lead a conversation with the user. For instance, don't use refresh cards for a multi-step 'wizard'
• Do include at least an OpenUri action to view the entity in the external app it comes from.

ActionCard action

Presents additional UI that contains one or more Inputs, along with associated actions that can be either OpenUri or HttpPOST types.

Do use an ActionCard action if an action requires additional input from the user. Some scenarios:

• Responding to a survey
• Adding a comment to a bug
• Providing justification for declining an expense report

By default, an ActionCard action will be represented as a button or link in the card's UI. When clicked, that button will display an additional piece of UI containing the inputs and actions defined in the action card.

If there is a single ActionCard action in a potentialAction collection, then Outlook will represent that action 'pre-expanded,' e.g. its inputs and actions will be immediately visible.

Outlook 365 Login

Example ActionCard

Inputs

Three types of inputs are supported: TextInput, DateInput, and MultichoiceInput.

Common fields

The following fields are common to all input types.

TextInput

Use this input type when you need users to provide free text, such as the response to a survey question.

Example TextInput

DateInput

Use this input type when you need users to provide a date and or a time, such as for a task's due date.

Example DateInput

MultichoiceInput

Use this input type when you need users to select from a list of pre-defined choices, such as a bug status, yes/no/maybe, etc.

Example compact MultichoiceInput

Example multi-select MultichoiceInput

Example expanded MultichoiceInput

Input value substitution

The value of an input can be referenced in any URL of a ViewAction or HttpPOST action. It can also be referenced in an HttpPOST action's body. When an input value is referenced, it is substituted with the actual value of the input right before the action is executed.

To reference an input's value, use the following format:

{{<id of input>.value}}

Input value substitution example

InvokeAddInCommand action

Opens an Outlook add-in task pane. If the add-in is not installed, the user is prompted to install the add-in with a single click.

When an InvokeAddInCommand action is executed, Outlook first checks if the requested add-in is installed and turned on for the user. If it is not, the user is notified that the action requires the add-in, and is able to install and enable the add-in with a single click. Outlook opens the requested , making any initialization context specified by the action available to the add-in.

For more information, see Invoke an Outlook add-in from an actionable message.

Example InvokeAddInCommand

Card Examples

Trello

Card is created in a list: How to download netflix to macbook.

Here is how that card is built:

Here's the same card with the Add a comment action expanded:

Here's how the Add a comment action is built:

Trello JSON

Twitter

Here's an example of a Twitter digest card:

Here's how that card is built:

Twitter JSON

Actionable email

Here's an example of an HTML email body with an embedded message card.