Adaptive Cards

What Adaptive Cards are

An Adaptive Card is a chunk of UI described in JSON. You author the card once; each host — Microsoft Teams, Outlook, a bot, Copilot Studio, Viva Connections — renders it as native UI that adapts to its own look and feel. No HTML or CSS, no per-client tweaking: the same payload becomes a Teams message, an email card, or a bot reply.

Every card is an object with type: "AdaptiveCard", a version, a body array of elements, and an optional actions array of buttons. The host supplies the styling (fonts, colours, spacing) through a host config, so you describe *intent* (“this is a heading”, “this is an accent button”) rather than pixels.

• Teams — flow-bot messages, bot replies, message-extension and dialog (task module) UI. Supports schema 1.5.
• Outlook actionable messages — a card embedded in an email so recipients act without leaving the inbox. Separate, more conservative schema track (baseline 1.0).
• Power Automate — posts cards to Teams (display-only or “wait for a response”) via the Teams connector.
• Bots / Copilot Studio / Bot Framework Web Chat — rich replies and forms (Web Chat tracks 1.6).
• Design + validate in the official Adaptive Cards Designer, then paste the JSON into your flow or bot.

Card anatomy

Start from this skeleton. type and version are required; $schema enables editor IntelliSense; everything visible lives in body; buttons live in actions.

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "body": [
    { "type": "TextBlock", "text": "Order shipped", "size": "Large", "weight": "Bolder", "wrap": true },
    { "type": "TextBlock", "text": "Tracking number TN-4821 is on its way.", "wrap": true, "isSubtle": true }
  ],
  "actions": [
    { "type": "Action.OpenUrl", "title": "Track package", "url": "https://contoso.com/track/TN-4821" }
  ]
}

Elements

Elements are the leaf content you stack in body (or inside a container). TextBlock and Image cover most cards.

TextBlock honours a small markdown subset across most hosts: **bold**, _italic_, [links](https://…), bulleted / numbered lists, and line breaks. Use wrap: true almost everywhere — text is truncated to one line by default.

{
  "type": "ColumnSet",
  "columns": [
    { "type": "Column", "width": "auto", "items": [
      { "type": "Image", "url": "https://contoso.com/avatar.png", "size": "Small", "style": "Person", "altText": "Priya N." }
    ] },
    { "type": "Column", "width": "stretch", "verticalContentAlignment": "Center", "items": [
      { "type": "TextBlock", "text": "Priya Nair", "weight": "Bolder", "wrap": true },
      { "type": "TextBlock", "text": "Requested 3 days of leave", "isSubtle": true, "spacing": "None", "wrap": true }
    ] }
  ]
}

Containers & layout

Containers group and arrange elements. Container stacks vertically; ColumnSet lays out side by side; FactSet renders a tidy label/value grid; Table (1.5) draws real rows and columns.

{
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    { "type": "Container", "style": "Emphasis", "bleed": true, "items": [
      { "type": "TextBlock", "text": "Expense report #1042", "weight": "Bolder", "size": "Large", "wrap": true }
    ] },
    { "type": "FactSet", "facts": [
      { "title": "Submitted by", "value": "Dana Wu" },
      { "title": "Amount", "value": "$486.20" },
      { "title": "Status", "value": "Pending approval" }
    ] }
  ]
}

Inputs (collecting data)

Inputs turn a card into a form. Each input needs a unique `id` — that id becomes the key in the data sent back when the user submits. Pair inputs with an Action.Submit (or Action.Execute) to gather their values.

{
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    { "type": "Input.Text", "id": "comments", "label": "Comments", "isMultiline": true, "isRequired": true,
      "errorMessage": "Please add a comment." },
    { "type": "Input.ChoiceSet", "id": "priority", "label": "Priority", "style": "Compact", "value": "normal",
      "choices": [
        { "title": "Low", "value": "low" },
        { "title": "Normal", "value": "normal" },
        { "title": "High", "value": "high" }
      ] }
  ],
  "actions": [
    { "type": "Action.Submit", "title": "Send", "style": "positive" }
  ]
}

Actions

Actions are the buttons. They sit in the card-level actions array, inside an ActionSet, or as a selectAction on an element. There are six types.

Posting from Power Automate

The Microsoft Teams connector offers several “Post adaptive card” actions. The split that matters is display-only vs wait for a response:

• Post adaptive card in a chat or channel / Post your own adaptive card as the Flow bot — display only. Only Action.OpenUrl works; Action.Submit errors.
• Post adaptive card and wait for a response (to a user or channel) — the flow pauses until someone responds, then exposes each input value as dynamic content for later steps.
• A card in a *channel* can be answered by anyone in that channel; the flow continues on the first response and ignores the rest.
• After a response, set Update message (and Should update card) so the card visibly changes — otherwise the form just resets and people may submit again.

