MM Blocks Documentation

source/deployment-guide/mobile/mobile-troubleshooting.rst

@@ -166,3 +166,8 @@ If you did not receive a push notification when testing push notifications, use
   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.
+
+Integration posts (MM Blocks) do not render or respond
+-------------------------------------------------------
+
+If buttons, menus, or structured content from an integration post is missing or unresponsive on mobile, see :doc:`Troubleshoot MM Blocks </get-help/mm-blocks-troubleshooting>`.

source/end-user-guide/access/client-availability.rst

@@ -147,6 +147,8 @@ Integrations
 +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+
 | `Outgoing webhooks <https://developers.mattermost.com/integrate/webhooks/outgoing/>`_                           | |checkmark| | |checkmark| | |checkmark|     |
 +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+
+| `MM Blocks <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_ [1]_                             | Conditional | Conditional | Conditional     |
++-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+
 | `Message attachments <https://developers.mattermost.com/integrate/reference/message-attachments/>`_             | |checkmark| | |checkmark| | |checkmark|     |
 +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+
 | `Message buttons <https://developers.mattermost.com/integrate/plugins/interactive-messages/#message-buttons>`_  | |checkmark| | |checkmark| | |checkmark|     |
@@ -158,6 +160,8 @@ Integrations
 | `Right-hand sidebar <https://developers.mattermost.com/integrate/reference/server/server-reference/>`_          | |checkmark| | |checkmark| |                 |
 +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+
 
+.. [1] Requires ``MM_FEATUREFLAGS_MMBLOCKSENABLED`` to be enabled on the Mattermost server (defaults to ``true``). When set to ``false``, clients do not render native MM Blocks payloads and the server rejects MM Blocks action requests.
+
 Authentication
 ~~~~~~~~~~~~~~
 

source/end-user-guide/messaging-collaboration.rst

@@ -36,4 +36,4 @@ Getting Started
 * :doc:`Communicate with messages and threads </end-user-guide/collaborate/communicate-with-messages>` Learn how to get started collaborating within Mattermost channels.
 * :doc:`Collaborate within Microsoft Teams </end-user-guide/collaborate/collaborate-within-connected-microsoft-teams>` - Learn how to get started collaborating within Microsoft Teams.
 * :doc:`Keyboard shortcuts </end-user-guide/collaborate/keyboard-shortcuts>` - Make a more efficient use of your keyboard with keyboard shortcuts.
-* :doc:`Extend Mattermost with integrations </end-user-guide/collaborate/extend-mattermost-with-integrations>` - Find open source integrations to common tools in the Mattermost Marketplace.
+* :doc:`Extend Mattermost with integrations </end-user-guide/collaborate/extend-mattermost-with-integrations>` - Find open source integrations to common tools in the Mattermost Marketplace, and learn how to interact with rich integration messages.

source/get-help/get-help-index.rst

@@ -9,6 +9,7 @@ Training and Support
    /get-help/community-chat.rst
    /get-help/community-for-mattermost.rst
    /get-help/contribute-to-documentation.rst
+   /get-help/mm-blocks-troubleshooting.rst
 
 Get the help you need with Mattermost via robust documentation, extensive community support, and professional support services. If you're struggling with something on your Mattermost journey, take a look at the following learning resources:
 
@@ -31,6 +32,8 @@ Help Center
 
 Visit the `Mattermost Help Center <https://support.mattermost.com/hc/en-us>`_ to access frequently asked questions and common troubleshooting tips.
 
+- :doc:`Troubleshoot MM Blocks </get-help/mm-blocks-troubleshooting>` — Resolve rendering and interaction issues with integration posts that use MM Blocks, including expandable content on mobile.
+
 Commercial Customer Support
 ---------------------------
 

source/get-help/mm-blocks-troubleshooting.rst

