Initial draft for MM Blocks#1508
Open
larkox wants to merge 4 commits into
Open
Conversation
|
Newest code from mattermost has been published to preview environment for Git SHA 8a38941 |
Contributor
|
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 (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughThis pull request introduces MM Blocks as the primary framework for interactive content in Mattermost integrations. It adds comprehensive reference documentation, updates integration guides to recommend MM Blocks over legacy attachments, and clarifies the relationships between MM Blocks, markdown actions, and legacy formats. ChangesMM Blocks Integration Framework Documentation
Sequence Diagram(s)(omitted — changes are documentation-only and the sequence conditions are not met) Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
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