Format cards in Microsoft Teams

Following are the two ways to add rich text formatting to your cards:

Cards support formatting in the text property only, not in the title or subtitle properties. Formatting can be specified using a subset of XML or HTML formatting or Markdown, depending on the card type. For current and future development of Adaptive Cards, Markdown formatting is recommended.

Formatting support differs between card types. Rendering of the card can differ slightly between the desktop and the mobile Microsoft Teams clients, and Teams in the desktop browser.

You can include an inline image with any Teams card. Supported image formats are .png, .jpg, or .gif formats. Keep the dimensions within 1024 x 1024 pixels and file size less than 1 MB. Animated .gif images aren't supported. For more information, see types of cards.

You can format Adaptive Cards and Office 365 Connector cards with Markdown that include certain supported styles.

Format cards with Markdown

The following card types support Markdown formatting in Teams:

  • Adaptive Cards: Markdown is supported in Adaptive Card Textblock field, and Fact.Title and Fact.Value. HTML isn't supported in Adaptive Cards.
  • Office 365 Connector cards: Markdown and limited HTML is supported in Office 365 Connector cards in the text fields.

You can use newlines for Adaptive Cards using \r or \n escape sequences for newlines in lists. Formatting is different between the desktop and the mobile versions of Teams for Adaptive Cards. Card-based mentions are supported in web, desktop, and mobile clients. You can use the information masking property to mask specific information, such as password or sensitive information from users within the Adaptive Card Input.Text input element. You can expand the width of an Adaptive Card using the width object. You can enable typeahead support within Adaptive Cards and filter the set of input choices as the user types the input. You can use the msteams property to add the ability to display images in stage view selectively.

Formatting is different between the desktop and the mobile versions of Teams for Adaptive Cards and connector cards. In this section, you can go through the Markdown format example for Adaptive Cards and connector cards.

The following table provides the supported styles for Textblock, Fact.Title, and Fact.Value:

Style Example Markdown
Bold Bold **Bold**
Italic Italic _Italic_
Unordered list
  • text
  • text
- Item 1\r- Item 2\r- Item 3
Ordered list
  1. text
  2. text
1. Green\r2. Orange\r3. Blue
Hyperlinks Bing [Title](url)

The following Markdown tags aren't supported:

  • Headers
  • Tables
  • Images
  • Preformatted text
  • Blockquotes

Newlines for Adaptive Cards

You can use the \r or \n escape sequences for newlines in lists. Using \n\n in lists causes the next element in the list to be indented. If you require newlines elsewhere in the TextBlock, use \n\n.

Mobile and desktop differences for Adaptive Cards

On the desktop, Adaptive Card Markdown formatting appears as shown in the following image in both web browsers and in the Teams client application:

Screenshot shows an example of Adaptive Card Markdown formatting in Teams desktop client.

On iOS, Adaptive Card Markdown formatting appears as shown in the following image:

Screenshot shows an example of Adaptive Card Markdown formatting in Teams iOS Platform.

On Android, Adaptive Card Markdown formatting appears as shown in the following image:

Screenshot shows an example of Adaptive Card Markdown formatting in Teams android Platform.

For more information, see text features in Adaptive Cards.

Note

The date and localization features mentioned in this section aren't supported in Teams.

Adaptive Cards format sample

The following code shows an example of Adaptive Cards formatting:

{
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "This is some **bold** text"
        },
        {
            "type": "TextBlock",
            "text": "This is some _italic_ text"
        },
        {
            "type": "TextBlock",
            "text": "- Bullet \r- List \r",
            "wrap": true
        },
        {
            "type": "TextBlock",
            "text": "1. Numbered\r2. List\r",
            "wrap": true
        },
        {
            "type": "TextBlock",
            "text": "Check out [Adaptive Cards](https://adaptivecards.io)"
        }
    ]
}

Adaptive Cards support emoji. The following code shows an example of Adaptive Cards with an emoji:

