diff --git a/msteams-platform/bots/how-to/format-your-bot-messages.md b/msteams-platform/bots/how-to/format-your-bot-messages.md index 4c4004f7aec..856d886302a 100644 --- a/msteams-platform/bots/how-to/format-your-bot-messages.md +++ b/msteams-platform/bots/how-to/format-your-bot-messages.md @@ -27,23 +27,80 @@ Microsoft Teams supports the following formatting options: | `TextFormat` value | Description | | --- | --- | -| `plain` | The text must be treated as raw text with no formatting applied.| -| `markdown` | The text must be treated as Markdown formatting and rendered on the channel as appropriate. | +| `plain` | The text is treated as raw text with no formatting applied. | +| `markdown` | The text is treated as Markdown formatting and rendered on the channel as appropriate. | +| `extendedmarkdown` | The text is treated as extended Markdown, supporting richer rendering for text-only messages such as tables, task lists, code fences, math equations, images, at-mentions, and citations. | | `xml` | The text is simple XML markup. | -Teams supports a subset of `markdown` and `xml` or HTML formatting tags. Your bot can also mention other users and tags in text messages posted in channels. For more information, see [add mentions to your messages](~/bots/how-to/conversations/channel-and-group-conversations.md#add-mentions-to-your-messages). +For `markdown`, Teams supports a subset of Markdown formatting. For `extendedmarkdown`, Teams supports CommonMark syntax along with additional features such as tables, task lists, code fences, math equations, images, at-mentions, and citations. In extended Markdown content, `` is the only supported HTML tag. For `xml`, Teams supports a subset of XML formatting tags. + +Your bot can also mention other users and tags in text messages posted in channels. For more information, see [add mentions to your messages](~/bots/how-to/conversations/channel-and-group-conversations.md#add-mentions-to-your-messages). + +### Enable extended Markdown + +To use extended Markdown formatting in bot messages, set the `textFormat` property to `"extendedmarkdown"` in your `Activity` object: + +# [JSON](#tab/json) + +```json +{ + "type": "message", + "textFormat": "extendedmarkdown", + "text": "### Sprint update\n\n- [x] Build completed\n- [1] Deploy pending" +} +``` + +# [C#](#tab/csharp) + +```csharp +var activity = new Activity +{ + Type = ActivityTypes.Message, + Text = "### Sprint update\n\n- [x] Build completed\n- [1] Deploy pending", + TextFormat = "extendedmarkdown" +}; + +await app.SendActivity(conversationId, activity); +``` + +# [TypeScript](#tab/typescript) + +```typescript +const activity = { + type: "message", + text: "### Sprint update\n\n- [x] Build completed\n- [1] Deploy pending", + textFormat: "extendedmarkdown" +}; + +await app.sendActivity(conversationId, activity); +``` + +# [Python](#tab/python) + +```python +activity = Activity( + type=ActivityTypes.message, + text="### Sprint update\n\n- [x] Build completed\n- [1] Deploy pending", + text_format="extendedmarkdown" +) + +await app.send_activity(conversation_id, activity) +``` + +--- The following limitations apply to formatting: -- Text-only messages don't support table formatting. +- Text-only messages in `plain` format don't support table formatting. - Rich cards support formatting in the text property only, not in the title or subtitle properties. -- Rich cards don't support Markdown or table formatting. +- For rich card payload properties, `markdown` and `extendedmarkdown` formatting aren't supported. +- Older or unsupported clients can show unsupported constructs as plain text. After you format text content, ensure that your formatting works across all platforms supported by Teams. -## Cross-platform support +## Standard Markdown support -Some styles aren't supported across all platforms. The following table provides a list of styles and which of these styles are supported in text-only messages and rich cards: +Some styles aren't supported across all platforms. The following table provides a list of standard Markdown styles and which of these styles are supported in text-only messages and rich cards: | Style | Text-only messages | Rich cards - XML only | | --- | :---: | :---: | @@ -59,6 +116,101 @@ Some styles aren't supported across all platforms. The following table provides | Hyperlink | ✔️ | ✔️ | | Image link | ❌ | ❌ | +## Extended Markdown features + +When using `textFormat: "extendedmarkdown"`, the following features are available in text-only messages: + +| Feature | Syntax | Description | +| --- | --- | --- | +| **Fenced code blocks** | Use triple backticks with a language identifier, for example ` ```python ` | Syntax-highlighted code fences | +| **Math equations** | Inline: `$E = mc^2$` Block: `$$\int_0^\infty f(x)dx$$` | LaTeX/KaTeX math notation rendered inline or as a block | +| **Images and image URLs** | `![alt text](https://example.com/image.png)` | Render image content from Markdown | +| **At-mentions** | `User Name` or `GroupName` | Reference users or groups | +| **Citations** | `[#]` in message text + `entities` array in Activity | Inline citation markers with reference details. For more information, see [citations](bot-messages-ai-generated-content.md#citations). | +| **Tables** | Pipe-delimited rows with separator line | Structured tabular data with optional column alignment | +| **Task lists** | `- [ ] item` / `- [x] item` | Checklist-style items; checkboxes are read-only | + +### At-mention support + +Mention users and groups in your bot messages. At-mentions work with both standard Markdown and extended Markdown: + +```markdown +Hello Jane Smith, please review this. + +Notifying team: Engineering Team +``` + +### Fenced code blocks + +Use triple backticks with a language identifier to display syntax-highlighted code in your bot messages. + +````markdown +```python +def fibonacci(n): + if n <= 1: + return n + return fibonacci(n-1) + fibonacci(n-2) +``` +```` + +### Math equations + +Use LaTeX/KaTeX syntax to render mathematical notation. Use single dollar signs for inline equations and double dollar signs for block equations. + +```markdown +Inline math: $E = mc^2$ + +Block math: +$$ +\int_0^\infty f(x)dx +$$ +``` + +### Images + +Use standard Markdown image syntax to render images in your bot messages. + +```markdown +![Build status](https://example.com/build-status.png) +``` + +### Citations + +Cite sources in your bot messages using `[#]` notation in the message text and providing citation details in the Activity `entities` array. For more information on how to add citations, see [citations](bot-messages-ai-generated-content.md#citations). + +### Tables + +Use GitHub Flavored Markdown (GFM) table syntax to present structured data. Tables support column alignment using colons in the separator row. + +```markdown +| Feature | Status | Priority | +|:--------|:------:|----------:| +| Tables | Done | High | +| Math | Done | High | +``` + +In this example, the first column is left-aligned, the second is centered, and the third is right-aligned. + +### Task lists + +Use task list syntax to display completed and pending items in your bot messages. + +```markdown +- [x] Checkout code +- [x] Install dependencies +- [x] Run unit tests +- [ ] Deploy to production +``` + +> [!NOTE] +> Task list checkboxes are read-only. Users can't interact with them to change their state. + +## Streaming with extended Markdown + +[!INCLUDE [streaming-with-extended-markdown](includes/streaming-with-extended-markdown.md)] + +For detailed information about streaming implementation, see [Stream bot messages](../streaming-ux.md). + After checking cross-platform support, ensure that support by individual platforms is also available. ## Support by individual platform diff --git a/msteams-platform/bots/how-to/includes/streaming-with-extended-markdown.md b/msteams-platform/bots/how-to/includes/streaming-with-extended-markdown.md new file mode 100644 index 00000000000..293c93f6449 --- /dev/null +++ b/msteams-platform/bots/how-to/includes/streaming-with-extended-markdown.md @@ -0,0 +1,9 @@ +When streaming with extended Markdown, your bot can progressively send content that includes: + +- **Fenced code blocks**: Render only after the closing ` ``` ` fence is received on its own line +- **Math equations**: Render after the closing `$` or `$$` delimiter is received +- **Images and image URLs**: Render after the closing parenthesis of the image URL passes validation +- **At-mentions**: Render when `...` tags are complete and valid +- **Citations**: Render when `[#]` markers and corresponding `entities` are present in the Activity +- **Tables**: Render when enough rows are received to form a valid table structure +- **Task lists**: Render when list items and checkbox markers (`- [ ]`, `- [x]`) are complete diff --git a/msteams-platform/bots/how-to/teams-conversational-ai/ai-ux.md b/msteams-platform/bots/how-to/teams-conversational-ai/ai-ux.md index 228ecf4bea1..16aa3c4869b 100644 --- a/msteams-platform/bots/how-to/teams-conversational-ai/ai-ux.md +++ b/msteams-platform/bots/how-to/teams-conversational-ai/ai-ux.md @@ -66,7 +66,11 @@ Use the following types of updates while streaming responses: - Informative updates: Send information on the sub-steps as the agent generates the response before it sends the final response. - Response streaming: Send the intermediate states of the final response while the LLM creates its full response. -Use [Teams SDK](/microsoftteams/platform/teams-ai-library/) to add streaming to the agent. +For detailed streaming implementation guidance, see [Stream agent messages](../../streaming-ux.md). + +### Format agent messages with extended Markdown + +You can format agent messages using extended Markdown (`textFormat: "extendedmarkdown"`) for rich formatting. Extended Markdown supports features such as tables, task lists, code fences, math equations, images, at-mentions, and citations. For more information, see [Format your bot messages](../format-your-bot-messages.md#enable-extended-markdown). ### Ensure the agent response contains citations @@ -74,7 +78,7 @@ Users must know the sources an agent uses to generate its final response. Identi :::image type="content" source="../../../assets/images/bots/ai-citation.png" alt-text="Image shows an example of citations in agents." border="false"::: -Use [Teams SDK](/microsoftteams/platform/teams-ai-library/) to add streaming to the agent. +For more information, see [Bot messages with AI-generated content](../bot-messages-ai-generated-content.md#citations). > [!NOTE] > @@ -94,7 +98,7 @@ Examples of AI label: :::image type="content" source="../../../assets/images/bots/ai-labels-2.png" alt-text="Image shows an example of AI label for a confidential message." border="false"::: -Use [Teams SDK](/microsoftteams/platform/teams-ai-library/) to add streaming to the agent. +For more information, see [AI label](../bot-messages-ai-generated-content.md#ai-label). ### Ensure that the agent maintains intelligent conversation @@ -173,5 +177,5 @@ To enable the app profile card for your agents or bots, add the `features` field ## See also - [Teams SDK](teams-conversation-ai-overview.md) -- [Stream bot messages](../../streaming-ux.md) +- [Stream agent messages](../../streaming-ux.md) - [Enhance AI-generated bot messages](../bot-messages-ai-generated-content.md) diff --git a/msteams-platform/bots/streaming-ux.md b/msteams-platform/bots/streaming-ux.md index 76585bc7884..c9f29468a09 100644 --- a/msteams-platform/bots/streaming-ux.md +++ b/msteams-platform/bots/streaming-ux.md @@ -54,6 +54,8 @@ You can implement streaming bot messages in your app in one of the following way In addition, you'll also learn how to [stop streaming bot response](#stop-streaming-bot-response) and [response codes](#response-codes) for streaming bot messages. +For guidance on formatting bot messages during streaming, including code examples for different text formats, see [Format your bot messages](how-to/format-your-bot-messages.md). + ## Stream message through Teams SDK [!INCLUDE [teams-ai-lib-v2-rec](../includes/teams-ai-lib-v2-rec.md)] @@ -83,7 +85,11 @@ Through streaming, your AI-powered bot can offer an experience that is engaging 3. **Format the final streamed message**: - Using AI SDK, text messages and simple markdown can be formatted while they're being streamed. However, for Adaptive Cards, images, or rich HTML, the formatting can be applied once the final message is complete. The bot can send attachments only in the final streamed chunk. + Text messages with extended Markdown (using `textFormat: "extendedmarkdown"`) are formatted as they're streamed. Extended Markdown content such as fenced code blocks, math equations, images, tables, at-mentions, citations, and task lists render progressively at safe boundaries. For standard Adaptive Cards attachments or rich HTML, formatting is applied once the final message is complete. The bot can send attachments only in the final streamed chunk. + + [!INCLUDE [streaming-with-extended-markdown](how-to/includes/streaming-with-extended-markdown.md)] + + For more information about supported features and syntax, see [Format your bot messages using Extended Markdown features](how-to/format-your-bot-messages.md#enable-extended-markdown). The following example shows the streaming response in an AI-powered bot: