Teams Message Formatting Skill

Teams Message Formatting

Microsoft Teams has several incompatible text systems. Pick the surface first, then write the text for that surface — most rendering bugs come from using one surface's syntax on another.

CRITICAL: Four Markup Systems

| System | Used In | Bold | Link | Mention | |--------|---------|------|------|---------| | Bot text markdown | Bot Framework/Teams SDK activity text (default) | **bold** | [text](url) | <at>Name</at> plus activity entities | | Bot text xml | Bot activity textFormat: "xml" and hero/thumbnail card text | bold | <a href="url">text</a> | <at>Name</at> plus activity entities | | Adaptive Card Markdown | TextBlock.text, Fact.title, Fact.value | **bold** | [text](url) | <at>Name</at> plus root msteams.entities | | Graph chatMessage HTML | Microsoft Graph chatMessage.body.contentType: "html" | bold | <a href="url">text</a> | <at id="0">Name</at> plus mentions array |

Do not mix them. Slack mrkdwn (*bold*, <url|text>) is wrong everywhere in Teams. Full standard Markdown is also wrong in Adaptive Cards: headings, tables, images, preformatted text, and blockquotes are not supported in TextBlock.

Quick Decision Tree

What are you formatting?
|-- Bot reply or proactive bot message
|   |-- Simple text                          -> textFormat "markdown" (or SDK default)
|   |-- User/tag mention                     -> <at>...</at> plus activity entities
|   `-- Rich UI, inputs, buttons             -> Adaptive Card ($teams-adaptive-cards)
|-- Adaptive Card text
|   |-- TextBlock / FactSet                  -> limited Adaptive Card Markdown only
|   |-- Heading                              -> TextBlock size/weight/style, never `#`
|   |-- Table                                -> Table element, never Markdown table
|   `-- Code                                 -> CodeBlock element, never backticks
|-- Microsoft Graph chatMessage (delegated send)
|   |-- Plain text                           -> body contentType "text"
|   |-- Formatting, mentions, emoji, code    -> body contentType "html"
|   `-- Adaptive Card                        -> <attachment id> placeholder + attachments
|-- Service-to-channel webhook
|   |-- Anything new                         -> Workflows webhook + Adaptive Card wrapper
|   `-- Legacy webhook.office.com URL        -> retired May 2026; migrate to Workflows
`-- Hero/thumbnail card                      -> XML/HTML subset in `text` only; no Markdown,
                                                no formatting in title/subtitle

Bot Activity Text

Set textFormat when constructing raw Bot Framework activities (markdown is the default):

{
  "type": "message",
  "textFormat": "markdown",
  "text": "**Build failed** in [CI](https://example.com/run/123)."
}

Bot text Markdown support varies by client, so stay inside the safe subset:

Safe on desktop, iOS, and Android: bold, italic, links, preformatted text, blockquotes.
Desktop only: ordered and unordered lists.
Not on Android: strikethrough.
Never supported in text-only bot messages: headings, horizontal rules, tables, image links. Use an Adaptive Card for those.

Bot messages have an approximate 100 KB limit (text, mentions, reactions); stay under 80 KB or the send fails with 413 MessageSizeTooBig.

For mentions, include both the visible <at>...</at> text and a matching entities item:

{
  "type": "message",
  "text": "Hey <at>Ada Lovelace</at>, the deployment is ready.",
  "entities": [
    {
      "type": "mention",
      "text": "<at>Ada Lovelace</at>",
      "mentioned": {
        "id": "29:teams-user-id",
        "name": "Ada Lovelace"
      }
    }
  ]
}

The entities[].text value must exactly match a substring of text (including any @ prefix); otherwise Teams ignores the mention. The mentioned.id accepts a Teams user ID (29:...), a Microsoft Entra Object ID, or a UPN. See references/MENTIONS.md for tag, team, and channel mentions.

Adaptive Card Text

Use limited Markdown only in TextBlock.text, Fact.title, and Fact.value:

