Skip to main content

How to Make Adaptive Card Inputs Required

· 7 min read
Jagdish Kumawat
Founder @ Dewiride

A form that lets people send it half filled in sends you half the answers. Adaptive Cards can stop that themselves: mark an input as required, give it an error message, and the chat app won't send the card until it's filled in, or until text matches a pattern you choose.

The Properties​

Since version 1.3 of the card format, every input has these properties for checking what people enter:

PropertyOnWhat it does
isRequiredEvery inputThe card isn't sent until the input has a value
errorMessageEvery inputThe text shown under the input when its check fails
labelEvery inputThe input's label; a required input's label gets a mark, by default an asterisk
regexInput.TextA regular expression the text has to match
maxLengthInput.TextThe longest text allowed
min, maxInput.Number, Input.Date, Input.TimeThe lowest and highest value allowed

Microsoft's documentation on input validation recommends label over placeholder for naming an input, because a label stays visible and screen readers connect it to its input. The checks run in the chat app when someone selects an Action.Submit button: if an input fails, its error message appears and nothing is sent.

The Example​

The card for this post signs people up for a team newsletter. It asks for a work email, which must look like an email address, and how often to send the newsletter, which must be chosen:

Cards/SignupCard.json
{
"type": "AdaptiveCard",
"$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"text": "Sign up for the team newsletter",
"size": "Medium",
"weight": "Bolder"
},
{
"type": "Input.Text",
"id": "email",
"label": "Work email",
"style": "Email",
"isRequired": true,
"regex": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
"errorMessage": "Enter an email address, such as sam@example.com."
},
{
"type": "Input.ChoiceSet",
"id": "frequency",
"label": "How often?",
"isRequired": true,
"errorMessage": "Pick how often you'd like it.",
"choices": [
{ "title": "Every week", "value": "weekly" },
{ "title": "Every month", "value": "monthly" }
]
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Sign up",
"data": { "verb": "signUp" }
}
]
}

Cards/SignupCard.json in a macOS-style editor window: the Input.Text for the work email with label, style Email, isRequired, a regex and an errorMessage, and the Input.ChoiceSet for how often with isRequired and its own errorMessage

  • "style": "Email" is a hint to the chat app that the input holds an email address. The regex is what checks it.
  • regex does the checking: one or more characters that aren't @ or a space, an @, more of the same, a dot, and more again. In JSON, each backslash is written twice, so \s (any space) appears as \\s.
  • One errorMessage covers both checks on the email: it's shown whether the input is empty or doesn't match the pattern.

A small agent sends the card when someone types newsletter and answers its Sign up button with AdaptiveCards.OnActionSubmit("signUp", ...), as in How to Handle Adaptive Card Submit Actions in the Microsoft 365 Agents SDK in C#.

Prerequisites​

  • The Microsoft 365 Agents Playground, to try the card. agentsplayground --version should print 0.2.30; if the command isn't found, install it with npm install -g @microsoft/m365agentsplayground.

Step 1: Send the Card Empty​

With the agent running on port 3978, start the Agents Playground:

Terminal 2
agentsplayground -e http://localhost:3978/api/messages -c emulator

Send newsletter, and select Sign up without filling anything in:

The Agents Playground chat: the newsletter card after Sign up was selected empty, with Enter an email address, such as sam@example.com. under Work email and Pick how often you'd like it. under How often?

Both labels carry a red asterisk, both error messages appeared, and the Playground's Log Panel shows that nothing was sent.

Step 2: Enter an Address That Doesn't Match​

Type sam@example in Work email, pick Every week, and select Sign up again:

The card with sam@example in Work email and Every week chosen: the email's error message is still shown, the frequency's is gone

The frequency now passes, but sam@example has no dot after the @, so the pattern doesn't match and the card still won't send.

Step 3: Send a Valid Card​

Change the email to sam@example.com and select Sign up:

The card cleared after sending, and the agent's answer You're signed up. The newsletter goes to sam@example.com every week.

Both checks passed, the card was sent, and the agent answered. Its handler checks the values again before acting on them, because these checks run in the chat app, which your agent doesn't control: another app may skip them, and an old copy of a card may not have them.

Common Mistakes​

MistakeWhat happensDo this instead
Single backslashes in regex, such as \sThe card's JSON is invalidWrite each backslash twice in JSON
Using placeholder as the only name for an inputThe name disappears once people type, and screen readers may not read itGive every input a label
A required input on a card with a Cancel buttonThe Cancel button is blocked until the input is filledHow to Add a Cancel Button That Skips Validation to an Adaptive Card
Trusting the card's checks in the agentValues that skipped them reach your codeCheck again in the handler

Troubleshooting​

SymptomLikely causeFix
No asterisk on a required inputThe input has no labelAdd one
A valid address is rejectedThe pattern is stricter than you meantTest the pattern on real examples

FAQ​

Does the chat app check the values, or my agent?​

The chat app, before it sends anything. Your agent only ever sees cards that passed, from apps that run the checks, which is why the agent should still check what it receives.

Can a check box be required?​

Yes, isRequired works on Input.Toggle too. A required check box has to be ticked before the card is sent, which suits I accept the terms.

Can a date be limited to the future?​

Input.Date has min and max. Microsoft's documentation notes that some apps enforce them in the date picker itself, by not letting people pick a day outside the range, and then the error message may not appear.

Conclusion​

Give every input a label, mark the ones that must be filled in with isRequired, add an errorMessage, and use regex, maxLength, min or max for values that have to follow a rule. The chat app then keeps the card from being sent until it passes, and people see exactly what to fix, next to the input that needs it.

Additional Resources​