{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.0", "body": [ { "type": "Container", "items": [ { "type": "TextBlock", "text": "Publish Adaptive Card with emojis 🥰 ", "weight": "bolder", "size": "medium" }, ] }, ], }

Note

If you are using REST APIs, then set charset=UTF-8 in your request headers to add emojis in Adaptive Cards.

Adaptive card emoji

Mention support within Adaptive Cards

You can add @mentions within an Adaptive Card body for bots and message extension responses. To add @mentions in cards, follow the same notification logic and rendering as that of message based mentions in channel and group chat conversations.

Bots and message extensions can include mentions within the card content in TextBlock and FactSet elements.

Note

  • Media elements are currently not supported in Adaptive Cards on Teams platform.
  • Channel and team mentions aren't supported in bot messages.

To include a mention in an Adaptive Card, your app needs to include the following elements:

  • <at>username</at> in the supported Adaptive Card elements.
  • The mention object inside of an msteams property in the card content includes the Teams user ID of the user being mentioned.
  • The userId is unique to your bot ID and a particular user. It can be used to @mention a particular user. The userId can be retrieved using one of the options mentioned in get the user ID.

Sample Adaptive Card with a mention

The following code shows an example of Adaptive Card with a mention:

{
  "contentType": "application/vnd.microsoft.card.adaptive",
  "content": {
    "type": "AdaptiveCard",
    "body": [
      {
        "type": "TextBlock",
        "text": "Hi <at>John Doe</at>"
      }
    ],
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0",
    "msteams": {
      "entities": [
        {
          "type": "mention",
          "text": "<at>John Doe</at>",
          "mentioned": {
            "id": "29:123124124124",
            "name": "John Doe"
          }
        }
      ]
    }
  }
}

Microsoft Azure Active Directory (Azure AD) Object ID and UPN in user mention

Teams platform allows to mention users with their Azure AD Object ID and User Principle Name (UPN), in addition to the existing mention IDs. Bots with Adaptive Cards and Connectors with Incoming Webhooks support the two user mention IDs.

The following table describes the newly supported user mention IDs:

IDs Supporting capabilities Description Example
Azure AD Object ID Bot, Connector Azure AD user’s Object ID 49c4641c-ab91-4248-aebb-6a7de286397b
UPN Bot, Connector Azure AD user’s UPN john.smith@microsoft.com

User mention in bots with Adaptive Cards

Bots support user mention with the Azure AD Object ID and UPN, in addition to the existing IDs. The support for two new IDs is available in bots for text messages, Adaptive Cards body, and message extension response. Bots support the mention IDs in conversation and invoke scenarios. The user gets activity feed notification when being @mentioned with the IDs.

Note

Schema update and UI/UX changes aren't required for user mentions with Adaptive Cards in Bot.

Example

Example for user mention in bots with Adaptive Cards as follows:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0",
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "text": "Hi <at>Adele UPN</at>, <at>Adele Azure AD</at>"
    }
  ],
  "msteams": {
    "entities": [
      {
        "type": "mention",
        "text": "<at>Adele UPN</at>",
        "mentioned": {
          "id": "AdeleV@contoso.onmicrosoft.com",
          "name": "Adele Vance"
        }
      },
      {
        "type": "mention",
        "text": "<at>Adele Azure AD</at>",
        "mentioned": {
          "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
          "name": "Adele Vance"
        }
      }
    ]
  }
}

Following image illustrates the user mention with Adaptive Card in Bot:

User mention in bot with Adaptive Card

User mention in Incoming Webhook with Adaptive Cards

Incoming webhooks start to support user mention in Adaptive Cards with the Azure AD Object ID and UPN.

Note

  • Enable user mention in the schema for Incoming webhooks to support Azure AD Object ID and UPN.
  • UI/UX changes aren't required for user mentions with Azure AD Object ID and UPN.
Example

Example for user mention in Incoming Webhook as follows:

{
    "type": "message",
    "attachments": [
        {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
            "type": "AdaptiveCard",
            "body": [
                {
                    "type": "TextBlock",
                    "size": "Medium",
                    "weight": "Bolder",
                    "text": "Sample Adaptive Card with User Mention"
                },
                {
                    "type": "TextBlock",
                    "text": "Hi <at>Adele UPN</at>, <at>Adele Azure AD</at>"
                }
            ],
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "version": "1.0",
            "msteams": {
                "entities": [
                    {
                        "type": "mention",
                        "text": "<at>Adele UPN</at>",
                        "mentioned": {
                          "id": "AdeleV@contoso.onmicrosoft.com",
                          "name": "Adele Vance"
                        }
                      },
                      {
                        "type": "mention",
                        "text": "<at>Adele Azure AD</at>",
                        "mentioned": {
                          "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
                          "name": "Adele Vance"
                        }
                      }
                ]
            }
        }
    }]
}

Following image illustrates user mention in Incoming Webhook:

User mention in Incoming Webhook

Information masking in Adaptive Cards

Use the information masking property to mask specific information, such as password or sensitive information from users within the Adaptive Card Input.Text input element.

Note

The feature only supports client side information masking. The masked input text is sent as clear text to the HTTPS endpoint address that was specified during bot configuration.