| Format | Syntax | Notes | |--------|--------|-------| | Bold | **bold** | Standard Markdown bold | | Italic | _italic_ | Underscore style is what the Teams docs show | | Link | [text](https://example.com) | URL must be absolute | | Bullet list | - Item 1\r- Item 2 | \r or \n between items | | Ordered list | 1. First\r2. Second | Keep list text short | | Line break | \n\n outside lists | \n\n inside a list indents the next item — use \r there |

Unsupported in Adaptive Card Markdown: headings, tables, images, preformatted text, and blockquotes. HTML is never supported in Adaptive Cards. Use card elements instead: TextBlock size/weight/style: "heading" for headings, Table for tables, Image for images, CodeBlock for code.

Graph chatMessage Text

Graph chatMessage.body is text or Teams-restricted html. Use HTML whenever the body contains mentions, links, emphasis, attachments, emoji tags, or code blocks:

{
  "body": {
    "contentType": "html",
    "content": "<p><strong>Build failed</strong> in <a href=\"https://example.com/run/123\">CI</a>.</p>"
  }
}

Graph supports Teams-specific body elements: <at id="N">, <attachment id="...">, <emoji>, <customemoji>, and <codeblock class="..."><code>. The body is not arbitrary browser HTML — <div>, inline styles, and layout CSS may be ignored or break rendering. Normal sends are delegated-only (ChannelMessage.Send / ChatMessage.Send); application-permission send is migration-only. Read references/GRAPH-CHATMESSAGE.md before building Graph payloads.

Escaping User Content

Escape based on the destination, innermost format first:

| Destination | Escape | |-------------|--------| | JSON string | JSON escaping for backslash, quote, newline | | Bot XML / Graph HTML | &, <, >, ", ' when inserted as text | | Adaptive Card Markdown | Escape or strip Markdown metacharacters when text must render literally | | Mention display text | Keep the visible <at>...</at> text and metadata exactly synchronized |

Never concatenate untrusted user content into Graph HTML, Bot XML, or mention markup without escaping it first — unescaped < or & corrupts the whole body.

Anti-Patterns

| Anti-Pattern | Problem | Fix | |--------------|---------|-----| | Slack mrkdwn in Teams | Renders literally or incorrectly | Use the markup for the target surface | | Markdown table or # heading in TextBlock | Unsupported, renders as literal text | Table element; TextBlock size/weight/style | |  or any HTML in Adaptive Card text | HTML unsupported in cards | **bold** or TextBlock styling | | Triple-backtick code in TextBlock | Preformatted text unsupported | CodeBlock element | | Graph mention without mentions array | Renders as text, no notification | Add matching mentions entry | | Bot mention without entities | Renders as text, no notification | Add matching activity entity | | New MessageCard/connector integration | O365 connectors retired May 2026 | Workflows webhook or notification bot with Adaptive Cards | | Graph chatMessage for app-only notifications | Application send is migration-only | Bot proactive messaging or Workflows | | Lists or strikethrough in bot text for mobile users | Lists desktop-only; strikethrough missing on Android | Adaptive Card, or restructure the text |

Reference Documentation

| Read | When | |------|------| | references/CHEATSHEET.md | You need exact syntax for any surface fast | | references/MARKDOWN-HTML.md | Bot Markdown/XML per-platform support, Adaptive Card Markdown detail, hero-card HTML, MessageCard legacy | | references/MENTIONS.md | Any mention: bot, Adaptive Card, Graph, user, tag, team, channel, or stripping incoming bot mentions | | references/GRAPH-CHATMESSAGE.md | Building Graph chatMessage payloads: HTML restrictions, codeblock/emoji tags, attachments, permissions |

Sources

Format your bot messages - Microsoft Teams
Format text in cards - Microsoft Teams
Channel and group chat bot conversations - Microsoft Teams
Send chatMessage in a channel or chat - Microsoft Graph
Teams messaging APIs in Microsoft Graph - Microsoft Graph
Create an Incoming Webhook (Workflows) - Microsoft Teams
Retirement of Office 365 connectors within Microsoft Teams - Microsoft 365 Dev Blog

Agent Skills: Teams Message Formatting

Install this agent skill to your local

Skill Files