MM Blocks Documentation#1508
Open
larkox wants to merge 6 commits into
Open
Conversation
|
Newest code from mattermost has been published to preview environment for Git SHA 8a38941 |
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
💤 Files with no reviewable changes (1)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThis pull request adds MM Blocks reference documentation and updates related integration guides to describe MM Blocks, markdown actions, legacy attachments, webhooks, and slash command payload fields. ChangesMM Blocks Integration Framework Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
site/content/integrate/reference/markdown-actions/_index.md (1)
215-220:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate the security bullet to match the new action ID charset.
This section still says action IDs are “alphanumeric strings”, but this page now documents
[A-Za-z0-9_-]+. Please align the wording to avoid conflicting guidance.Suggested doc fix
-- Action IDs are validated as alphanumeric strings and matched case-sensitively. +- Action IDs are validated against `[A-Za-z0-9_-]+` and matched case-sensitively.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@site/content/integrate/reference/markdown-actions/_index.md` around lines 215 - 220, The security bullet that currently says Action IDs are “alphanumeric strings” is out of date; change the wording for the Action ID bullet (the line describing action ID validation) to state the new allowed charset (e.g. "Action IDs must match the pattern [A-Za-z0-9_-]+ — alphanumerics, underscore and hyphen — and are matched case-sensitively") so the documentation for Action IDs and their validation matches the current behavior.site/content/integrate/slash-commands/custom/_index.md (1)
104-104:⚠️ Potential issue | 🟠 Major | ⚡ Quick winComplete the slash-command
propscontract for MM Blocks.This row still omits the explicit MM Blocks keys, which now creates inconsistency with the incoming/outgoing webhook parameter docs and the cohort objective for response
propscoverage.Suggested doc fix
-| `props` | Sets the post `props`, a JSON property bag for storing extra or meta data on the post. Mainly used by other integrations accessing posts through the {{< newtabref title="REST API" href="https://api.mattermost.com" >}}.<br/>The following keys are reserved: `from_webhook`, `override_username`, `override_icon_url` and `attachments`. | No | +| `props` | Sets the post `props`, a JSON property bag for storing extra or meta data on the post. Mainly used by other integrations accessing posts through the {{< newtabref title="REST API" href="https://api.mattermost.com" >}}.<br/>The following keys are reserved: `from_webhook`, `override_username`, `override_icon_url` and `attachments`.<br/>Use `props.mm_blocks` and `props.mm_blocks_actions` for [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) interactive content. | No |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@site/content/integrate/slash-commands/custom/_index.md` at line 104, The props row for the slash-command docs omits explicit MM Blocks keys; update the `props` description to enumerate the reserved MM Blocks-related keys (in addition to the already-listed `from_webhook`, `override_username`, `override_icon_url`, `attachments`), briefly describe each key's purpose/format (e.g., the key that carries block payloads and any block-action/context identifiers), and make the wording consistent with the incoming/outgoing webhook parameter docs and the response `props` coverage. Locate the `props` table row (the cell that currently starts "Sets the post `props`") and expand its content to list the MM Blocks keys and short definitions so the contract is explicit and aligned with webhook docs.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@site/content/integrate/reference/mm-blocks/_index.md`:
- Line 265: The table row for the `options` field uses the phrase "depends" in
the Required column; change that wording to "depends on" so the entry reads:
`Array of {text, value} pairs. Required unless data_source is set.` Update the
text associated with the `options` field (the string shown in the table) to
replace "depends" with "depends on" so the schema wording is accurate and
consistent.
- Line 446: The doc line uses incorrect casing `update.Props`; change it to
`update.props` so it matches the rest of the examples and the response contract;
update the occurrence in the text (reference to `update.Props`) to
`update.props` in the mm-blocks reference content to ensure consistent casing
across examples and semantics.
---
Outside diff comments:
In `@site/content/integrate/reference/markdown-actions/_index.md`:
- Around line 215-220: The security bullet that currently says Action IDs are
“alphanumeric strings” is out of date; change the wording for the Action ID
bullet (the line describing action ID validation) to state the new allowed
charset (e.g. "Action IDs must match the pattern [A-Za-z0-9_-]+ — alphanumerics,
underscore and hyphen — and are matched case-sensitively") so the documentation
for Action IDs and their validation matches the current behavior.
In `@site/content/integrate/slash-commands/custom/_index.md`:
- Line 104: The props row for the slash-command docs omits explicit MM Blocks
keys; update the `props` description to enumerate the reserved MM Blocks-related
keys (in addition to the already-listed `from_webhook`, `override_username`,
`override_icon_url`, `attachments`), briefly describe each key's purpose/format
(e.g., the key that carries block payloads and any block-action/context
identifiers), and make the wording consistent with the incoming/outgoing webhook
parameter docs and the response `props` coverage. Locate the `props` table row
(the cell that currently starts "Sets the post `props`") and expand its content
to list the MM Blocks keys and short definitions so the contract is explicit and
aligned with webhook docs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a96b0d41-5231-415e-a57b-19fcc9703993
📒 Files selected for processing (8)
site/content/integrate/faq/_index.mdsite/content/integrate/plugins/interactive-messages/_index.mdsite/content/integrate/reference/markdown-actions/_index.mdsite/content/integrate/reference/message-attachments/_index.mdsite/content/integrate/reference/mm-blocks/_index.mdsite/content/integrate/slash-commands/custom/_index.mdsite/content/integrate/webhooks/incoming/_index.mdsite/content/integrate/webhooks/outgoing/_index.md
|
Newest code from mattermost has been published to preview environment for Git SHA 9571324 |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds initial developer documentation for the new MM Blocks integration format, and updates existing integration docs to reference MM Blocks as the recommended approach for structured/interactive content.
Changes:
- Introduces a new MM Blocks reference page describing payload structure, block types, and action dispatch.
- Updates webhook and slash command docs to point readers to
props.mm_blocks/props.mm_blocks_actions. - Reframes legacy interactive attachments/buttons docs as supported but not recommended for new integrations.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| site/content/integrate/webhooks/outgoing/_index.md | Adds MM Blocks guidance under props and in advanced formatting note. |
| site/content/integrate/webhooks/incoming/_index.md | Adds MM Blocks guidance under props. |
| site/content/integrate/slash-commands/custom/_index.md | Adds MM Blocks references in response guidance and props parameter docs. |
| site/content/integrate/reference/mm-blocks/_index.md | New comprehensive MM Blocks reference page (schema, examples, actions, limits). |
| site/content/integrate/reference/message-attachments/_index.md | Marks attachment actions as legacy and points to MM Blocks. |
| site/content/integrate/reference/markdown-actions/_index.md | Aligns markdown actions docs with MM Blocks / shared action registry. |
| site/content/integrate/plugins/interactive-messages/_index.md | Adds MM Blocks section and reframes legacy attachment actions. |
| site/content/integrate/faq/_index.md | Adds MM Blocks guidance in attachments FAQ section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Newest code from mattermost has been published to preview environment for Git SHA 3932294 |
| 6. To have your application post a message back to `town-square`, it can respond to the HTTP `POST` or `GET` request with a JSON payload. | ||
|
|
||
| Mattermost supports several [parameters](#response-parameters) in the response to fine-tune the user's experience. For instance, you can override the username and profile picture the messages post as, or specify a custom post type when sending a webhook message for use by [plugins]({{< ref "/integrate/plugins" >}}). Messages with advanced formatting can be created by including an [attachment array]({{< ref "/integrate/reference/message-attachments" >}}) and [interactive message buttons]({{< ref "/integrate/plugins/interactive-messages" >}}) in the response payload. | ||
| Mattermost supports several [parameters](#response-parameters) in the response to fine-tune the user's experience. For instance, you can override the username and profile picture the messages post as, or specify a custom post type when sending a webhook message for use by [plugins]({{< ref "/integrate/plugins" >}}). Messages with advanced formatting can be created by including [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}), an [attachment array]({{< ref "/integrate/reference/message-attachments" >}}), or [interactive message buttons]({{< ref "/integrate/plugins/interactive-messages" >}}) in the response payload. |
|
Newest code from mattermost has been published to preview environment for Git SHA be582f8 |
hanzei
requested changes
Jun 26, 2026
hanzei
left a comment
hanzei
left a comment
Contributor
There was a problem hiding this comment.
One totally non-blocking thought: Should we export an LLM focused version of the docs, similar to what https://readmellm.github.io/ and other project recommend? Given that MM-blocks is new, most models don't know about it yet.
Comment on lines
+28
to
+50
| ```json | ||
| { | ||
| "text": "Deployment #42 finished.", | ||
| "props": { | ||
| "mm_blocks": [ | ||
| {"type": "text", "text": "Deployed `main` to **staging**."}, | ||
| { | ||
| "type": "button", | ||
| "text": "View logs", | ||
| "style": "primary", | ||
| "action_id": "view_logs" | ||
| } | ||
| ], | ||
| "mm_blocks_actions": { | ||
| "view_logs": { | ||
| "type": "external", | ||
| "url": "https://integration.example.com/actions/view-logs", | ||
| "context": {"deployment_id": "42"} | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
I wonder if we even need the example. We want to redirect the dev to the MM blocks page anyway, right?
Contributor
There was a problem hiding this comment.
I would love to see some screenshots here
Contributor
Author
There was a problem hiding this comment.
They will come later 😄
Comment on lines
196
to
202
| | --- | --- | | ||
| | Maximum entries in `mm_blocks_actions` | 50 | | ||
| | Maximum length of an action ID (map key) | 64 characters | | ||
| | Action ID character set | `[A-Za-z0-9]+` | | ||
| | Action ID character set | `[A-Za-z0-9_-]+` | | ||
| | Maximum entries in `query` (link or registry) | 50 | | ||
| | Maximum length of a query key | 128 characters | | ||
| | Maximum length of a query value | 2048 characters | |
Contributor
There was a problem hiding this comment.
Nit: this seems like a technical detail not worth documenting in a table. Maybe add some of the limits to corresponding sections.
Contributor
There was a problem hiding this comment.
I would also love some screenshot here 😉
|
|
||
| MM Blocks are the recommended way to build [interactive messages]({{< ref "/integrate/plugins/interactive-messages" >}}). Instead of placing buttons and menus inside legacy [message attachments]({{< ref "/integrate/reference/message-attachments" >}}), integrations send a block tree in `props.mm_blocks` and register action handlers in `props.mm_blocks_actions`. | ||
|
|
||
| Legacy attachment arrays (top-level `attachments` on webhooks and slash-command responses, or `props.attachments` on REST API posts), Slack Block Kit (`props.blocks`), and Microsoft Adaptive Cards (`props.cards`) are still accepted. Mattermost translates them into MM Blocks at render time, but new integrations should use native MM Blocks directly. |
Contributor
There was a problem hiding this comment.
Should we move this more to the bottom? I think the docs should first talk about what MM-Blocks are and not point in other directions.
|
|
||
| ### Submit from a plugin | ||
|
|
||
| ```go |
Contributor
There was a problem hiding this comment.
Nit: code highlighting seems broken. Maybe golang?
| | `container` | Groups blocks with optional border, accent bar, background, and layout flow | | ||
| | `collapsible` | Expandable section with separate header and content block arrays | | ||
| | `column_set` | Horizontal row of columns | | ||
| | `column` | Column inside a `column_set` (not valid as a top-level block) | |
Contributor
There was a problem hiding this comment.
Should we have clickable links here that take to the sections?
|
|
||
| Additional action types may be introduced in future releases. Entries with an unknown `type` value are rejected at post-create time. | ||
|
|
||
| ## Action dispatch flow |
Comment on lines
+460
to
+473
| ## Validation limits | ||
|
|
||
| Posts that exceed any of the following limits are rejected at create or update time. | ||
|
|
||
| | Limit | Value | | ||
| | --- | --- | | ||
| | Maximum entries in `mm_blocks_actions` | 50 | | ||
| | Maximum length of an action ID (map key) | 64 characters | | ||
| | Action ID character set | `[A-Za-z0-9_-]+` | | ||
| | Maximum entries in `query` (link, registry, or block) | 50 | | ||
| | Maximum length of a query key | 128 characters | | ||
| | Maximum length of a query value | 2048 characters | | ||
| | Maximum entries in `context` per action | 50 | | ||
| | Maximum length of a context key | 128 characters | |
Contributor
There was a problem hiding this comment.
same comment as on the other files. this wrongly placed.
|
Newest code from mattermost has been published to preview environment for Git SHA 8729f81 |
|
Newest code from mattermost has been published to preview environment for Git SHA dde520b |
Contributor
Author
|
@hanzei Re: LLM Sounds like a great idea, but I don't know exactly where that should live. Whether in this repo, in the main repo, or where exactly 😅 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation for the MM Blocks feature, as defined in the following tech and design specs:
https://mattermost.atlassian.net/wiki/spaces/DE/pages/4426596366/Interactive+Post+Improvements
https://mattermost.atlassian.net/wiki/spaces/DES/pages/4532535321/Interactive+Blocks+UX+Specs
Related PRs
(Mobile) mattermost/mattermost-mobile#9764
(Web) mattermost/mattermost#36338
(Product docs) mattermost/docs#9013
Ticket Link
Fix https://mattermost.atlassian.net/browse/MM-68635