@@ -0,0 +1,95 @@
+Troubleshoot MM Blocks
+======================
+
+.. include:: ../_static/badges/all-commercial.rst
+  :start-after: :nosearch:
+
+Integration posts that use MM Blocks show structured content—including text, images, buttons, and menus—directly in a channel. This page covers common issues when MM Blocks do not render or respond as expected, with emphasis on mobile clients.
+
+MM Blocks content does not appear
+---------------------------------
+
+**Symptoms:** A post shows only plain text (or no content) and the expected buttons, images, or content blocks are missing.
+
+**Try the following:**
+
+1. **Update your client.** MM Blocks require a current Mattermost web, desktop, or mobile app. See :doc:`client availability </end-user-guide/access/client-availability>` for platform support.
+2. **Confirm the integration payload.** The post must include a non-empty ``props.mm_blocks`` array (or a legacy format such as message attachments that the client translates). Ask your integration owner or system admin to verify the webhook or bot payload.
+3. **Check the feature flag (system admins).** Self-hosted deployments can disable MM Blocks by setting ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false``. When disabled, native MM Blocks payloads are not rendered and their actions are rejected.
+4. **Reload the channel.** Pull to refresh on mobile, or switch channels and return, to fetch the latest post data.
+
+Buttons or menus do not respond
+-------------------------------
+
+**Symptoms:** Buttons appear disabled, or tapping a button or menu option has no effect.
+
+**Try the following:**
+
+1. **Wait for the action to finish.** Some integrations show a loading state while Mattermost calls an external service. Slow integrations may time out based on your server's :ref:`integration request timeout <administration-guide/configure/integrations-configuration-settings:integration request timeout>` setting.
+2. **Check whether the control is disabled.** Integrations can send buttons and menus in a disabled state. Disabled controls cannot be activated.
+3. **Verify outbound server connectivity.** External actions require Mattermost **server nodes** (not end-user devices) to make **outbound** requests to each integration action endpoint URL configured in the post. These endpoints typically use **HTTPS on TCP port 443**; if a URL uses another scheme or port, that destination must be reachable outbound from the server. Allow only the specific integration endpoints your organization uses—this is not an inbound connection requirement.
+4. **Look for follow-up messages.** Successful actions may update the original post or return an ephemeral reply visible only to you. Check the thread panel if the post is part of a thread.
+
+Scrollable content issues on mobile
+-----------------------------------
+
+**Symptoms:** Clipped integration content cannot be expanded, or the **Scrollable content** screen is empty.
+
+Some integration posts limit the height of a content region. When content overflows, Mattermost mobile shows a clipped preview with an expand control in the corner of the region.
+
+**To view the full content on mobile:**
+
+1. Locate the clipped region in the post (a fade at the bottom indicates more content below).
+2. Select the expand control in the bottom-right corner of the clipped area.
+3. Mattermost opens a full-screen **Scrollable content** view where you can scroll through the complete block content.
+4. Use the back gesture or navigation control to return to the channel.
+
+**If the Scrollable content screen shows "Cannot display content":**
+
+- Return to the channel and open the expand control again. This screen appears when the expanded payload is no longer available (for example, after navigating away before the view loaded).
+- Update to the latest mobile app build if the issue persists across multiple posts.
+
+On web and desktop, the same clipped regions scroll inside the post; a separate full-screen view is not used.
+
+Collapsible sections or images look wrong
+-----------------------------------------
+
+**Symptoms:** A section will not expand, an image fails to load, or part of the layout is missing.
+
+**Try the following:**
+
+1. **Collapsible sections:** Select the section header to toggle between expanded and collapsed states. If the header is missing or empty, the integration payload may be incomplete.
+2. **Images:** External images require a valid URL and may be blocked by your server's image proxy or SVG settings. Contact your system admin if images from other integrations load but MM Blocks images do not.
+3. **Partial content:** Clients skip individual malformed blocks and still render valid ones in the same post. If only some elements are missing, the integration payload likely contains invalid block entries.
+
+Not all blocks appear or text is cut off
+-----------------------------------------
+
+**Symptoms:** Only part of an integration post renders, blocks at the end of the post are missing, or text in a block or on a button label ends abruptly.
+
+Mattermost enforces size limits on MM Blocks payloads. Content that exceeds a limit is truncated when the post is rendered.
+
+**Try the following:**
+
+1. **Review payload limits (integration owners).** A single post is limited to:
+
+   - **100 blocks** in the ``props.mm_blocks`` array
+   - **32 levels** of nesting depth across nested block structures
+   - **16,000 characters** total across all text in the payload, including text blocks and button labels
+
+2. **Reduce payload size.** Split long content across multiple posts, shorten labels, flatten deeply nested structures, or remove optional blocks.
+3. **Validate after content changes.** If truncation appears only for certain posts or started after an integration update, compare the payload against these limits.
+
+Legacy message attachments
+--------------------------
+
+Older integrations that use `message attachments <https://developers.mattermost.com/integrate/reference/message-attachments/>`_ are translated into the MM Blocks UI at render time. Button and menu behavior should match native MM Blocks posts. If an attachment-based post behaves differently from a native MM Blocks post, report the payload to your integration owner.
+
+Get more help
+-------------
+
+- **End users:** See :doc:`Extend Mattermost with integrations </end-user-guide/collaborate/extend-mattermost-with-integrations>` for how to use buttons, menus, and expandable content in channels.
+- **Developers:** See the `MM Blocks reference <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_ for payload format, action APIs, and migration guidance.
+- **Mobile deployment issues:** See :doc:`Mobile deployment troubleshooting </deployment-guide/mobile/mobile-troubleshooting>` for connectivity, push notification, and app install problems unrelated to MM Blocks content.
+
+If you continue to experience issues, visit the `Mattermost Troubleshooting forum <https://forum.mattermost.com/c/trouble-shoot/16>`_ or contact your system administrator.