To mask information in Adaptive Cards, add the style property to type input.text, and set its value to Password.

Sample Adaptive Card with masking property

The following code shows an example of Adaptive Card with masking property:

{
    "type": "Input.Text",
    "id": "secretThing",
    "style": "password",
},

The following image is an example of masking information in Adaptive Cards:

Masking information view

Full width Adaptive Card

You can use the msteams property to expand the width of an Adaptive Card and make use of additional canvas space. The next section provides information on how to use the property.

Note

Test your full width Adaptive Card in narrow form factors such as mobile and meeting side panels to ensure that content is not truncated.

Construct full width cards

To make a full width Adaptive Card, the width object in msteams property in the card content must be set to Full.

Sample Adaptive Card with full width

To make a full width Adaptive Card, your app must include the elements from the following code sample:

{
    "type": "AdaptiveCard",
    "body": [{
        "type": "Container",
        "items": [{
            "type": "TextBlock",
            "text": "Digest card",
            "size": "Large",
            "weight": "Bolder"
        }]
    }],

    "msteams": {
        "width": "Full"
    },
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2"
}

The following image shows a full width Adaptive Card:

Full width Adaptive Card view

The following image shows the default view of the Adaptive Card when you have not set the width property to Full:

Small width Adaptive Card view

Typeahead support

Within the Input.Choiceset schema element, asking users to filter and select a sizeable number of choices can significantly slow down task completion. Typeahead support within Adaptive Cards can simplify input selection by narrowing or filtering the set of input choices as the user types the input.

To enable typeahead within the Input.Choiceset, set style to filtered and ensure isMultiSelect is set to false.

Sample Adaptive Card with typeahead support

The following code shows an example of Adaptive Card with typeahead support:

{
   "type": "Input.ChoiceSet",
   "label": "Select a user",
   "isMultiSelect": false,
   "choices":  [
      { "title": "User 1", "value": "User1" },
      { "title": "User 2", "value": "User2" }
    ],
   "style": "filtered"
}

Stage view for images in Adaptive Cards

In an Adaptive Card, you can use the msteams property to add the ability to display images in stage view selectively. When users hover over the images, they can see an expand icon, for which the allowExpand attribute is set to true. For information on how to use the property, see the following example:

