Teams Message Formatting

Microsoft Teams has several incompatible text systems. Pick the surface first, then write the text for that surface.

CRITICAL: Four Markup Systems

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

Quick Decision Tree

What are you formatting?
|-- Bot plain reply or proactive message
|   |-- Simple text                         -> `textFormat: "markdown"` or default SDK text
|   |-- Need user/tag mention                -> `<at>...</at>` plus activity `entities`
|   `-- Need rich UI or inputs               -> use $teams-adaptive-cards
|-- Adaptive Card text
|   |-- TextBlock / FactSet                  -> limited Adaptive Card Markdown
|   |-- Header                               -> use TextBlock `size`/`weight`, not `#`
|   |-- Table                                -> use Table element, not Markdown table
|   `-- Code                                 -> use CodeBlock if Teams/card version supports it
|-- Microsoft Graph chatMessage
|   |-- Plain text only                      -> body `contentType: "text"`
|   |-- Formatting, mentions, attachments    -> body `contentType: "html"`
|   `-- Adaptive Card attachment             -> use body `<attachment id="...">` plus attachments
|-- Workflows / Incoming Webhook
|   |-- New implementation                   -> Adaptive Card webhook wrapper
|   `-- Legacy connector                     -> MessageCard only; avoid new connector design
`-- Simple hero/thumbnail card text          -> limited XML/HTML in `text`, not Markdown

Bot Activity Text

Use textFormat when constructing raw Bot Framework activities:

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

Teams supports only a subset of Markdown across platforms. Use simple bold, italic, links, preformatted text, and blockquotes. Avoid relying on tables, headings, horizontal rules, and image links in text-only bot messages.

For mention text, 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 in text; otherwise Teams ignores the mention.

Adaptive Card Text

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

Unsupported in Adaptive Card Markdown: headings, tables, images, preformatted text, and blockquotes. Use Adaptive Card elements instead: TextBlock styling for headings, Table for tables, Image for images, and CodeBlock for code when appropriate.

Graph chatMessage Text

Graph chatMessage.body can be text or Teams-restricted html. Use HTML when the body contains mentions, inline links, 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 such as <at>, <attachment>, <emoji>, <customemoji>, and <codeblock>. The body is not arbitrary browser HTML: avoid <div>, inline styles, script-like content, and layout CSS. See references/GRAPH-CHATMESSAGE.md before building Graph payloads.

Escaping User Content

Escape based on the destination:

Never concatenate untrusted user content into Graph HTML, Bot XML, or mention markup without escaping it first.

Anti-Patterns

Reference Documentation

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 - Microsoft Teams