MM Blocks Documentation#9013
Conversation
|
Newest code from mattermost has been published to preview environment for Git SHA ed6cdfb |
|
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 (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds comprehensive MM Blocks documentation: a core reference page, integration-guide updates recommending MM Blocks and clarifying webhook/command parameters, end-user guidance on interacting with MM Blocks, and a troubleshooting page plus help-index and mobile troubleshooting pointers. ChangesMM Blocks documentation suite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes 🚥 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)
Warning Review ran into problems🔥 ProblemsStopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@source/end-user-guide/access/client-availability.rst`:
- Around line 150-151: The MM Blocks support row currently appears
unconditional; update the table entry for "MM Blocks" (the row shown in the
diff) to indicate that support is conditional on the feature flag by adding
wording like "Conditional (requires MmBlocksEnabled)" or equivalent, and/or add
a footnote referencing the MmBlocksEnabled feature flag so admins know the
feature can be disabled; ensure the table cell replaces the plain checkmark with
this conditional text and add a short footnote explaining MmBlocksEnabled.
In `@source/get-help/mm-blocks-troubleshooting.rst`:
- Line 30: Change the vague "Verify network connectivity." sentence so it
explicitly states that Mattermost server nodes must be able to make outbound
HTTPS (TCP 443) connections to the integration action endpoint(s) configured by
the post author and that this outbound access is required (not inbound); update
the sentence matching "Verify network connectivity." to mention direction
(outbound), protocol (HTTPS/TCP 443), source (Mattermost server nodes),
destination (integration action endpoint URL), and that this access is required
and should be limited to those endpoints only.
🪄 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: e83f574b-6e12-479c-a7a5-372b3764b04d
📒 Files selected for processing (13)
source/deployment-guide/mobile/mobile-troubleshooting.rstsource/end-user-guide/access/client-availability.rstsource/end-user-guide/collaborate/extend-mattermost-with-integrations.rstsource/end-user-guide/messaging-collaboration.rstsource/get-help/get-help-index.rstsource/get-help/mm-blocks-troubleshooting.rstsource/integrations-guide/faq.rstsource/integrations-guide/incoming-webhooks.rstsource/integrations-guide/integrations-guide-index.rstsource/integrations-guide/mm-blocks.rstsource/integrations-guide/outgoing-webhooks.rstsource/integrations-guide/slash-commands.rstsource/integrations-guide/webhook-integrations.rst
There was a problem hiding this comment.
Pull request overview
Adds end-to-end documentation coverage for the new MM Blocks interactive post format, and updates existing webhook/slash command docs plus end-user/help content to point readers to MM Blocks as the preferred approach over legacy message attachments.
Changes:
- Adds a new developer reference page for MM Blocks payload structure, supported block types, actions, APIs, and migration from attachments.
- Updates incoming/outgoing webhook and slash command docs to recommend MM Blocks and clarify payload requirements.
- Adds end-user guidance and troubleshooting content (including mobile) for interacting with rich integration messages.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| source/integrations-guide/webhook-integrations.rst | Adds MM Blocks to the Webhooks section nav and positions it as the recommended interactive format. |
| source/integrations-guide/slash-commands.rst | Updates a slash command use case to reference MM Blocks for interactive results. |
| source/integrations-guide/outgoing-webhooks.rst | Documents MM Blocks support in outgoing webhook responses and updates parameter guidance. |
| source/integrations-guide/mm-blocks.rst | New dedicated reference page describing MM Blocks format, actions, API endpoint, and migration guidance. |
| source/integrations-guide/integrations-guide-index.rst | Highlights MM Blocks as the preferred interactive format when discussing Slack compatibility. |
| source/integrations-guide/incoming-webhooks.rst | Updates incoming webhook parameters and “Do More” section to recommend MM Blocks. |
| source/integrations-guide/faq.rst | Adds a new FAQ entry explaining what MM Blocks are. |
| source/get-help/mm-blocks-troubleshooting.rst | New troubleshooting page for MM Blocks rendering/action issues (with mobile emphasis). |
| source/get-help/get-help-index.rst | Adds the MM Blocks troubleshooting page to the Help section and links it in the Help Center list. |
| source/end-user-guide/messaging-collaboration.rst | Updates the end-user navigation blurb to mention interacting with rich integration messages. |
| source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst | Adds end-user instructions for interacting with MM Blocks (buttons, menus, collapsible/scrollable content). |
| source/end-user-guide/access/client-availability.rst | Adds MM Blocks to the client availability matrix under Integrations. |
| source/deployment-guide/mobile/mobile-troubleshooting.rst | Adds a mobile troubleshooting pointer for MM Blocks integration posts. |
|
Newest code from mattermost has been published to preview environment for Git SHA 0dc201a |
|
Newest code from mattermost has been published to preview environment for Git SHA e125609 |
|
Newest code from mattermost has been published to preview environment for Git SHA 5154279 |
|
Newest code from mattermost has been published to preview environment for Git SHA 0d690d9 |
|
Newest code from mattermost has been published to preview environment for Git SHA 06075f3 |
hanzei
left a comment
hanzei
left a comment
There was a problem hiding this comment.
I free like this PR is over doing it. Do we really need to document the technical details on this page? I wonder if we should place them in the dev docs instead.
more details in the comments below
| If push notifications are not being delivered on the mobile device, confirm that you're logged in to the **Native** mobile app session through **Profile > Security > View and Log Out of Active Sessions**. Otherwise, the `DeviceId` won't get registered in the `Sessions` table and notifications won't be delivered. | ||
|
|
||
| .. important:: | ||
|
|
||
| To conserve disk space, once your push notification issue is resolved, go to **System Console > Environment > Logging > File Log Level**, then select **ERROR** to switch your logging detail level from **DEBUG** to **Errors Only**. | ||
|
|
||
| If push notifications are not being delivered on the mobile device, confirm that you're logged in to the **Native** mobile app session through **Profile > Security > View and Log Out of Active Sessions**. Otherwise, the `DeviceId` won't get registered in the `Sessions` table and notifications won't be delivered. No newline at end of file |
There was a problem hiding this comment.
I wonder if we should talk about block in general here. It's a integration dev feature, not an admin thing. What values does this documentation provide?
|
|
||
| :doc:`MM Blocks </integrations-guide/mm-blocks>` are Mattermost's structured format for rich, interactive posts. Integrations set ``props.mm_blocks`` (content and controls) and ``props.mm_blocks_actions`` (integration URLs and navigation targets) on a post. | ||
|
|
||
| MM Blocks are the recommended way to build interactive messages with buttons, menus, images, and layouts. Legacy `message attachments <https://developers.mattermost.com/integrate/reference/message-attachments/>`_ and other formats (Slack Block Kit ``blocks``, Adaptive Cards ``cards``) are still accepted and translated into MM Blocks at render time. |
There was a problem hiding this comment.
nit: remove the technical details for clarity
There was a problem hiding this comment.
Should we move this whole pag over to the dev docs? Are there other places where we already document the technical details on how integrations work?
| **Knowledge retrieval** | ||
|
|
||
| A command like ``/docs search authentication`` queries your documentation system and returns a list of relevant articles as interactive message attachments with links. No newline at end of file | ||
| A command like ``/docs search authentication`` queries your documentation system and returns a list of relevant articles rendered using :doc:`MM Blocks </integrations-guide/mm-blocks>` (recommended) or legacy `message attachments <https://developers.mattermost.com/integrate/reference/message-attachments/>`_ with links. No newline at end of file |
There was a problem hiding this comment.
let's just remove message attachments
|
|
||
| Incoming Webhooks </integrations-guide/incoming-webhooks> | ||
| Outgoing Webhooks </integrations-guide/outgoing-webhooks> | ||
| MM Blocks </integrations-guide/mm-blocks> |
There was a problem hiding this comment.
MM Blocks are for incoming webhooks only, right? if so, let's group them with incoming webhooks.
There was a problem hiding this comment.
For now, it will be for any integration that can create messages. That is...
- Incoming webhooks
- Plugins
- Personal Access Tokens
In the future, I would love to use this in other contexts outside of posts (e.g. building the RHS, building modals, etc...). But that is still an idea.
|
I agree with @hanzei I think this should be in the dev docs along with/similar to the existing message attachment docs. We can leave a note or redirect in the regular docs for better visibility. Also agree that this: https://github.com/mattermost/docs/pull/9013/files/06075f3009f5f9a0fcce70bd976637e99c6da6a4#diff-023263fae145e89db7c74e0d9e3384781191a84c0bd578986fe269e4b65ef1a6 Seems a bit excessive and just reads like an LLM summary of what was implemented. Imo it would make more sense to have a shorter version à la "Mattermost integrations can extend messages using the new blocks system, which includes things like x y and z. You can learn more about inegrating with blocks in the developer docs here." |
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
(Dev Docs) mattermost/mattermost-developer-documentation#1508
Ticket Link
Fix https://mattermost.atlassian.net/browse/MM-68635