Fix Adaptive Cards: Rendering, Schema & Integration Issues

Everything starts here. A malformed JSON payload causes silent failures that look identical to rendering SDK problems or host app bugs, so rule this out before anything else.

Open the Adaptive Cards Designer, paste your payload into the Card Payload Editor panel, and look at the bottom status bar. Any JSON syntax errors will show up immediately in red. Fix those first, a missing comma, an unclosed brace, or a misquoted string will stop the whole card from parsing.

Once the JSON is syntactically valid, look at the Warnings panel on the right side of the designer. This is where schema-level problems appear: unknown element types, invalid property values, missing required fields. Common ones I see are:

• type property missing from an element, every element in the card body needs an explicit type declaration
• Using style: "attention" on a container when the target host's schema version doesn't support that style value
• Action types spelled incorrectly, Action.Submit not Action.submit (it's case-sensitive)

For programmatic validation, use the adaptivecards npm package:

npm install adaptivecards

// In your validation script
const AdaptiveCards = require('adaptivecards');
const card = new AdaptiveCards.AdaptiveCard();
card.parse(yourCardPayload);
const validationResults = card.validateProperties();
validationResults.items.forEach(item => {
  console.log(`[${item.phase}] ${item.message}`);
});

When this runs cleanly with zero validation items, you know your JSON is solid. You should see the card render correctly in the designer across all target host apps. If you still see issues after this, the problem is in the rendering SDK setup, move to Step 2.

If you're building a custom host application, your own website, desktop app, or mobile app, you need to install the platform-specific rendering SDK manually. This is what transforms your JSON into actual native UI. Without it, nothing renders. The SDK is not bundled with frameworks automatically.

Adaptive Cards officially supports these platforms with dedicated SDKs: Android, iOS, JavaScript, ASP.NET, .NET WPF, Windows, and ReactNative. Pick the one that matches your stack.

For JavaScript/Web apps:

npm install adaptivecards

Then in your app code:

import * as AdaptiveCards from 'adaptivecards';

const adaptiveCard = new AdaptiveCards.AdaptiveCard();

// Point to your host config
adaptiveCard.hostConfig = new AdaptiveCards.HostConfig({
  fontFamily: "Segoe UI, Helvetica Neue, sans-serif"
});

adaptiveCard.parse(yourCardPayload);
const renderedCard = adaptiveCard.render();

// Attach to your DOM element
document.getElementById('card-container').appendChild(renderedCard);

For .NET / ASP.NET:

Install-Package AdaptiveCards -Version 2.7.3

For Android, add to your build.gradle:

implementation 'io.adaptivecards:adaptivecards-android:2.7.0'

One thing developers miss: after installing the SDK, you still need to supply a Host Config. If you skip the host config, the SDK uses internal defaults that may not match what you expect visually. The Host Config is a separate JSON object that controls the look and feel, colors, font sizes, element spacing, image sizes. The card author owns the content; the host app owns the styling. That's the core design contract of Adaptive Cards, and the Host Config is how you enforce it.

After installing and running, open your browser's developer console. The JavaScript SDK logs rendering warnings there, including elements it skipped due to host config restrictions. That's a fast way to spot what's silently getting dropped.

Teams is the most common surface where Adaptive Cards break in ways that make no sense at first glance. I've seen cards that work perfectly in the Bot Framework Emulator but arrive in Teams as plain text. Here's what's going on and how to fix it.

Teams Adaptive Cards are delivered through the Bot Framework. The Bot Framework wraps your Adaptive Card payload inside an attachment object. If that wrapper is malformed, Teams silently falls back to whatever text fallback you set (or nothing at all). Your card payload must be structured like this:

const card = {
  type: "AdaptiveCard",
  version: "1.3",
  body: [ /* your elements */ ],
  actions: [ /* your actions */ ]
};

const message = MessageFactory.attachment(
  CardFactory.adaptiveCard(card)
);

The CardFactory.adaptiveCard() call is the part people miss, it correctly sets the contentType to application/vnd.microsoft.card.adaptive. If you manually build the attachment object and get that content type wrong, Teams won't know to render it as an Adaptive Card.

Second thing to check: Teams has its own schema version support ceiling, and it doesn't always match the latest Adaptive Cards schema release. As of early 2026, Teams Desktop supports up to schema 1.5 for most tenants, but older clients may cap at 1.3. Test with version: "1.3" first to establish a baseline that works everywhere, then selectively upgrade features that require newer schema versions.

Third: if your card has Action.Submit buttons and they're not responding, check that your bot has the teams channel enabled and that the serviceUrl in the incoming activity matches what Teams is sending. Mismatched service URLs cause submit actions to fail silently.

After applying these fixes, test the card in both the Teams web client and the Teams desktop app, they sometimes behave differently on schema version support, and you want to confirm both surfaces work before shipping.

Outlook Actionable Messages have additional requirements that go beyond just getting the JSON right. I've helped teams debug this for hours only to find the issue was a registration problem, not a code problem at all.

For Outlook to render your Adaptive Card as an actionable message rather than falling back to the plain HTML email body, your sending email address (or sending domain) must be registered with Microsoft's Actionable Email Developer Dashboard. This is mandatory for production. Without registration, Outlook silently ignores the card markup.

Go to outlook.office.com/connectors/oam/publish and register your sender. During development you can use self-service registration and test only to your own mailbox. For organization-wide or global deployment, you need admin approval.

Once registered, your email's <head> must include the correct script tag that embeds the Adaptive Card payload:

<script type="application/adaptivecard+json">
{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "originator": "YOUR-ORIGINATOR-ID-FROM-REGISTRATION",
  "body": [ ... ],
  "actions": [ ... ]
}
</script>

The originator field is critical, it ties the card back to your registered application ID. Get this wrong and Outlook won't render the card. The value comes from your registration record in the Actionable Email Developer Dashboard.

Also: Outlook Actionable Messages support a more limited schema version than Teams. Stick to schema version 1.0 for maximum compatibility, especially if you're targeting both Outlook desktop and Outlook on the web. Elements like ColumnSet and FactSet work well; more advanced layout features from newer schema versions may not render correctly in all Outlook clients.

When testing, use a personal Outlook.com address first, the self-service registration process is faster and you can iterate without waiting for IT admin approval.

Adaptive Cards Templating is one of the most powerful features, it lets you separate your card layout from your data so you can reuse the same template with different datasets. But it's also where a lot of silent bugs hide.

The templating system uses data binding expressions wrapped in curly braces. When the bound property doesn't exist in your data, the element doesn't render an error, it just shows nothing. That's intentional behavior for safety, but it makes debugging genuinely painful.

Install the templating SDK alongside the rendering SDK:

npm install adaptivecards-templating

Then use it like this:

import { Template } from 'adaptivecards-templating';

const template = new Template(yourCardTemplate);

// This is where binding happens, pass your data object here
const cardPayload = template.expand({
  $root: {
    title: "Invoice #4821",
    amount: "$1,240.00",
    dueDate: "2026-05-01"
  }
});

// Now render cardPayload as you normally would
adaptiveCard.parse(cardPayload);

To debug binding errors, add a console.log(cardPayload) after the template.expand() call and inspect the output JSON. Look for any text nodes that still contain raw binding expressions like ${title} instead of resolved values, those tell you exactly which data properties are missing or misnamed.

Common binding mistakes:

• Using ${item.name} when iterating over an array but the array items use a different property name
• Forgetting that binding expressions are case-sensitive, ${Title} and ${title} are different
• Nesting data incorrectly under $root, the entire data context needs to be under $root in the expand call

The template service at templates.adaptivecards.io can automatically find a template for a given data shape and even pre-populate it. If you're building something data-driven and want to skip manual template authoring, this is worth exploring, you feed it your data schema and it returns a ready-to-use card template. That said, review whatever it returns before shipping to production; auto-generated templates sometimes need layout tweaks for your specific use case.