source/integrations-guide/faq.rst

@@ -48,7 +48,14 @@ What are attachments?
 
 When "attachments" are mentioned in Mattermost integrations documentation, it refers to Slack's message attachments functionality. These "attachments" can be optionally added as an array in the data sent by an integration, and are used to customize the formatting of the message.
 
-Mattermost doesn't currently support the ability to attach files to a post made via webhook. You can use the API to attach files to a message if needed. 
+Mattermost doesn't currently support the ability to attach files to a post made via webhook. You can use the API to attach files to a message if needed.
+
+What are MM Blocks?
+--------------------
+
+MM Blocks are Mattermost's structured format for rich, interactive integration posts. They are the recommended way to create richly formatted interactive messages with text, images, buttons, and menus.
+
+See the `MM Blocks reference <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_ in the developer documentation for integration details. If content does not render as expected, see :doc:`Troubleshoot MM Blocks </get-help/mm-blocks-troubleshooting>`.
 
 Where can I find existing integrations?
 ---------------------------------------

source/integrations-guide/incoming-webhooks.rst

@@ -8,6 +8,8 @@ Incoming Webhooks
 
 Send or receive real-time data from external tools. Webhooks require minimal coding and are easy to set up with virtually any tool or platform because they use lightweight HTTP POST requests with JSON payloads.
 
+For richly formatted interactive posts with buttons and menus, see :doc:`MM Blocks </integrations-guide/mm-blocks>`.
+
 Using incoming webhooks in Mattermost requires only basic setup. You generate a webhook URL using the Mattermost interface, then point another service to send data to that address. No coding is required if your external service triggering the events is able to send data via webhooks or HTTP POST requests, which most modern applications and platforms support. Setting this up usually involves pasting the Mattermost webhook URL into the service’s settings and selecting what type of events you want it to send. 
 
 Example Use Cases
@@ -107,7 +109,7 @@ The JSON payload can contain the following parameters:
      - Required
      - Description
    * - ``text``
-     - Yes (if ``attachments`` is not set)
+     - Yes (if ``attachments`` and ``props.mm_blocks`` are not set)
      - :doc:`Markdown-formatted </end-user-guide/collaborate/format-messages>` message. Use ``@<username>``, ``@channel``, and ``@here`` for notifications.
    * - ``channel``
      - No
@@ -122,14 +124,14 @@ The JSON payload can contain the following parameters:
      - No
      - Overrides the ``icon_url`` with an emoji. Use the emoji name (e.g., ``:tada:``). The :ref:`Enable integrations to override profile picture icons <administration-guide/configure/integrations-configuration-settings:enable integrations to override profile picture icons>` setting must be enabled.
    * - ``attachments``
-     - Yes (if ``text`` is not set)
-     - An array of `message attachment <https://developers.mattermost.com/integrate/reference/message-attachments/>`_ objects for richer formatting.
+     - Yes (if ``text`` and ``props.mm_blocks`` are not set)
+     - An array of `message attachment <https://developers.mattermost.com/integrate/reference/message-attachments/>`_ objects for richer formatting. Legacy format; use `MM Blocks <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_ for new integrations.
    * - ``type``
      - No
      - Sets the post type, mainly for use by plugins. If set, must begin with ``custom_``.
    * - ``props``
      - No
-     - A JSON object for storing metadata. The ``card`` property can be used to display extra Markdown-formatted text in the post's info panel (RHS). This is available in Mattermost v5.14 and later, and is not yet supported on mobile.
+     - A JSON object for storing metadata. Use `MM Blocks <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_ for rich, interactive content. The ``card`` property can be used to display extra Markdown-formatted text in the post's info panel (RHS). This is available in Mattermost v5.14 and later, and is not yet supported on mobile.
    * - ``priority``
      - No
      - Sets the priority of the message. See `message priorities <https://developers.mattermost.com/integrate/reference/message-priority/>`_.
