From ed6cdfbc0393c4a9d025de3074e6469e7b5b5c38 Mon Sep 17 00:00:00 2001 From: Daniel Espino Date: Sat, 6 Jun 2026 14:23:15 +0200 Subject: [PATCH 1/7] Initial documentation draft --- .../mobile/mobile-troubleshooting.rst | 5 + .../access/client-availability.rst | 2 + .../extend-mattermost-with-integrations.rst | 38 +++ .../messaging-collaboration.rst | 2 +- source/get-help/get-help-index.rst | 3 + source/get-help/mm-blocks-troubleshooting.rst | 77 +++++ source/integrations-guide/faq.rst | 9 +- .../integrations-guide/incoming-webhooks.rst | 11 +- .../integrations-guide-index.rst | 2 +- source/integrations-guide/mm-blocks.rst | 287 ++++++++++++++++++ .../integrations-guide/outgoing-webhooks.rst | 13 +- source/integrations-guide/slash-commands.rst | 2 +- .../webhook-integrations.rst | 2 + 13 files changed, 438 insertions(+), 15 deletions(-) create mode 100644 source/get-help/mm-blocks-troubleshooting.rst create mode 100644 source/integrations-guide/mm-blocks.rst diff --git a/source/deployment-guide/mobile/mobile-troubleshooting.rst b/source/deployment-guide/mobile/mobile-troubleshooting.rst index 0c510fbaaeb..2c83f9ffda9 100644 --- a/source/deployment-guide/mobile/mobile-troubleshooting.rst +++ b/source/deployment-guide/mobile/mobile-troubleshooting.rst @@ -147,4 +147,9 @@ 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**. +Integration posts (MM Blocks) do not render or respond +---------------------------------------------------- + +If buttons, menus, or structured layout content from an integration post is missing or unresponsive on mobile, see :doc:`Troubleshoot MM Blocks `. + 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 diff --git a/source/end-user-guide/access/client-availability.rst b/source/end-user-guide/access/client-availability.rst index 704036a3957..2d69504e91b 100644 --- a/source/end-user-guide/access/client-availability.rst +++ b/source/end-user-guide/access/client-availability.rst @@ -147,6 +147,8 @@ Integrations +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Outgoing webhooks `_ | |checkmark| | |checkmark| | |checkmark| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ +| :doc:`MM Blocks ` | |checkmark| | |checkmark| | |checkmark| | ++-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Message attachments `_ | |checkmark| | |checkmark| | |checkmark| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Message buttons `_ | |checkmark| | |checkmark| | |checkmark| | diff --git a/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst b/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst index f9ad3c9e2ef..506849167ce 100644 --- a/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst +++ b/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst @@ -26,6 +26,44 @@ Mattermost interoperability - :ref:`ServiceNow ` - :ref:`Zoom ` +Interact with integration messages +---------------------------------- + +Many integrations post rich, actionable content into channels using **MM Blocks**—a structured layout format for text, images, buttons, menus, and grouped content. You may also see the same presentation for older integrations that use message attachments; Mattermost translates those into the MM Blocks layout automatically. + +What you may see in a channel +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Integration posts can include: + +- **Text and images** formatted with headings, emphasis, and links. +- **Grouped content** in bordered or shaded containers, sometimes arranged in columns. +- **Buttons** labeled with actions such as *Acknowledge*, *Approve*, or *View details*. +- **Menus** (static selects) that let you choose from a list of options. +- **Collapsible sections** with a header you can tap to show or hide additional details. + +Using buttons and menus +~~~~~~~~~~~~~~~~~~~~~~~ + +1. **Buttons:** Select a button to send your choice to the integration. The integration may update the post in place or send you a private follow-up message visible only to you. +2. **Menus:** Select the menu to open the list of options, then choose one. Mattermost sends the selected value to the integration, similar to pressing a button. +3. **Disabled controls:** Some buttons or menus appear grayed out and cannot be selected until the integration enables them. + +If nothing happens after you select a button or menu option, wait a moment in case the integration is still processing. Contact your system admin if actions consistently fail. + +Expandable and scrollable content +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some integration posts clip long content to keep the channel readable. + +- **Collapsible sections:** Select the section header to expand or collapse the content beneath it. +- **Web and desktop:** When a content region has a height limit, scroll inside the post to read the full content. +- **Mobile:** When content is clipped, a fade appears at the bottom of the region and an expand control is shown in the bottom-right corner. Select that control to open a full-screen **Scrollable content** view. Scroll through the complete content, then use the back gesture or navigation control to return to the channel. + +.. tip:: + + Integration developers can learn how to build MM Blocks payloads in the :doc:`MM Blocks ` documentation. If content does not render or respond as expected, see :doc:`Troubleshoot MM Blocks `. + .. tip:: - `Visit the Mattermost Marketplace `__ to find open source, community-supported integrations to common developer tools like `CircleCI `__, `Opsgenie `__, `PagerDuty Notifier `__; productivity tools like `Autolink `__, `ToDo `__, and `WelcomeBot `__; as well as social tools like `Memes `__ and `GIFs `__ that are freely available for use and customization. diff --git a/source/end-user-guide/messaging-collaboration.rst b/source/end-user-guide/messaging-collaboration.rst index 79b9f46ce37..916a58093f3 100644 --- a/source/end-user-guide/messaging-collaboration.rst +++ b/source/end-user-guide/messaging-collaboration.rst @@ -36,4 +36,4 @@ Getting Started * :doc:`Communicate with messages and threads ` Learn how to get started collaborating within Mattermost channels. * :doc:`Collaborate within Microsoft Teams ` - Learn how to get started collaborating within Microsoft Teams. * :doc:`Keyboard shortcuts ` - Make a more efficient use of your keyboard with keyboard shortcuts. -* :doc:`Extend Mattermost with integrations ` - Find open source integrations to common tools in the Mattermost Marketplace. +* :doc:`Extend Mattermost with integrations ` - Find open source integrations to common tools in the Mattermost Marketplace, and learn how to interact with rich integration messages (MM Blocks). diff --git a/source/get-help/get-help-index.rst b/source/get-help/get-help-index.rst index 799ebf92194..5690bceb6c0 100644 --- a/source/get-help/get-help-index.rst +++ b/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 `_ to access frequently asked questions and common troubleshooting tips. +- :doc:`Troubleshoot MM Blocks ` — Resolve rendering and interaction issues with integration posts that use MM Blocks, including expandable content on mobile. + Commercial Customer Support --------------------------- diff --git a/source/get-help/mm-blocks-troubleshooting.rst b/source/get-help/mm-blocks-troubleshooting.rst new file mode 100644 index 00000000000..61179a8c427 --- /dev/null +++ b/source/get-help/mm-blocks-troubleshooting.rst @@ -0,0 +1,77 @@ +Troubleshoot MM Blocks +====================== + +.. include:: ../_static/badges/all-commercial.rst + :start-after: :nosearch: + +Integration posts that use :doc:`MM Blocks ` show structured content—text, images, buttons, menus, and layouts—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 layout 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 ` 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 with the ``MmBlocksEnabled`` feature flag. When disabled, native MM Blocks payloads are not rendered and their actions are rejected. See :doc:`MM Blocks ` for details. +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 ` 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 network connectivity.** External actions require Mattermost to reach the integration URL configured by the post author. Connectivity issues on the server or integration host can prevent responses. +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. + +Legacy message attachments +-------------------------- + +Older integrations that use `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 ` for how to use buttons, menus, and expandable content in channels. +- **Developers:** See :doc:`MM Blocks ` for payload format, action APIs, and migration guidance. +- **Mobile deployment issues:** See :doc:`Mobile deployment 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 `_ or contact your system administrator. diff --git a/source/integrations-guide/faq.rst b/source/integrations-guide/faq.rst index c064d334c8a..951dc971f4c 100644 --- a/source/integrations-guide/faq.rst +++ b/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? +-------------------- + +:doc:`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 `_ and other formats (Slack Block Kit ``blocks``, Adaptive Cards ``cards``) are still accepted and translated into MM Blocks at render time. Where can I find existing integrations? --------------------------------------- diff --git a/source/integrations-guide/incoming-webhooks.rst b/source/integrations-guide/incoming-webhooks.rst index a201342dec7..fe581ca4c94 100644 --- a/source/integrations-guide/incoming-webhooks.rst +++ b/source/integrations-guide/incoming-webhooks.rst @@ -107,7 +107,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 ` message. Use ``@``, ``@channel``, and ``@here`` for notifications. * - ``channel`` - No @@ -122,14 +122,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 ` setting must be enabled. * - ``attachments`` - - Yes (if ``text`` is not set) - - An array of `message attachment `_ objects for richer formatting. + - Yes (if ``text`` and ``props.mm_blocks`` are not set) + - An array of `message attachment `_ objects for richer formatting. Legacy format; prefer ``props.mm_blocks`` for new integrations. See :doc:`MM Blocks `. * - ``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`` and ``mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). 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 `_. @@ -224,7 +224,8 @@ 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 `_: Present rich, structured summaries such as status, priority, fields, links, or images for faster triage and comprehension. (Slack‑compatible schema.) +- :doc:`MM Blocks `: **Recommended.** Build structured, interactive posts with text, images, layouts, buttons, and menus using ``props.mm_blocks`` and ``props.mm_blocks_actions``. +- `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 `_: 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 `_: 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 `_: Set ``priority`` to elevate critical posts and optionally request acknowledgements or persistent notifications. diff --git a/source/integrations-guide/integrations-guide-index.rst b/source/integrations-guide/integrations-guide-index.rst index 80d0d811125..edb62d6dd4f 100644 --- a/source/integrations-guide/integrations-guide-index.rst +++ b/source/integrations-guide/integrations-guide-index.rst @@ -88,7 +88,7 @@ Incoming Webhooks :doc:`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 ` with Slack’s webhook format to make migration easier. +Additionally, Mattermost webhook payloads are :ref:`fully compatible ` with Slack’s webhook format to make migration easier. For new interactive content, use :doc:`MM Blocks ` instead of message attachments. Outgoing Webhooks ^^^^^^^^^^^^^^^^^^ diff --git a/source/integrations-guide/mm-blocks.rst b/source/integrations-guide/mm-blocks.rst new file mode 100644 index 00000000000..c8d0f9f25d8 --- /dev/null +++ b/source/integrations-guide/mm-blocks.rst @@ -0,0 +1,287 @@ +MM Blocks +========== + +.. include:: ../_static/badges/all-commercial.rst + :start-after: :nosearch: + +**Technical complexity:** :ref:`Low-code ` + +MM Blocks are Mattermost's structured format for rich, interactive posts. Use them to build notifications with text, images, layouts, buttons, and menus directly in a post's ``props``—without relying on Slack-compatible `message attachments `_. + +MM Blocks replace message attachments as the recommended way to create `interactive messages `_. Existing attachment-based payloads continue to work: clients translate them into MM Blocks at render time. + +Overview +-------- + +Interactive posts combine: + +- **Content blocks** in ``props.mm_blocks`` — text, images, dividers, containers, columns, collapsible sections, buttons, and static selects. +- **Action definitions** in ``props.mm_blocks_actions`` — maps each ``action_id`` to an integration URL or in-app navigation target. + +When a post is created, the server encrypts ``mm_blocks_actions`` into a single cookie string before the post is sent to clients. Users interact with buttons and menus in the channel; Mattermost calls your integration and can update the post or return an ephemeral reply. + +MM Blocks are supported on web, desktop, and mobile clients. Availability is controlled by the ``MmBlocksEnabled`` `feature flag `_ (enabled by default in current Mattermost releases). Self-hosted deployments can set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` to disable rendering and action dispatch for MM Blocks payloads. + +Quick start +----------- + +This incoming webhook payload renders a short message with a primary button. The button calls an external integration URL when clicked. + +.. code-block:: json + + { + "text": "Deployment finished", + "props": { + "mm_blocks": [ + { + "type": "text", + "text": "Build **#42** deployed to *staging*." + }, + { + "type": "divider" + }, + { + "type": "button", + "text": "View logs", + "style": "primary", + "action_id": "view_logs" + } + ], + "mm_blocks_actions": { + "view_logs": { + "type": "external", + "url": "https://example.com/integrations/view-logs", + "context": { + "deployment_id": "42" + } + } + } + } + } + +Post properties +--------------- + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Property + - Description + * - ``props.mm_blocks`` + - Array of block objects that define layout and interactive controls. See `Block types`_ below. + * - ``props.mm_blocks_actions`` + - Object keyed by ``action_id``. Each value defines how Mattermost handles a button press or menu selection. Replaced on the wire by an encrypted cookie after the post is saved. + +You can include ``mm_blocks`` in any post payload that supports ``props``, including :doc:`incoming webhooks `, :doc:`outgoing webhook ` responses, slash command responses, bot posts, and ephemeral posts created through the API. + +Block types +----------- + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Type + - Description + * - ``text`` + - Markdown text. Optional ``size`` (``small`` or ``default``) and ``is_subtle`` (muted color). + * - ``divider`` + - Horizontal rule between blocks. + * - ``image`` + - Image with ``url``, optional ``alt_text``, ``title``, ``size`` (``auto``, ``xsmall``, ``small``, ``medium``, ``large``, ``stretch``), ``max_width``, ``max_height``, ``image_style``, and ``horizontal_alignment``. + * - ``button`` + - Labeled button. Requires ``text`` and ``action_id``. Optional ``style`` (``default``, ``primary``, ``danger``, ``good``, ``success``, ``warning``, or ``#RRGGBB`` hex), ``tooltip``, ``disabled``, and per-control ``query``. + * - ``static_select`` + - Dropdown menu. Requires ``action_id`` and ``placeholder``. Optional ``options`` (``text`` / ``value`` pairs), ``initial_option``, ``disabled``, ``data_source`` (``users`` or ``channels`` for dynamic pickers), and ``query``. + * - ``container`` + - Groups nested blocks in ``content``. Optional ``border``, ``accent_color``, ``background`` (``gray`` or ``none``), ``gap``, ``flow`` (``horizontal`` or ``vertical``), and ``max_height`` (``none``, ``small``, ``medium``, ``large``) to clip and scroll overflowing content. + * - ``column_set`` / ``column`` + - Multi-column layout. A ``column_set`` contains ``columns``; each ``column`` has ``items`` and optional ``width`` (``auto`` or ``stretch``). + * - ``collapsible`` + - Expandable section with ``header`` and ``content`` block arrays. Optional ``collapsed`` (defaults to expanded). + +Malformed block entries are skipped at render time; valid blocks in the same array still display. + +Container example +~~~~~~~~~~~~~~~~~ + +.. code-block:: json + + { + "props": { + "mm_blocks": [ + { + "type": "container", + "accent_color": "#439FE0", + "border": true, + "gap": "small", + "content": [ + {"type": "text", "text": "**Incident summary**"}, + {"type": "text", "text": "Severity: high", "is_subtle": true, "size": "small"}, + { + "type": "column_set", + "columns": [ + { + "type": "column", + "width": "stretch", + "items": [{"type": "text", "text": "Service: **payments**"}] + }, + { + "type": "column", + "width": "stretch", + "items": [{"type": "text", "text": "Region: **us-east-1**"}] + } + ] + } + ] + } + ] + } + } + +Interactive actions +------------------- + +Define one entry in ``mm_blocks_actions`` for each ``action_id`` used by a ``button`` or ``static_select`` block. + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Action type + - Behavior + * - ``external`` + - Mattermost sends an HTTP POST to ``url`` with the user's selection, a ``trigger_id`` for follow-up calls (such as opening an `interactive dialog `_), and optional ``context``. Your integration can update the original post or return an ephemeral message. + * - ``openURL`` + - Navigates the user to ``url`` inside Mattermost (relative paths such as ``/team/channels/town-square``) or in the system browser for absolute ``http``/``https`` links. The response may include ``goto_location`` for client-side routing. + +Optional ``query`` on an action definition is merged into the target URL. Per-control ``query`` on a block is sent in the post-action request body and merged after the action-level query. + +When a user selects a menu option, Mattermost includes ``selected_option`` in the post-action request with the chosen value. + +Action API +---------- + +When a user activates a control, the client calls: + +``POST /api/v4/posts/{post_id}/actions/{action_id}`` + +The request body may include: + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Field + - Description + * - ``cookie`` + - Encrypted action cookie for the post (supplied automatically by Mattermost clients). + * - ``selected_option`` + - Value from a ``static_select`` menu selection. + * - ``query`` + - Per-control query parameters from the block definition. + * - ``integration_format`` + - Source format for the action: ``mm_block``, ``attachment``, ``block``, ``card``, or ``apps_binding``. + +A successful response returns ``status``, ``trigger_id``, and optionally ``goto_location`` for ``openURL`` actions. + +``action_id`` values may contain letters, numbers, underscores (``_``), and hyphens (``-``). + +Legacy formats +-------------- + +Mattermost clients still accept older interactive payload shapes and translate them into MM Blocks for rendering. When multiple formats are present, clients use this priority: + +1. ``props.mm_blocks`` (native) +2. ``props.blocks`` (Slack Block Kit) +3. ``props.cards`` (Adaptive Cards) +4. ``props.attachments`` (Slack-compatible message attachments) + +.. note:: + + Message attachments remain supported for backward compatibility. New integrations should use ``mm_blocks`` and ``mm_blocks_actions`` instead of nesting interactive controls under ``attachments``. + +Attachment actions map to MM Blocks as follows: + +- Attachment ``actions[].id`` becomes ``action_id`` on buttons and selects. +- Attachment ``actions[].integration.url`` is used for external dispatch (equivalent to ``mm_blocks_actions`` entries). +- Button ``style`` values (``primary``, ``good``, ``danger``, hex colors, and so on) are preserved. + +Migrating from attachments +-------------------------- + +1. Move visual content (text, fields, images) into typed MM Blocks—use ``container`` blocks with ``accent_color`` instead of attachment ``color``, and ``text`` blocks instead of ``pretext`` / ``text`` / field values. +2. Replace ``actions`` arrays with ``button`` and ``static_select`` blocks that reference ``action_id`` values. +3. Add an ``mm_blocks_actions`` map keyed by those IDs with ``type``, ``url``, and ``context`` (previously ``integration.url`` and ``integration.context``). +4. Optionally add ``text`` (or ``message``) above the blocks for notifications and search when the block content alone is not enough context. + +Example migration — attachment button: + +.. code-block:: json + + { + "attachments": [ + { + "text": "Approve this change?", + "actions": [ + { + "type": "button", + "id": "approve", + "name": "Approve", + "style": "primary", + "integration": { + "url": "https://example.com/actions/approve", + "context": {"id": "cr-1"} + } + } + ] + } + ] + } + +Equivalent MM Blocks payload: + +.. code-block:: json + + { + "text": "Approve this change?", + "props": { + "mm_blocks": [ + {"type": "text", "text": "Approve this change?"}, + { + "type": "button", + "text": "Approve", + "style": "primary", + "action_id": "approve" + } + ], + "mm_blocks_actions": { + "approve": { + "type": "external", + "url": "https://example.com/actions/approve", + "context": {"id": "cr-1"} + } + } + } + } + +End-user experience +------------------- + +See :doc:`Extend Mattermost with integrations ` for end-user guidance on buttons, menus, collapsible sections, and expandable content. See :doc:`Troubleshoot MM Blocks ` if content does not render or respond as expected. + +On all supported clients, users can tap buttons, open static select menus, and expand or collapse ``collapsible`` sections inline in the channel. + +Containers with a ``max_height`` preset clip overflowing content. On mobile, users select the expand control on a clipped region to open a full-screen **Scrollable content** view. On web and desktop, the same regions scroll inside the post. + +Legacy attachment posts render with the same MM Blocks UI after client-side translation, so button and menu behavior is consistent across formats. + +Related documentation +--------------------- + +- :doc:`Incoming webhooks ` — post MM Blocks through a webhook URL. +- :doc:`Outgoing webhooks ` — return MM Blocks in webhook responses. +- `Interactive messages `_ — action handling, ephemeral updates, and integration responses. +- `Message attachments `_ — legacy Slack-compatible format (still supported). +- `Interactive dialogs `_ — collect structured input after a button click. diff --git a/source/integrations-guide/outgoing-webhooks.rst b/source/integrations-guide/outgoing-webhooks.rst index 4a7784d4780..ad5f7cf508f 100644 --- a/source/integrations-guide/outgoing-webhooks.rst +++ b/source/integrations-guide/outgoing-webhooks.rst @@ -143,7 +143,7 @@ The JSON response can contain the following parameters: * - Parameter - Description * - ``text`` - - (Required if ``attachments`` is not set) :doc:`Markdown-formatted ` message. + - (Required if ``attachments`` and ``props.mm_blocks`` are not set) :doc:`Markdown-formatted ` message. * - ``response_type`` - Set to ``comment`` to reply to the message that triggered the webhook. Defaults to ``post``, which creates a new message. * - ``username`` @@ -151,11 +151,11 @@ The JSON response can contain the following parameters: * - ``icon_url`` - Overrides the default profile picture. Requires :ref:`Enable integrations to override profile picture icons ` to be enabled. * - ``attachments`` - - (Required if ``text`` is not set) An array of `message attachment `_ objects. + - (Required if ``text`` and ``props.mm_blocks`` are not set) An array of `message attachment `_ objects. Legacy format; prefer ``props.mm_blocks`` for new integrations. See :doc:`MM Blocks `. * - ``type`` - Sets the post type, mainly for plugins. If set, must begin with ``custom_``. * - ``props`` - - A JSON object for storing metadata. + - A JSON object for storing metadata. Use ``mm_blocks`` and ``mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). * - ``priority`` - Sets the priority of the message. See `message priorities `_. @@ -184,21 +184,22 @@ This response would produce a threaded reply to the original message that trigge :alt: Example of a full response from an outgoing webhook. :width: 400 -You can also include `message attachments `_ and `interactive messages `_ in your response to create more advanced workflows. +You can also include :doc:`MM Blocks `, `message attachments `_, and `interactive messages `_ in your response to create more advanced workflows. Do More with Outgoing Webhooks ------------------------------ Turn keyword-triggered callbacks into guided, in-channel workflows by returning buttons, menus, and other interactive elements in your webhook responses so users can act immediately. -- `Message Attachments `_: Return rich, structured results (IDs, statuses, fields, links, images) for quick confirmation and follow-up. +- :doc:`MM Blocks `: **Recommended.** Return structured, interactive content with ``props.mm_blocks`` and ``props.mm_blocks_actions``. +- `Message Attachments `_: Legacy format for rich, structured results. Existing payloads are translated to MM Blocks at render time; use MM Blocks for new integrations. - `Interactive Messages `_: Present next-step actions (Acknowledge, Assign, Escalate) as buttons/menus directly in your response—no context switching. - `Interactive Dialogs `_: When a button/menu click requires more info (e.g., “Acknowledge with note”, “Assign to user”), open a dialog to collect structured inputs with required fields, min/max lengths, server-driven user/channel pickers, validated defaults, inline field errors, placeholders, and help text. - `Message Priority `_: Include ``priority`` in your response to mark critical updates and optionally request acknowledgements or persistent notifications. .. note:: - - Outgoing webhook responses support attachments and interactive actions. When a user clicks an action, your integration receives a signed trigger ID and can open an interactive dialog via the dialog API. You can also control visibility with the response type (in-channel vs ephemeral). + - Outgoing webhook responses support MM Blocks, attachments, and interactive actions. When a user clicks an action, your integration receives a signed trigger ID and can open an interactive dialog via the dialog API. You can also control visibility with the response type (in-channel vs ephemeral). - Need a dedicated identity, permissions scoping, or need to post outside of webhook/command flows? Use a `bot account `_ if you need a more permanent solution than using overrides for simple branding. - If your command backend needs to call Mattermost APIs (e.g., posting messages, ephemeral posts, opening interactive dialogs, etc.), authenticate with a bot user `personal access token `_. We recommend avoiding human/System Admin personal access tokens for automations and rotating and storing tokens securely. - Looking to support private channels, direct messages, and autocomplete? Use a :doc:`built-in slash command `, or create a `custom slash command `_. You can additionally tegrate Mattermost with custom integrations hosted within your internal OAuth infrastructure `using the Client Credentials OAuth 2.0 grant type `_. Mattermost also makes it easy to `migrate integrations written for Slack to Mattermost `_. \ No newline at end of file diff --git a/source/integrations-guide/slash-commands.rst b/source/integrations-guide/slash-commands.rst index 396c763e92e..225ec80803b 100644 --- a/source/integrations-guide/slash-commands.rst +++ b/source/integrations-guide/slash-commands.rst @@ -51,4 +51,4 @@ Using ``/pagerduty trigger`` can open a form to start a new incident, notify on- **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 as :doc:`MM Blocks ` or message attachments with links. \ No newline at end of file diff --git a/source/integrations-guide/webhook-integrations.rst b/source/integrations-guide/webhook-integrations.rst index 851c24af678..b7a351e0f06 100644 --- a/source/integrations-guide/webhook-integrations.rst +++ b/source/integrations-guide/webhook-integrations.rst @@ -11,6 +11,7 @@ Webhooks Incoming Webhooks Outgoing Webhooks + MM Blocks Imagine your CI/CD pipeline just finished a build. Rather than digging through logs, a Mattermost channel instantly shows a new message: @@ -22,6 +23,7 @@ With webhooks, you can: - Receive updates in Mattermost from other systems via :doc:`Incoming Webhooks `. - Send data out of Mattermost to external endpoints via :doc:`Outgoing Webhooks ` based on channel activity. +- Build rich, interactive posts with buttons, menus, images, and layouts using :doc:`MM Blocks `—the recommended alternative to legacy `message attachments `_. Because webhooks use lightweight HTTP POST requests with JSON payloads, they're easy to set up with virtually any tool or platform, whether you need quick notifications or deep integration with enterprise workflows. From 0dc201a9f10e5529063fe288af4d841e65369ba5 Mon Sep 17 00:00:00 2001 From: Daniel Espino Date: Sat, 6 Jun 2026 14:52:53 +0200 Subject: [PATCH 2/7] Address review comments --- .../access/client-availability.rst | 4 +++- source/get-help/mm-blocks-troubleshooting.rst | 2 +- .../integrations-guide/incoming-webhooks.rst | 4 ++-- source/integrations-guide/mm-blocks.rst | 20 +++++++++---------- .../integrations-guide/outgoing-webhooks.rst | 4 ++-- source/integrations-guide/slash-commands.rst | 2 +- 6 files changed, 19 insertions(+), 17 deletions(-) diff --git a/source/end-user-guide/access/client-availability.rst b/source/end-user-guide/access/client-availability.rst index 2d69504e91b..3bba4632a21 100644 --- a/source/end-user-guide/access/client-availability.rst +++ b/source/end-user-guide/access/client-availability.rst @@ -147,7 +147,7 @@ Integrations +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Outgoing webhooks `_ | |checkmark| | |checkmark| | |checkmark| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ -| :doc:`MM Blocks ` | |checkmark| | |checkmark| | |checkmark| | +| :doc:`MM Blocks ` [1]_ | Conditional | Conditional | Conditional | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Message attachments `_ | |checkmark| | |checkmark| | |checkmark| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ @@ -160,6 +160,8 @@ Integrations | `Right-hand sidebar `_ | |checkmark| | |checkmark| | | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ +.. [1] Requires the ``MmBlocksEnabled`` feature flag on the Mattermost server. When disabled, clients do not render native ``mm_blocks`` payloads and the server rejects MM Blocks action requests. Self-hosted deployments can set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` to turn the feature off. See :doc:`MM Blocks ` for details. + Authentication ~~~~~~~~~~~~~~ diff --git a/source/get-help/mm-blocks-troubleshooting.rst b/source/get-help/mm-blocks-troubleshooting.rst index 61179a8c427..60df10a7084 100644 --- a/source/get-help/mm-blocks-troubleshooting.rst +++ b/source/get-help/mm-blocks-troubleshooting.rst @@ -27,7 +27,7 @@ Buttons or menus do not respond 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 ` 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 network connectivity.** External actions require Mattermost to reach the integration URL configured by the post author. Connectivity issues on the server or integration host can prevent responses. +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 diff --git a/source/integrations-guide/incoming-webhooks.rst b/source/integrations-guide/incoming-webhooks.rst index fe581ca4c94..a4ec821bd75 100644 --- a/source/integrations-guide/incoming-webhooks.rst +++ b/source/integrations-guide/incoming-webhooks.rst @@ -129,7 +129,7 @@ The JSON payload can contain the following parameters: - Sets the post type, mainly for use by plugins. If set, must begin with ``custom_``. * - ``props`` - No - - A JSON object for storing metadata. Use ``mm_blocks`` and ``mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). 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 ``props.mm_blocks`` and ``props.mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). 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 `_. @@ -226,7 +226,7 @@ Transform basic message posts into rich, interactive notifications by including - :doc:`MM Blocks `: **Recommended.** Build structured, interactive posts with text, images, layouts, buttons, and menus using ``props.mm_blocks`` and ``props.mm_blocks_actions``. - `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 `_: 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 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 `_: 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 `_: Set ``priority`` to elevate critical posts and optionally request acknowledgements or persistent notifications. diff --git a/source/integrations-guide/mm-blocks.rst b/source/integrations-guide/mm-blocks.rst index c8d0f9f25d8..7a2d06c644c 100644 --- a/source/integrations-guide/mm-blocks.rst +++ b/source/integrations-guide/mm-blocks.rst @@ -16,11 +16,11 @@ Overview Interactive posts combine: - **Content blocks** in ``props.mm_blocks`` — text, images, dividers, containers, columns, collapsible sections, buttons, and static selects. -- **Action definitions** in ``props.mm_blocks_actions`` — maps each ``action_id`` to an integration URL or in-app navigation target. +- **Action definitions** in ``props.mm_blocks_actions`` — map each ``action_id`` to an integration URL or in-app navigation target. -When a post is created, the server encrypts ``mm_blocks_actions`` into a single cookie string before the post is sent to clients. Users interact with buttons and menus in the channel; Mattermost calls your integration and can update the post or return an ephemeral reply. +When a post is created, the server encrypts ``props.mm_blocks_actions`` into a single cookie string before the post is sent to clients. Users interact with buttons and menus in the channel; Mattermost calls your integration and can update the post or return an ephemeral reply. -MM Blocks are supported on web, desktop, and mobile clients. Availability is controlled by the ``MmBlocksEnabled`` `feature flag `_ (enabled by default in current Mattermost releases). Self-hosted deployments can set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` to disable rendering and action dispatch for MM Blocks payloads. +MM Blocks are supported on web, desktop, and mobile clients. Availability is controlled by the ``MmBlocksEnabled`` `feature flag `_, which defaults to ``true``. Self-hosted deployments can set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` to disable rendering and action dispatch for MM Blocks payloads. Quick start ----------- @@ -73,7 +73,7 @@ Post properties * - ``props.mm_blocks_actions`` - Object keyed by ``action_id``. Each value defines how Mattermost handles a button press or menu selection. Replaced on the wire by an encrypted cookie after the post is saved. -You can include ``mm_blocks`` in any post payload that supports ``props``, including :doc:`incoming webhooks `, :doc:`outgoing webhook ` responses, slash command responses, bot posts, and ephemeral posts created through the API. +You can include ``props.mm_blocks`` and ``props.mm_blocks_actions`` in any payload that supports a ``props`` object, including :doc:`incoming webhooks `, :doc:`outgoing webhook ` responses, slash command responses, bot posts, and ephemeral posts created through the API. Block types ----------- @@ -143,7 +143,7 @@ Container example Interactive actions ------------------- -Define one entry in ``mm_blocks_actions`` for each ``action_id`` used by a ``button`` or ``static_select`` block. +Define one entry in ``props.mm_blocks_actions`` for each ``action_id`` used by a ``button`` or ``static_select`` block. .. list-table:: :widths: 20 80 @@ -196,16 +196,16 @@ Mattermost clients still accept older interactive payload shapes and translate t 1. ``props.mm_blocks`` (native) 2. ``props.blocks`` (Slack Block Kit) 3. ``props.cards`` (Adaptive Cards) -4. ``props.attachments`` (Slack-compatible message attachments) +4. ``attachments`` in webhook and slash command payloads (stored as ``props.attachments`` on the post; Slack-compatible message attachments) .. note:: - Message attachments remain supported for backward compatibility. New integrations should use ``mm_blocks`` and ``mm_blocks_actions`` instead of nesting interactive controls under ``attachments``. + Message attachments remain supported for backward compatibility. New integrations should use ``props.mm_blocks`` and ``props.mm_blocks_actions`` instead of nesting interactive controls under top-level ``attachments``. Attachment actions map to MM Blocks as follows: - Attachment ``actions[].id`` becomes ``action_id`` on buttons and selects. -- Attachment ``actions[].integration.url`` is used for external dispatch (equivalent to ``mm_blocks_actions`` entries). +- Attachment ``actions[].integration.url`` is used for external dispatch (equivalent to ``props.mm_blocks_actions`` entries). - Button ``style`` values (``primary``, ``good``, ``danger``, hex colors, and so on) are preserved. Migrating from attachments @@ -213,8 +213,8 @@ Migrating from attachments 1. Move visual content (text, fields, images) into typed MM Blocks—use ``container`` blocks with ``accent_color`` instead of attachment ``color``, and ``text`` blocks instead of ``pretext`` / ``text`` / field values. 2. Replace ``actions`` arrays with ``button`` and ``static_select`` blocks that reference ``action_id`` values. -3. Add an ``mm_blocks_actions`` map keyed by those IDs with ``type``, ``url``, and ``context`` (previously ``integration.url`` and ``integration.context``). -4. Optionally add ``text`` (or ``message``) above the blocks for notifications and search when the block content alone is not enough context. +3. Add a ``props.mm_blocks_actions`` map keyed by those IDs with ``type``, ``url``, and ``context`` (previously ``integration.url`` and ``integration.context``). +4. Optionally add ``text`` above the blocks for notifications and search when the block content alone is not enough context. Example migration — attachment button: diff --git a/source/integrations-guide/outgoing-webhooks.rst b/source/integrations-guide/outgoing-webhooks.rst index ad5f7cf508f..2fe3833299e 100644 --- a/source/integrations-guide/outgoing-webhooks.rst +++ b/source/integrations-guide/outgoing-webhooks.rst @@ -155,7 +155,7 @@ The JSON response can contain the following parameters: * - ``type`` - Sets the post type, mainly for plugins. If set, must begin with ``custom_``. * - ``props`` - - A JSON object for storing metadata. Use ``mm_blocks`` and ``mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). + - A JSON object for storing metadata. Use ``props.mm_blocks`` and ``props.mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). * - ``priority`` - Sets the priority of the message. See `message priorities `_. @@ -202,4 +202,4 @@ Turn keyword-triggered callbacks into guided, in-channel workflows by returning - Outgoing webhook responses support MM Blocks, attachments, and interactive actions. When a user clicks an action, your integration receives a signed trigger ID and can open an interactive dialog via the dialog API. You can also control visibility with the response type (in-channel vs ephemeral). - Need a dedicated identity, permissions scoping, or need to post outside of webhook/command flows? Use a `bot account `_ if you need a more permanent solution than using overrides for simple branding. - If your command backend needs to call Mattermost APIs (e.g., posting messages, ephemeral posts, opening interactive dialogs, etc.), authenticate with a bot user `personal access token `_. We recommend avoiding human/System Admin personal access tokens for automations and rotating and storing tokens securely. - - Looking to support private channels, direct messages, and autocomplete? Use a :doc:`built-in slash command `, or create a `custom slash command `_. You can additionally tegrate Mattermost with custom integrations hosted within your internal OAuth infrastructure `using the Client Credentials OAuth 2.0 grant type `_. Mattermost also makes it easy to `migrate integrations written for Slack to Mattermost `_. \ No newline at end of file + - Looking to support private channels, direct messages, and autocomplete? Use a :doc:`built-in slash command `, or create a `custom slash command `_. You can additionally integrate Mattermost with custom integrations hosted within your internal OAuth infrastructure `using the Client Credentials OAuth 2.0 grant type `_. Mattermost also makes it easy to `migrate integrations written for Slack to Mattermost `_. \ No newline at end of file diff --git a/source/integrations-guide/slash-commands.rst b/source/integrations-guide/slash-commands.rst index 225ec80803b..5a290757cf3 100644 --- a/source/integrations-guide/slash-commands.rst +++ b/source/integrations-guide/slash-commands.rst @@ -51,4 +51,4 @@ Using ``/pagerduty trigger`` can open a form to start a new incident, notify on- **Knowledge retrieval** -A command like ``/docs search authentication`` queries your documentation system and returns a list of relevant articles as :doc:`MM Blocks ` or 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 as :doc:`MM Blocks ` or legacy `message attachments `_ with links. \ No newline at end of file From e1256096fb2b143079c2c53ebfa2bd1b6f42247f Mon Sep 17 00:00:00 2001 From: Daniel Espino Date: Mon, 8 Jun 2026 11:43:39 +0200 Subject: [PATCH 3/7] Address copilot comments --- source/deployment-guide/mobile/mobile-troubleshooting.rst | 6 +++--- source/end-user-guide/access/client-availability.rst | 2 +- source/get-help/mm-blocks-troubleshooting.rst | 2 +- source/integrations-guide/mm-blocks.rst | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/deployment-guide/mobile/mobile-troubleshooting.rst b/source/deployment-guide/mobile/mobile-troubleshooting.rst index 2c83f9ffda9..d98e7ee4122 100644 --- a/source/deployment-guide/mobile/mobile-troubleshooting.rst +++ b/source/deployment-guide/mobile/mobile-troubleshooting.rst @@ -143,6 +143,8 @@ If you did not receive a push notification when testing push notifications, use - If the log message displays, it means a message was sent to the HPNS server and was not received by your mobile app. Please `create a support ticket `_ with the subject "HPNS issue" for help from Mattermost's Support team. - If the log message does not display, it means no mobile push notification was sent to “Account A”. Please repeat the process starting at step 2 and double-check each step. +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**. @@ -150,6 +152,4 @@ If you did not receive a push notification when testing push notifications, use Integration posts (MM Blocks) do not render or respond ---------------------------------------------------- -If buttons, menus, or structured layout content from an integration post is missing or unresponsive on mobile, see :doc:`Troubleshoot MM Blocks `. - -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 +If buttons, menus, or structured layout content from an integration post is missing or unresponsive on mobile, see :doc:`Troubleshoot MM Blocks `. \ No newline at end of file diff --git a/source/end-user-guide/access/client-availability.rst b/source/end-user-guide/access/client-availability.rst index 3bba4632a21..a21c13025d5 100644 --- a/source/end-user-guide/access/client-availability.rst +++ b/source/end-user-guide/access/client-availability.rst @@ -160,7 +160,7 @@ Integrations | `Right-hand sidebar `_ | |checkmark| | |checkmark| | | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ -.. [1] Requires the ``MmBlocksEnabled`` feature flag on the Mattermost server. When disabled, clients do not render native ``mm_blocks`` payloads and the server rejects MM Blocks action requests. Self-hosted deployments can set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` to turn the feature off. See :doc:`MM Blocks ` for details. +.. [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. See :doc:`MM Blocks ` for details. Authentication ~~~~~~~~~~~~~~ diff --git a/source/get-help/mm-blocks-troubleshooting.rst b/source/get-help/mm-blocks-troubleshooting.rst index 60df10a7084..54bff4ce64b 100644 --- a/source/get-help/mm-blocks-troubleshooting.rst +++ b/source/get-help/mm-blocks-troubleshooting.rst @@ -15,7 +15,7 @@ MM Blocks content does not appear 1. **Update your client.** MM Blocks require a current Mattermost web, desktop, or mobile app. See :doc:`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 with the ``MmBlocksEnabled`` feature flag. When disabled, native MM Blocks payloads are not rendered and their actions are rejected. See :doc:`MM Blocks ` for details. +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. See :doc:`MM Blocks ` for details. 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 diff --git a/source/integrations-guide/mm-blocks.rst b/source/integrations-guide/mm-blocks.rst index 7a2d06c644c..92419e6fe87 100644 --- a/source/integrations-guide/mm-blocks.rst +++ b/source/integrations-guide/mm-blocks.rst @@ -20,7 +20,7 @@ Interactive posts combine: When a post is created, the server encrypts ``props.mm_blocks_actions`` into a single cookie string before the post is sent to clients. Users interact with buttons and menus in the channel; Mattermost calls your integration and can update the post or return an ephemeral reply. -MM Blocks are supported on web, desktop, and mobile clients. Availability is controlled by the ``MmBlocksEnabled`` `feature flag `_, which defaults to ``true``. Self-hosted deployments can set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` to disable rendering and action dispatch for MM Blocks payloads. +MM Blocks are supported on web, desktop, and mobile clients. Availability is controlled by the ``MM_FEATUREFLAGS_MMBLOCKSENABLED`` `feature flag `_ (defaults to ``true``). Set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` on self-hosted deployments to disable rendering and action dispatch for MM Blocks payloads. Quick start ----------- @@ -73,7 +73,7 @@ Post properties * - ``props.mm_blocks_actions`` - Object keyed by ``action_id``. Each value defines how Mattermost handles a button press or menu selection. Replaced on the wire by an encrypted cookie after the post is saved. -You can include ``props.mm_blocks`` and ``props.mm_blocks_actions`` in any payload that supports a ``props`` object, including :doc:`incoming webhooks `, :doc:`outgoing webhook ` responses, slash command responses, bot posts, and ephemeral posts created through the API. +You can include ``props.mm_blocks`` and ``props.mm_blocks_actions`` in any payload that supports a ``props`` object, including :doc:`incoming webhooks `, :doc:`outgoing webhooks ` responses, slash command responses, bot posts, and ephemeral posts created through the API. Block types ----------- From 0d690d9c612c71ecfa774f97789e7a110b4d8561 Mon Sep 17 00:00:00 2001 From: Daniel Espino Date: Mon, 8 Jun 2026 12:44:48 +0200 Subject: [PATCH 4/7] Address copilot comment --- source/deployment-guide/mobile/mobile-troubleshooting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/deployment-guide/mobile/mobile-troubleshooting.rst b/source/deployment-guide/mobile/mobile-troubleshooting.rst index d98e7ee4122..c38edfc7062 100644 --- a/source/deployment-guide/mobile/mobile-troubleshooting.rst +++ b/source/deployment-guide/mobile/mobile-troubleshooting.rst @@ -150,6 +150,6 @@ If push notifications are not being delivered on the mobile device, confirm that 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**. Integration posts (MM Blocks) do not render or respond ----------------------------------------------------- +------------------------------------------------------- If buttons, menus, or structured layout content from an integration post is missing or unresponsive on mobile, see :doc:`Troubleshoot MM Blocks `. \ No newline at end of file From 06075f3009f5f9a0fcce70bd976637e99c6da6a4 Mon Sep 17 00:00:00 2001 From: Daniel Espino Date: Mon, 8 Jun 2026 13:14:10 +0200 Subject: [PATCH 5/7] Address comments --- source/integrations-guide/slash-commands.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/integrations-guide/slash-commands.rst b/source/integrations-guide/slash-commands.rst index 5a290757cf3..121929613bc 100644 --- a/source/integrations-guide/slash-commands.rst +++ b/source/integrations-guide/slash-commands.rst @@ -51,4 +51,4 @@ Using ``/pagerduty trigger`` can open a form to start a new incident, notify on- **Knowledge retrieval** -A command like ``/docs search authentication`` queries your documentation system and returns a list of relevant articles as :doc:`MM Blocks ` or legacy `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 ` (recommended) or legacy `message attachments `_ with links. \ No newline at end of file From fd769eaf21485162f8b7c4968195efaef5d29e87 Mon Sep 17 00:00:00 2001 From: Daniel Espino Date: Fri, 19 Jun 2026 17:19:07 +0200 Subject: [PATCH 6/7] Address comments --- .../mobile/mobile-troubleshooting.rst | 6 +- .../access/client-availability.rst | 4 +- .../extend-mattermost-with-integrations.rst | 35 +-- .../messaging-collaboration.rst | 2 +- source/get-help/mm-blocks-troubleshooting.rst | 8 +- source/integrations-guide/faq.rst | 4 +- .../integrations-guide/incoming-webhooks.rst | 8 +- .../integrations-guide-index.rst | 2 +- source/integrations-guide/mm-blocks.rst | 280 +----------------- .../integrations-guide/outgoing-webhooks.rst | 8 +- source/integrations-guide/slash-commands.rst | 2 +- .../webhook-integrations.rst | 3 +- 12 files changed, 30 insertions(+), 332 deletions(-) diff --git a/source/deployment-guide/mobile/mobile-troubleshooting.rst b/source/deployment-guide/mobile/mobile-troubleshooting.rst index c38edfc7062..9eb3d613f65 100644 --- a/source/deployment-guide/mobile/mobile-troubleshooting.rst +++ b/source/deployment-guide/mobile/mobile-troubleshooting.rst @@ -143,13 +143,13 @@ If you did not receive a push notification when testing push notifications, use - If the log message displays, it means a message was sent to the HPNS server and was not received by your mobile app. Please `create a support ticket `_ with the subject "HPNS issue" for help from Mattermost's Support team. - If the log message does not display, it means no mobile push notification was sent to “Account A”. Please repeat the process starting at step 2 and double-check each step. -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. + Integration posts (MM Blocks) do not render or respond ------------------------------------------------------- -If buttons, menus, or structured layout content from an integration post is missing or unresponsive on mobile, see :doc:`Troubleshoot MM Blocks `. \ No newline at end of file +If buttons, menus, or structured content from an integration post is missing or unresponsive on mobile, see :doc:`Troubleshoot MM Blocks `. diff --git a/source/end-user-guide/access/client-availability.rst b/source/end-user-guide/access/client-availability.rst index a21c13025d5..502ade34d82 100644 --- a/source/end-user-guide/access/client-availability.rst +++ b/source/end-user-guide/access/client-availability.rst @@ -147,7 +147,7 @@ Integrations +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Outgoing webhooks `_ | |checkmark| | |checkmark| | |checkmark| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ -| :doc:`MM Blocks ` [1]_ | Conditional | Conditional | Conditional | +| `MM Blocks `_ [1]_ | Conditional | Conditional | Conditional | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Message attachments `_ | |checkmark| | |checkmark| | |checkmark| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ @@ -160,7 +160,7 @@ Integrations | `Right-hand sidebar `_ | |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. See :doc:`MM Blocks ` for details. +.. [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 ~~~~~~~~~~~~~~ diff --git a/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst b/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst index 506849167ce..ef98ca8cb17 100644 --- a/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst +++ b/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst @@ -29,40 +29,9 @@ Mattermost interoperability Interact with integration messages ---------------------------------- -Many integrations post rich, actionable content into channels using **MM Blocks**—a structured layout format for text, images, buttons, menus, and grouped content. You may also see the same presentation for older integrations that use message attachments; Mattermost translates those into the MM Blocks layout automatically. +Many integrations post rich, actionable content into channels—such as status updates with **Approve** or **Acknowledge** buttons, option menus, images, and grouped content. When you select a button or choose an option from a menu, Mattermost sends your selection to the integration. The integration may update the post in the channel or reply with a message visible only to you. -What you may see in a channel -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Integration posts can include: - -- **Text and images** formatted with headings, emphasis, and links. -- **Grouped content** in bordered or shaded containers, sometimes arranged in columns. -- **Buttons** labeled with actions such as *Acknowledge*, *Approve*, or *View details*. -- **Menus** (static selects) that let you choose from a list of options. -- **Collapsible sections** with a header you can tap to show or hide additional details. - -Using buttons and menus -~~~~~~~~~~~~~~~~~~~~~~~ - -1. **Buttons:** Select a button to send your choice to the integration. The integration may update the post in place or send you a private follow-up message visible only to you. -2. **Menus:** Select the menu to open the list of options, then choose one. Mattermost sends the selected value to the integration, similar to pressing a button. -3. **Disabled controls:** Some buttons or menus appear grayed out and cannot be selected until the integration enables them. - -If nothing happens after you select a button or menu option, wait a moment in case the integration is still processing. Contact your system admin if actions consistently fail. - -Expandable and scrollable content -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some integration posts clip long content to keep the channel readable. - -- **Collapsible sections:** Select the section header to expand or collapse the content beneath it. -- **Web and desktop:** When a content region has a height limit, scroll inside the post to read the full content. -- **Mobile:** When content is clipped, a fade appears at the bottom of the region and an expand control is shown in the bottom-right corner. Select that control to open a full-screen **Scrollable content** view. Scroll through the complete content, then use the back gesture or navigation control to return to the channel. - -.. tip:: - - Integration developers can learn how to build MM Blocks payloads in the :doc:`MM Blocks ` documentation. If content does not render or respond as expected, see :doc:`Troubleshoot MM Blocks `. +If content does not render or respond as expected, see :doc:`Troubleshoot MM Blocks `. .. tip:: diff --git a/source/end-user-guide/messaging-collaboration.rst b/source/end-user-guide/messaging-collaboration.rst index 916a58093f3..ed0dbfd91b7 100644 --- a/source/end-user-guide/messaging-collaboration.rst +++ b/source/end-user-guide/messaging-collaboration.rst @@ -36,4 +36,4 @@ Getting Started * :doc:`Communicate with messages and threads ` Learn how to get started collaborating within Mattermost channels. * :doc:`Collaborate within Microsoft Teams ` - Learn how to get started collaborating within Microsoft Teams. * :doc:`Keyboard shortcuts ` - Make a more efficient use of your keyboard with keyboard shortcuts. -* :doc:`Extend Mattermost with integrations ` - Find open source integrations to common tools in the Mattermost Marketplace, and learn how to interact with rich integration messages (MM Blocks). +* :doc:`Extend Mattermost with integrations ` - Find open source integrations to common tools in the Mattermost Marketplace, and learn how to interact with rich integration messages. diff --git a/source/get-help/mm-blocks-troubleshooting.rst b/source/get-help/mm-blocks-troubleshooting.rst index 54bff4ce64b..23f1bcc8867 100644 --- a/source/get-help/mm-blocks-troubleshooting.rst +++ b/source/get-help/mm-blocks-troubleshooting.rst @@ -4,18 +4,18 @@ Troubleshoot MM Blocks .. include:: ../_static/badges/all-commercial.rst :start-after: :nosearch: -Integration posts that use :doc:`MM Blocks ` show structured content—text, images, buttons, menus, and layouts—directly in a channel. This page covers common issues when MM Blocks do not render or respond as expected, with emphasis on mobile clients. +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 layout blocks are missing. +**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 ` 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. See :doc:`MM Blocks ` for details. +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 @@ -71,7 +71,7 @@ Get more help ------------- - **End users:** See :doc:`Extend Mattermost with integrations ` for how to use buttons, menus, and expandable content in channels. -- **Developers:** See :doc:`MM Blocks ` for payload format, action APIs, and migration guidance. +- **Developers:** See the `MM Blocks reference `_ for payload format, action APIs, and migration guidance. - **Mobile deployment issues:** See :doc:`Mobile deployment 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 `_ or contact your system administrator. diff --git a/source/integrations-guide/faq.rst b/source/integrations-guide/faq.rst index 951dc971f4c..2e67b4d5c2c 100644 --- a/source/integrations-guide/faq.rst +++ b/source/integrations-guide/faq.rst @@ -53,9 +53,9 @@ Mattermost doesn't currently support the ability to attach files to a post made What are MM Blocks? -------------------- -:doc:`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 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. -MM Blocks are the recommended way to build interactive messages with buttons, menus, images, and layouts. Legacy `message attachments `_ and other formats (Slack Block Kit ``blocks``, Adaptive Cards ``cards``) are still accepted and translated into MM Blocks at render time. +See the `MM Blocks reference `_ in the developer documentation for integration details. If content does not render as expected, see :doc:`Troubleshoot MM Blocks `. Where can I find existing integrations? --------------------------------------- diff --git a/source/integrations-guide/incoming-webhooks.rst b/source/integrations-guide/incoming-webhooks.rst index a4ec821bd75..bb0eb089240 100644 --- a/source/integrations-guide/incoming-webhooks.rst +++ b/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 `. + 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 @@ -123,13 +125,13 @@ The JSON payload can contain the following parameters: - Overrides the ``icon_url`` with an emoji. Use the emoji name (e.g., ``:tada:``). The :ref:`Enable integrations to override profile picture icons ` setting must be enabled. * - ``attachments`` - Yes (if ``text`` and ``props.mm_blocks`` are not set) - - An array of `message attachment `_ objects for richer formatting. Legacy format; prefer ``props.mm_blocks`` for new integrations. See :doc:`MM Blocks `. + - An array of `message attachment `_ objects for richer formatting. Legacy format; use `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. Use ``props.mm_blocks`` and ``props.mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). 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 `_ 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 `_. @@ -224,7 +226,7 @@ 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. -- :doc:`MM Blocks `: **Recommended.** Build structured, interactive posts with text, images, layouts, buttons, and menus using ``props.mm_blocks`` and ``props.mm_blocks_actions``. +- `MM Blocks `_: **Recommended.** Create structured, interactive posts with text, images, buttons, and menus. - `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 `_: 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 `_: 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. diff --git a/source/integrations-guide/integrations-guide-index.rst b/source/integrations-guide/integrations-guide-index.rst index edb62d6dd4f..53673857a37 100644 --- a/source/integrations-guide/integrations-guide-index.rst +++ b/source/integrations-guide/integrations-guide-index.rst @@ -88,7 +88,7 @@ Incoming Webhooks :doc:`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 ` with Slack’s webhook format to make migration easier. For new interactive content, use :doc:`MM Blocks ` instead of message attachments. +Additionally, Mattermost webhook payloads are :ref:`fully compatible ` with Slack’s webhook format to make migration easier. For new interactive content, use `MM Blocks `_ instead of message attachments. Outgoing Webhooks ^^^^^^^^^^^^^^^^^^ diff --git a/source/integrations-guide/mm-blocks.rst b/source/integrations-guide/mm-blocks.rst index 92419e6fe87..83e455799fb 100644 --- a/source/integrations-guide/mm-blocks.rst +++ b/source/integrations-guide/mm-blocks.rst @@ -6,282 +6,10 @@ MM Blocks **Technical complexity:** :ref:`Low-code ` -MM Blocks are Mattermost's structured format for rich, interactive posts. Use them to build notifications with text, images, layouts, buttons, and menus directly in a post's ``props``—without relying on Slack-compatible `message attachments `_. +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 replace message attachments as the recommended way to create `interactive messages `_. Existing attachment-based payloads continue to work: clients translate them into MM Blocks at render time. +MM Blocks are the recommended way to create interactive messages for integrations such as :doc:`incoming webhooks `, plugins, and bot accounts. Legacy `message attachments `_ continue to work; clients translate them into the MM Blocks format at render time. -Overview --------- +For payload structure, block types, action handling, and migration guidance, see the `MM Blocks reference `_ in the developer documentation. -Interactive posts combine: - -- **Content blocks** in ``props.mm_blocks`` — text, images, dividers, containers, columns, collapsible sections, buttons, and static selects. -- **Action definitions** in ``props.mm_blocks_actions`` — map each ``action_id`` to an integration URL or in-app navigation target. - -When a post is created, the server encrypts ``props.mm_blocks_actions`` into a single cookie string before the post is sent to clients. Users interact with buttons and menus in the channel; Mattermost calls your integration and can update the post or return an ephemeral reply. - -MM Blocks are supported on web, desktop, and mobile clients. Availability is controlled by the ``MM_FEATUREFLAGS_MMBLOCKSENABLED`` `feature flag `_ (defaults to ``true``). Set ``MM_FEATUREFLAGS_MMBLOCKSENABLED=false`` on self-hosted deployments to disable rendering and action dispatch for MM Blocks payloads. - -Quick start ------------ - -This incoming webhook payload renders a short message with a primary button. The button calls an external integration URL when clicked. - -.. code-block:: json - - { - "text": "Deployment finished", - "props": { - "mm_blocks": [ - { - "type": "text", - "text": "Build **#42** deployed to *staging*." - }, - { - "type": "divider" - }, - { - "type": "button", - "text": "View logs", - "style": "primary", - "action_id": "view_logs" - } - ], - "mm_blocks_actions": { - "view_logs": { - "type": "external", - "url": "https://example.com/integrations/view-logs", - "context": { - "deployment_id": "42" - } - } - } - } - } - -Post properties ---------------- - -.. list-table:: - :widths: 25 75 - :header-rows: 1 - - * - Property - - Description - * - ``props.mm_blocks`` - - Array of block objects that define layout and interactive controls. See `Block types`_ below. - * - ``props.mm_blocks_actions`` - - Object keyed by ``action_id``. Each value defines how Mattermost handles a button press or menu selection. Replaced on the wire by an encrypted cookie after the post is saved. - -You can include ``props.mm_blocks`` and ``props.mm_blocks_actions`` in any payload that supports a ``props`` object, including :doc:`incoming webhooks `, :doc:`outgoing webhooks ` responses, slash command responses, bot posts, and ephemeral posts created through the API. - -Block types ------------ - -.. list-table:: - :widths: 20 80 - :header-rows: 1 - - * - Type - - Description - * - ``text`` - - Markdown text. Optional ``size`` (``small`` or ``default``) and ``is_subtle`` (muted color). - * - ``divider`` - - Horizontal rule between blocks. - * - ``image`` - - Image with ``url``, optional ``alt_text``, ``title``, ``size`` (``auto``, ``xsmall``, ``small``, ``medium``, ``large``, ``stretch``), ``max_width``, ``max_height``, ``image_style``, and ``horizontal_alignment``. - * - ``button`` - - Labeled button. Requires ``text`` and ``action_id``. Optional ``style`` (``default``, ``primary``, ``danger``, ``good``, ``success``, ``warning``, or ``#RRGGBB`` hex), ``tooltip``, ``disabled``, and per-control ``query``. - * - ``static_select`` - - Dropdown menu. Requires ``action_id`` and ``placeholder``. Optional ``options`` (``text`` / ``value`` pairs), ``initial_option``, ``disabled``, ``data_source`` (``users`` or ``channels`` for dynamic pickers), and ``query``. - * - ``container`` - - Groups nested blocks in ``content``. Optional ``border``, ``accent_color``, ``background`` (``gray`` or ``none``), ``gap``, ``flow`` (``horizontal`` or ``vertical``), and ``max_height`` (``none``, ``small``, ``medium``, ``large``) to clip and scroll overflowing content. - * - ``column_set`` / ``column`` - - Multi-column layout. A ``column_set`` contains ``columns``; each ``column`` has ``items`` and optional ``width`` (``auto`` or ``stretch``). - * - ``collapsible`` - - Expandable section with ``header`` and ``content`` block arrays. Optional ``collapsed`` (defaults to expanded). - -Malformed block entries are skipped at render time; valid blocks in the same array still display. - -Container example -~~~~~~~~~~~~~~~~~ - -.. code-block:: json - - { - "props": { - "mm_blocks": [ - { - "type": "container", - "accent_color": "#439FE0", - "border": true, - "gap": "small", - "content": [ - {"type": "text", "text": "**Incident summary**"}, - {"type": "text", "text": "Severity: high", "is_subtle": true, "size": "small"}, - { - "type": "column_set", - "columns": [ - { - "type": "column", - "width": "stretch", - "items": [{"type": "text", "text": "Service: **payments**"}] - }, - { - "type": "column", - "width": "stretch", - "items": [{"type": "text", "text": "Region: **us-east-1**"}] - } - ] - } - ] - } - ] - } - } - -Interactive actions -------------------- - -Define one entry in ``props.mm_blocks_actions`` for each ``action_id`` used by a ``button`` or ``static_select`` block. - -.. list-table:: - :widths: 20 80 - :header-rows: 1 - - * - Action type - - Behavior - * - ``external`` - - Mattermost sends an HTTP POST to ``url`` with the user's selection, a ``trigger_id`` for follow-up calls (such as opening an `interactive dialog `_), and optional ``context``. Your integration can update the original post or return an ephemeral message. - * - ``openURL`` - - Navigates the user to ``url`` inside Mattermost (relative paths such as ``/team/channels/town-square``) or in the system browser for absolute ``http``/``https`` links. The response may include ``goto_location`` for client-side routing. - -Optional ``query`` on an action definition is merged into the target URL. Per-control ``query`` on a block is sent in the post-action request body and merged after the action-level query. - -When a user selects a menu option, Mattermost includes ``selected_option`` in the post-action request with the chosen value. - -Action API ----------- - -When a user activates a control, the client calls: - -``POST /api/v4/posts/{post_id}/actions/{action_id}`` - -The request body may include: - -.. list-table:: - :widths: 25 75 - :header-rows: 1 - - * - Field - - Description - * - ``cookie`` - - Encrypted action cookie for the post (supplied automatically by Mattermost clients). - * - ``selected_option`` - - Value from a ``static_select`` menu selection. - * - ``query`` - - Per-control query parameters from the block definition. - * - ``integration_format`` - - Source format for the action: ``mm_block``, ``attachment``, ``block``, ``card``, or ``apps_binding``. - -A successful response returns ``status``, ``trigger_id``, and optionally ``goto_location`` for ``openURL`` actions. - -``action_id`` values may contain letters, numbers, underscores (``_``), and hyphens (``-``). - -Legacy formats --------------- - -Mattermost clients still accept older interactive payload shapes and translate them into MM Blocks for rendering. When multiple formats are present, clients use this priority: - -1. ``props.mm_blocks`` (native) -2. ``props.blocks`` (Slack Block Kit) -3. ``props.cards`` (Adaptive Cards) -4. ``attachments`` in webhook and slash command payloads (stored as ``props.attachments`` on the post; Slack-compatible message attachments) - -.. note:: - - Message attachments remain supported for backward compatibility. New integrations should use ``props.mm_blocks`` and ``props.mm_blocks_actions`` instead of nesting interactive controls under top-level ``attachments``. - -Attachment actions map to MM Blocks as follows: - -- Attachment ``actions[].id`` becomes ``action_id`` on buttons and selects. -- Attachment ``actions[].integration.url`` is used for external dispatch (equivalent to ``props.mm_blocks_actions`` entries). -- Button ``style`` values (``primary``, ``good``, ``danger``, hex colors, and so on) are preserved. - -Migrating from attachments --------------------------- - -1. Move visual content (text, fields, images) into typed MM Blocks—use ``container`` blocks with ``accent_color`` instead of attachment ``color``, and ``text`` blocks instead of ``pretext`` / ``text`` / field values. -2. Replace ``actions`` arrays with ``button`` and ``static_select`` blocks that reference ``action_id`` values. -3. Add a ``props.mm_blocks_actions`` map keyed by those IDs with ``type``, ``url``, and ``context`` (previously ``integration.url`` and ``integration.context``). -4. Optionally add ``text`` above the blocks for notifications and search when the block content alone is not enough context. - -Example migration — attachment button: - -.. code-block:: json - - { - "attachments": [ - { - "text": "Approve this change?", - "actions": [ - { - "type": "button", - "id": "approve", - "name": "Approve", - "style": "primary", - "integration": { - "url": "https://example.com/actions/approve", - "context": {"id": "cr-1"} - } - } - ] - } - ] - } - -Equivalent MM Blocks payload: - -.. code-block:: json - - { - "text": "Approve this change?", - "props": { - "mm_blocks": [ - {"type": "text", "text": "Approve this change?"}, - { - "type": "button", - "text": "Approve", - "style": "primary", - "action_id": "approve" - } - ], - "mm_blocks_actions": { - "approve": { - "type": "external", - "url": "https://example.com/actions/approve", - "context": {"id": "cr-1"} - } - } - } - } - -End-user experience -------------------- - -See :doc:`Extend Mattermost with integrations ` for end-user guidance on buttons, menus, collapsible sections, and expandable content. See :doc:`Troubleshoot MM Blocks ` if content does not render or respond as expected. - -On all supported clients, users can tap buttons, open static select menus, and expand or collapse ``collapsible`` sections inline in the channel. - -Containers with a ``max_height`` preset clip overflowing content. On mobile, users select the expand control on a clipped region to open a full-screen **Scrollable content** view. On web and desktop, the same regions scroll inside the post. - -Legacy attachment posts render with the same MM Blocks UI after client-side translation, so button and menu behavior is consistent across formats. - -Related documentation ---------------------- - -- :doc:`Incoming webhooks ` — post MM Blocks through a webhook URL. -- :doc:`Outgoing webhooks ` — return MM Blocks in webhook responses. -- `Interactive messages `_ — action handling, ephemeral updates, and integration responses. -- `Message attachments `_ — legacy Slack-compatible format (still supported). -- `Interactive dialogs `_ — collect structured input after a button click. +If content does not render or respond as expected, see :doc:`Troubleshoot MM Blocks `. diff --git a/source/integrations-guide/outgoing-webhooks.rst b/source/integrations-guide/outgoing-webhooks.rst index 2fe3833299e..81b3ed3f105 100644 --- a/source/integrations-guide/outgoing-webhooks.rst +++ b/source/integrations-guide/outgoing-webhooks.rst @@ -151,11 +151,11 @@ The JSON response can contain the following parameters: * - ``icon_url`` - Overrides the default profile picture. Requires :ref:`Enable integrations to override profile picture icons ` to be enabled. * - ``attachments`` - - (Required if ``text`` and ``props.mm_blocks`` are not set) An array of `message attachment `_ objects. Legacy format; prefer ``props.mm_blocks`` for new integrations. See :doc:`MM Blocks `. + - (Required if ``text`` and ``props.mm_blocks`` are not set) An array of `message attachment `_ objects. Legacy format; use `MM Blocks `_ for new integrations. * - ``type`` - Sets the post type, mainly for plugins. If set, must begin with ``custom_``. * - ``props`` - - A JSON object for storing metadata. Use ``props.mm_blocks`` and ``props.mm_blocks_actions`` for rich, interactive content (see :doc:`MM Blocks `). + - A JSON object for storing metadata. Use `MM Blocks `_ for rich, interactive content. * - ``priority`` - Sets the priority of the message. See `message priorities `_. @@ -184,14 +184,14 @@ This response would produce a threaded reply to the original message that trigge :alt: Example of a full response from an outgoing webhook. :width: 400 -You can also include :doc:`MM Blocks `, `message attachments `_, and `interactive messages `_ in your response to create more advanced workflows. +You can also include `MM Blocks `_, `message attachments `_, and `interactive messages `_ in your response to create more advanced workflows. Do More with Outgoing Webhooks ------------------------------ Turn keyword-triggered callbacks into guided, in-channel workflows by returning buttons, menus, and other interactive elements in your webhook responses so users can act immediately. -- :doc:`MM Blocks `: **Recommended.** Return structured, interactive content with ``props.mm_blocks`` and ``props.mm_blocks_actions``. +- `MM Blocks `_: **Recommended.** Return structured, interactive content with text, buttons, and menus. - `Message Attachments `_: Legacy format for rich, structured results. Existing payloads are translated to MM Blocks at render time; use MM Blocks for new integrations. - `Interactive Messages `_: Present next-step actions (Acknowledge, Assign, Escalate) as buttons/menus directly in your response—no context switching. - `Interactive Dialogs `_: When a button/menu click requires more info (e.g., “Acknowledge with note”, “Assign to user”), open a dialog to collect structured inputs with required fields, min/max lengths, server-driven user/channel pickers, validated defaults, inline field errors, placeholders, and help text. diff --git a/source/integrations-guide/slash-commands.rst b/source/integrations-guide/slash-commands.rst index 121929613bc..637ec2293de 100644 --- a/source/integrations-guide/slash-commands.rst +++ b/source/integrations-guide/slash-commands.rst @@ -51,4 +51,4 @@ Using ``/pagerduty trigger`` can open a form to start a new incident, notify on- **Knowledge retrieval** -A command like ``/docs search authentication`` queries your documentation system and returns a list of relevant articles rendered using :doc:`MM Blocks ` (recommended) or legacy `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 `MM Blocks `_ with links. \ No newline at end of file diff --git a/source/integrations-guide/webhook-integrations.rst b/source/integrations-guide/webhook-integrations.rst index b7a351e0f06..1d758d5c503 100644 --- a/source/integrations-guide/webhook-integrations.rst +++ b/source/integrations-guide/webhook-integrations.rst @@ -11,7 +11,6 @@ Webhooks Incoming Webhooks Outgoing Webhooks - MM Blocks Imagine your CI/CD pipeline just finished a build. Rather than digging through logs, a Mattermost channel instantly shows a new message: @@ -23,7 +22,7 @@ With webhooks, you can: - Receive updates in Mattermost from other systems via :doc:`Incoming Webhooks `. - Send data out of Mattermost to external endpoints via :doc:`Outgoing Webhooks ` based on channel activity. -- Build rich, interactive posts with buttons, menus, images, and layouts using :doc:`MM Blocks `—the recommended alternative to legacy `message attachments `_. +- Create rich, interactive posts with text, images, buttons, and menus using `MM Blocks `_—the recommended alternative to legacy `message attachments `_. Because webhooks use lightweight HTTP POST requests with JSON payloads, they're easy to set up with virtually any tool or platform, whether you need quick notifications or deep integration with enterprise workflows. From 95461173dea6b8af1fd7be040fa3a27e45b87275 Mon Sep 17 00:00:00 2001 From: Daniel Espino Date: Fri, 26 Jun 2026 18:25:26 +0200 Subject: [PATCH 7/7] Address feedback and add limits related information --- .../extend-mattermost-with-integrations.rst | 7 ------- source/get-help/mm-blocks-troubleshooting.rst | 18 ++++++++++++++++++ 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst b/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst index ef98ca8cb17..f9ad3c9e2ef 100644 --- a/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst +++ b/source/end-user-guide/collaborate/extend-mattermost-with-integrations.rst @@ -26,13 +26,6 @@ Mattermost interoperability - :ref:`ServiceNow ` - :ref:`Zoom ` -Interact with integration messages ----------------------------------- - -Many integrations post rich, actionable content into channels—such as status updates with **Approve** or **Acknowledge** buttons, option menus, images, and grouped content. When you select a button or choose an option from a menu, Mattermost sends your selection to the integration. The integration may update the post in the channel or reply with a message visible only to you. - -If content does not render or respond as expected, see :doc:`Troubleshoot MM Blocks `. - .. tip:: - `Visit the Mattermost Marketplace `__ to find open source, community-supported integrations to common developer tools like `CircleCI `__, `Opsgenie `__, `PagerDuty Notifier `__; productivity tools like `Autolink `__, `ToDo `__, and `WelcomeBot `__; as well as social tools like `Memes `__ and `GIFs `__ that are freely available for use and customization. diff --git a/source/get-help/mm-blocks-troubleshooting.rst b/source/get-help/mm-blocks-troubleshooting.rst index 23f1bcc8867..434b93179a8 100644 --- a/source/get-help/mm-blocks-troubleshooting.rst +++ b/source/get-help/mm-blocks-troubleshooting.rst @@ -62,6 +62,24 @@ Collapsible sections or images look wrong 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 --------------------------