{
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    { "type": "TextBlock", "text": "Leave request", "size": "Large", "weight": "Bolder", "wrap": true },
    { "type": "FactSet", "facts": [
      { "title": "Requester", "value": "@{triggerBody()?['requester']}" },
      { "title": "Dates", "value": "@{triggerBody()?['dates']}" }
    ] },
    { "type": "Input.ChoiceSet", "id": "decision", "style": "Expanded", "label": "Decision",
      "choices": [
        { "title": "Approve", "value": "approve" },
        { "title": "Reject", "value": "reject" }
      ] }
  ],
  "actions": [
    { "type": "Action.Submit", "title": "Submit decision" }
  ]
}

After the action, the input ids (decision) and a submitActionId are available as dynamic content. Use them to branch the flow — e.g. a Condition on decision equals approve.

Outlook actionable messages

Outlook can render an Adaptive Card inside an email so the recipient acts without leaving the inbox. The card JSON is wrapped in a <script> tag in the email’s <head>. Outlook is a separate, more conservative schema track — design for 1.0 and test before using newer features.

<html>
<head>
  <script type="application/adaptivecard+json">
  {
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0",
    "originator": "&lt;your-provider-id-from-the-dashboard&gt;",
    "hideOriginalBody": true,
    "body": [
      { "type": "TextBlock", "text": "Approve expense #1042?", "size": "Large", "weight": "Bolder", "wrap": true }
    ],
    "actions": [
      { "type": "Action.OpenUrl", "title": "Review in browser", "url": "https://contoso.com/expenses/1042" }
    ]
  }
  </script>
</head>
<body>
  <!-- Plain-text/HTML fallback for clients that can't render the card -->
  Approve expense #1042: https://contoso.com/expenses/1042
</body>
</html>

• The email body must be HTML (plain text can’t carry the <script>), and recipients must be individual mailboxes on Exchange Online / Outlook.com — not groups or shared mailboxes.
• originator must hold a valid provider ID from the Actionable Email Developer Dashboard whenever you send to anyone other than yourself; without it the card is stripped.
• Interactive actions historically used Action.Http; the modern path is Action.Execute (1.4+) via a bot on the Outlook Actionable Messages channel.
• Actions can’t be taken on messages older than ~1 month, and there’s a limit on how many actionable messages render at once.

Templating & data binding

The Adaptive Cards Templating SDK separates layout from data: author a template with ${...} binding expressions, then merge it with a JSON data object at render time. Great for bots and custom apps that bind cards in code.

{
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    { "type": "TextBlock", "text": "Hello ${user.name}", "weight": "Bolder", "wrap": true },
    { "type": "Container", "$data": "${orders}", "items": [
      { "type": "TextBlock", "text": "${id} — ${status}", "wrap": true,
        "$when": "${status != 'cancelled'}" }
    ] }
  ]
}

import * as ACData from "adaptivecards-templating";

const template = new ACData.Template(cardTemplateJson);
const card = template.expand({
  $root: { user: { name: "Priya" }, orders: [{ id: "A-1", status: "shipped" }] }
});

Versions & host support

Schema support varies by host, so a feature that works in Teams may be ignored in Outlook. Target the version your host supports, and provide fallbacks.

• `fallbackText` on the card renders when the host is older than version — always set a meaningful sentence.
• `fallback` on an element/action swaps in a simpler alternative (or "drop") when the host can’t render it — e.g. Action.Execute → Action.Submit.
• `requires` (1.2) declares a minimum feature version on an element so the host can trigger that element’s fallback.
• When in doubt, set the Designer’s Target version to your host and let it flag unsupported elements before you ship.

Styling, accessibility & gotchas

• Describe intent, not pixels. Use size/weight/color/isSubtle and container style tokens; the host config maps them to its theme so cards look native in light and dark mode.
• Host images on a public HTTPS URL. Outlook and Teams won’t render data-URI / base64 images, and a URL that needs auth shows nothing. Always set altText.
• Always `wrap: true` on TextBlock, or text clips to one line. Test long values and narrow widths (Teams mobile, meeting side panel).
• Accessibility: meaningful altText, real label text on inputs (label), and don’t signal meaning with colour alone — Teams ignores button colour styling anyway.
• Dark mode: container style tokens adapt automatically; avoid hard-coded color hacks. Outlook actionable messages historically don’t restyle for dark mode.
• Validate the JSON in the Designer before pasting into a flow — most “card didn’t render” issues are curly quotes, a trailing comma, or a missing version.
• Keep cards short. Long cards get truncated in compact surfaces; link out with Action.OpenUrl for detail rather than cramming everything in.