@@ -224,8 +226,9 @@ Do More with Incoming Webhooks
 
 Transform basic message posts into rich, interactive notifications by including buttons, menus, and other interactive elements in your webhook messages, making them more engaging and useful for your team.
 
-- `Message Attachments <https://developers.mattermost.com/integrate/reference/message-attachments/>`_: Present rich, structured summaries such as status, priority, fields, links, or images for faster triage and comprehension. (Slack‑compatible schema.)
-- `Interactive Messages <https://developers.mattermost.com/integrate/plugins/interactive-messages>`_: Make notifications actionable with buttons or menus such as Acknowledge, Assign, or Escalate that enable an immediate user response without switching tools or context.
+- `MM Blocks <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_: **Recommended.** Create structured, interactive posts with text, images, buttons, and menus.
+- `Message Attachments <https://developers.mattermost.com/integrate/reference/message-attachments/>`_: Legacy Slack‑compatible schema for rich summaries. Existing payloads are translated to MM Blocks at render time; use MM Blocks for new integrations.
+- `Interactive Messages <https://developers.mattermost.com/integrate/plugins/interactive-messages/>`_: Make notifications actionable with buttons or menus such as Acknowledge, Assign, or Escalate that enable an immediate user response without switching tools or context.
 - `Interactive Dialogs <https://developers.mattermost.com/integrate/plugins/interactive-dialogs/>`_: Guide users to successful outcomes when interactions need structured input or confirmation (for example, “Acknowledge with note” or “Assign to user”). Improve data quality with required fields, minimum/maximum input lengths, server‑driven user/channel pickers, validated defaults, inline field errors, placeholders, and help text that help users enter the right data the first time.
 - `Message Priority <https://developers.mattermost.com/integrate/reference/message-priority/>`_: Set ``priority`` to elevate critical posts and optionally request acknowledgements or persistent notifications.
 

source/integrations-guide/integrations-guide-index.rst

@@ -88,7 +88,7 @@ Incoming Webhooks
 
 :doc:`Incoming webhooks </integrations-guide/incoming-webhooks>` allow external applications to post messages into Mattermost channels and direct messages. They are a simple way to receive notifications and data from other services in real-time and require only basic setup.
 
-Additionally, Mattermost webhook payloads are :ref:`fully compatible <integrations-guide/incoming-webhooks:slack compatibility>` with Slack’s webhook format to make migration easier.
+Additionally, Mattermost webhook payloads are :ref:`fully compatible <integrations-guide/incoming-webhooks:slack compatibility>` with Slack’s webhook format to make migration easier. For new interactive content, use `MM Blocks <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_ instead of message attachments.
 
 Outgoing Webhooks
 ^^^^^^^^^^^^^^^^^^

source/integrations-guide/mm-blocks.rst

@@ -0,0 +1,15 @@
+MM Blocks
+==========
+
+.. include:: ../_static/badges/all-commercial.rst
+  :start-after: :nosearch:
+
+**Technical complexity:** :ref:`Low-code <low-code>`
+
+MM Blocks are Mattermost's structured format for rich, interactive integration posts. Integrations can extend messages with text, images, buttons, menus, collapsible sections, and different layout options.
+
+MM Blocks are the recommended way to create interactive messages for integrations such as :doc:`incoming webhooks </integrations-guide/incoming-webhooks>`, plugins, and bot accounts. Legacy `message attachments <https://developers.mattermost.com/integrate/reference/message-attachments/>`_ continue to work; clients translate them into the MM Blocks format at render time.
+
+For payload structure, block types, action handling, and migration guidance, see the `MM Blocks reference <https://developers.mattermost.com/integrate/reference/mm-blocks/>`_ in the developer documentation.
+
+If content does not render or respond as expected, see :doc:`Troubleshoot MM Blocks </get-help/mm-blocks-troubleshooting>`.