Teams Message Formatting

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

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:

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:

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

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 (Workflows) - Microsoft Teams
• Retirement of Office 365 connectors within Microsoft Teams - Microsoft 365 Dev Blog