{
    "type": "AdaptiveCard",
     "body": [
          {
            "type": "Image",
            "url": "https://picsum.photos/200/200?image=110",
            "msTeams": {
              "allowExpand": true
            }
          }
     ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2"
}

When users hover over the image, an expand icon appears at the upper-right corner as shown in the following image:

Adaptive Card with expandable image

The image appears in stage view when the user selects the expand icon as shown in the following image:

Image expanded to stage view

In the stage view, users can zoom in and zoom out of the image. You can select the images in your Adaptive Card that must have this capability.

Note

  • Zoom in and zoom out capability applies only to the image elements that is image type in an Adaptive Card.
  • For Teams mobile apps, stage view functionality for images in Adaptive Cards is available by default. Users can view Adaptive Card images in stage view by simply tapping on the image, irrespective of whether the allowExpand attribute is present or not.

Adaptive Cards overflow menu

Adaptive Card in Teams supports overflow menu. You can populate an overflow menu for all the secondary actions in an Adaptive Card. An overflow menu in an Adaptive Card can be added to the following:

  • Actions: In actions, the primary buttons appear on the Adaptive Card and the secondary buttons are inside the overflow menu.

  • ActionSet: ActionSet is a combination of multiple actions in an Adaptive Card. Each action set can have an overflow menu.

Note

An Adaptive Card supports up to six primary actions to be viewed on the card. Any additional primary action is viewed in the overflow menu.

GIF shows the overflow menu experience in an Adaptive Card.

Enable overflow menu

To enable overflow menu, configure the mode property with the value as primary or secondary in the Adaptive Card schema. The following table describes the mode property:

Property Type Required Description
mode Enum (Primary, Secondary) No Whether or not the action is a primary or secondary action. Secondary actions will be collapsed into an overflow menu.

The following is an example of the mode property in the actions type and the ActionSet element:

Actions

In the following example, there are two primary actions and one secondary action. The secondary action creates an overflow menu.

{
   "type": "AdaptiveCard",
   "actions": [
        {
            "type": "Action.Submit",
            "title": "Set due date"
        },
        {
            "type": "Action.OpenUrl",
            "title": "View",
            "url": "https://adaptivecards.io"
        },
        {
            "type": "Action.Submit",
            "title": "Delete",
            "mode": "secondary"
        }
    ]
}

Note

  • The overflow menu behaves differently on a bot sent card and a message extension card for the root level actions in an Adaptive Card. The overflow menu on a bot sent card appears as a pop-up context menu and on the message extension card it appears at the upper-right corner under the More options (...) icon. The behavior is not applicable to the ActionSet in an Adaptive Card.

The following image is an example of overflow menu in a bot sent card and a message extension card:

Screenshot shows an example of the overflow menu behavior in a bot sent card and a messaging extension card.

Action set

In the following example, all the actions are marked as secondary, therefore, a single overflow menu appears on the card.

{
    "type": "ActionSet",
     "actions": [

          {
           
            "type": "Action.Submit",
            "title": "view",
            "mode": "Secondary" 
       {
       },
            "type": "Action.submit",
            "title": "Delete",
            "mode": "secondary"

       },
       {
             "type": "Action.submit",
            "title": "Delete",
            "mode": "secondary"
       }
     ]
}

The following is an example of the overflow menu experience in Teams desktop and mobile:

When a user selects the overflow menu on a desktop, the buttons that are set as secondary appear in the Adaptive Card.

Screenshot shows an example of buttons in an Adaptive Card on Teams desktop.

Screenshot shows an example of an Adaptive Card with the list of actions in an overflow menu on Teams desktop.

Screenshot shows an example of an Adaptive Card with the buttons that are set as secondary as options in an overflow menu on Teams desktop.

Format cards with HTML

The following card types support HTML formatting in Teams:

  • Office 365 Connector cards: Limited Markdown and HTML formatting are supported in Office 365 Connector cards.
  • Hero and thumbnail cards: HTML tags are supported for simple cards, such as the hero and thumbnail cards.

Formatting is different between the desktop and the mobile versions of Teams for Office 365 Connector cards and simple cards. In this section, you can go through the HTML format example for connector cards and simple cards.

Connector cards support limited Markdown and HTML formatting.

Style Example HTML
Bold text <strong>text</strong>
Italic text <em>text</em>
Header (levels 1–3) Text <h3>Text</h3>
Strikethrough text <strike>text</strike>
Unordered list
  • text
  • text
<ul><li>text</li><li>text</li></ul>
Ordered list
  1. text
  2. text
<ol><li>text</li><li>text</li></ol>
Preformatted text text <pre>text</pre>
Blockquote
text
<blockquote>text</blockquote>
Hyperlink Bing <a href="https://www.bing.com/">Bing</a>
Image link Duck on a rock <img src="https://aka.ms/Fo983c" alt="Duck on a rock"></img>

In connector cards, newlines are rendered in HTML using the <p> tag.

Mobile and desktop differences for connector cards

On the desktop, HTML formatting for connector cards appears as shown in the following image:

Screenshot shows HTML formatting for connector cards in the desktop client.

On iOS, HTML formatting appears as shown in the following image:

Screenshot shows HTML formatting for connector cards in the iOS client.

Connector cards using HTML for iOS include the following issues:

  • Inline images aren't rendered on iOS using either Markdown or HTML in connector cards.
  • Preformatted text is rendered but doesn't have a gray background.

On Android, HTML formatting appears as shown in the following image:

Screenshot shows HTML formatting for connector cards in the Android client.

Format sample for HTML connector cards

The following code shows an example of formatting for HTML connector cards:

{
  "contentType": "application/vnd.microsoft.teams.card.o365connector",
  "content": {
    "@type": "MessageCard",
    "@context": "https://schema.org/extensions",
    "summary": "Summary",
    "title": "Connector Card HTML formatting",
    "sections": [
        {
            "text": "This is some <strong>bold</strong> text"
        },
        {
            "text": "This is some <em>italic</em> text"
        },
        {
            "text": "This is some <strike>strikethrough</strike> text"
        },
        {
            "text": "<h1>Header 1</h1>\r<h2>Header 2</h2>\r <h3>Header 3</h3>"
        },
        {
            "text": "bullet list <ul><li>text</li><li>text</li></ul>"
        },
        {
            "text": "ordered list <ol><li>text</li><li>text</li></ol>"
        },
        {
            "text": "hyperlink <a href=\"https://www.bing.com/\">Bing</a>"
        },
        {
            "text": "embedded image <img src=\"https://aka.ms/Fo983c\" alt=\"Duck on a rock\"></img>"
        },
        {
            "text": "preformatted text <pre>text</pre>"
        },
        {
            "text": "Paragraphs <p>Line a</p><p>Line b</p>"
        },
        {
            "text": "<blockquote>Blockquote text</blockquote>"
        }
     ]
  }
}

See also