MM Blocks Documentation

site/content/integrate/faq/_index.md

@@ -34,6 +34,8 @@ If there's no translation layer, Mattermost won't understand the data you're sen
 
 When "attachments" are mentioned in the integrations documentation, it refers to Slack's Message Attachments. 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.
 
+For new interactive content — buttons, menus, and structured layouts — use [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) instead of attachment `actions`. Legacy attachments remain supported and are translated into MM Blocks at render time.
+
 We currently don't support the ability to attach files to a post made by an integration.
 
 ### Where can I find existing integrations?

site/content/integrate/plugins/interactive-messages/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "Interactive messages"
 heading: "Interactive messages"
-description: "Mattermost supports interactive message buttons and menus for incoming and outgoing webhooks, custom slash commands, and plugins via actions. They help make your integrations richer by completing common tasks inside Mattermost conversations, increasing user engagement and productivity."
+description: "Mattermost supports interactive message buttons and menus through MM Blocks, markdown action buttons, and legacy message attachments. They help make your integrations richer by completing common tasks inside Mattermost conversations, increasing user engagement and productivity."
 weight: 80
 aliases:
   - /integrate/admin-guide/admin-interactive-messages/
@@ -21,15 +21,27 @@ To try it out, you can use this {{< newtabref href="https://github.com/matterpol
 
 ![image](poll.png)
 
+## MM Blocks (recommended)
+
+[MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) are the recommended way to build interactive integration posts. Send a block tree in `props.mm_blocks` for layout, text, images, buttons, and menus, and register action handlers in `props.mm_blocks_actions`.
+
+See [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) for the full block schema, action types, validation limits, and examples.
+
 ## Markdown action buttons
 
-In addition to message-attachment buttons and menus, you can embed interactive affordances directly in a post's markdown body using `mmaction://` links backed by a `mm_blocks_actions` post prop. This is useful when a short message reads naturally with an inline "Approve" or "Reject" link and a full message attachment isn't warranted.
+Embed interactive affordances directly in a post's markdown body using `mmaction://` links backed by the same `mm_blocks_actions` registry. This is useful when a short message reads naturally with an inline "Approve" or "Reject" link.
 
 See [markdown action buttons]({{< ref "/integrate/reference/markdown-actions" >}}) for the full schema, limits, and end-to-end flow.
 
+## Legacy message attachment buttons and menus
+
+{{<note "Legacy format">}}
+The sections below describe interactive buttons and menus placed inside legacy [message attachments]({{< ref "/integrate/reference/message-attachments" >}}). Existing integrations continue to work — Mattermost translates attachment actions into MM Blocks at render time — but new integrations should use [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) directly.
+{{</note>}}
+
 ## Message buttons
 
-Add message buttons as `actions` in your integration {{< newtabref href="https://docs.mattermost.com/developer/message-attachments.html" title="message attachments" >}}.
+Add message buttons as `actions` in your integration [message attachments]({{< ref "/integrate/reference/message-attachments" >}}).
 
 The following payload gives an example that uses message buttons.
 
@@ -89,7 +101,7 @@ To return a custom error message to the user, your integration can respond with
 }
 ```
 
-The error message will be displayed to the user below the message attachment. If no custom error message is provided, a default "Action failed to execute" message is shown. This feature is available in Mattermost v10.5 and later.
+The error message will be displayed to the user below the interactive content. If no custom error message is provided, a default "Action failed to execute" message is shown. This feature is available in Mattermost v10.5 and later.
 
 ![image](interactive_message.gif)
 
@@ -301,7 +313,7 @@ Specify `users` as your action's `data_source` as follows:
 
 ### Parameters
 
-Below is a brief description of each parameter to help you customize the interactive message button and menu in Mattermost. For more information on message attachments, {{< newtabref href="https://docs.mattermost.com/developer/message-attachments.html" title="see our documentation" >}}.
+Below is a brief description of each parameter to help you customize legacy attachment interactive buttons and menus in Mattermost. For new integrations, see [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}). For more information on message attachments, see [message attachments]({{< ref "/integrate/reference/message-attachments" >}}).
 
 **ID**<br/>
 A per post unique identifier.
@@ -406,7 +418,7 @@ In most cases, your integration will do one or both of these things:
 
 ## Error handling
 
-When an action button integration fails, Mattermost automatically displays an error message to the user below the message attachment. This provides immediate feedback when button actions don't work as expected.
+When an action button integration fails, Mattermost automatically displays an error message to the user below the interactive content. This provides immediate feedback when button actions don't work as expected.
 
 ![image](action-button-error.png)
 
@@ -476,7 +488,7 @@ It is likely for one of three reasons:
 
 ### How do I manage properties of an interactive message?
 
-Use `update.Props` in the following ways to manage properties (`Props`) of an interactive message after a user performs an action via an interactive button or menu:
+Use `update.Props` in the following ways to manage properties (`Props`) of an interactive message after a user performs an action via an interactive button or menu. When using MM Blocks, include updated `mm_blocks` and `mm_blocks_actions` in `update.props` as needed:
 
  - `update.Props == nil` - Do not update `Props` field.
  - `update.Props == {}` - Clear all properties, except the username and icon of the original message, as well as whether the message was pinned to channel or contained emoji reactions.

site/content/integrate/reference/markdown-actions/_index.md

@@ -3,10 +3,11 @@ title: "Markdown action buttons"
 heading: "Use markdown action buttons"
 description: "Markdown action buttons let an integration turn an inline post-markdown link into an action affordance. Clicking the link dispatches a post action to the integration's endpoint instead of navigating away, expanding interactivity beyond message attachments."
 weight: 45
+mermaid: true
 ---
 
-{{<note "Part of a broader framework">}}
-Markdown action buttons are one binding surface in a broader Interactive Messages framework under active development. Additional binding surfaces and action types are planned for future iterations.
+{{<note "Part of the Interactive Messages framework">}}
+Markdown action buttons are one binding surface in the Interactive Messages framework alongside [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}). All surfaces share the same `mm_blocks_actions` action registry.
 {{</note>}}
 
 Use markdown action buttons to add inline, in-text affordances to a post — without using a message attachment. They're useful when:
@@ -15,7 +16,7 @@ Use markdown action buttons to add inline, in-text affordances to a post — wit
 - An integration wants to mix narrative text and action affordances in the same post body.
 - The visual weight of a full message attachment isn't warranted.
 
-For attachment-style buttons and menus, see [interactive messages]({{< ref "/integrate/plugins/interactive-messages" >}}).
+For block-style buttons and menus, see [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}). For legacy attachment actions, see [interactive messages]({{< ref "/integrate/plugins/interactive-messages" >}}).
 
 ## How it works
 
@@ -137,14 +138,14 @@ Plugin updates to `mm_blocks_actions` via `UpdatePost` are accepted only when th
 The link text rendered as the button label.
 
 **`<action_id>`**<br/>
-The host portion of the URL. Must match a key in `props.mm_blocks_actions`. Must be alphanumeric (`[A-Za-z0-9]+`), matched case-sensitively.
+The host portion of the URL. Must match a key in `props.mm_blocks_actions`. Must contain only letters, numbers, underscores, or hyphens (`[A-Za-z0-9_-]+`), matched case-sensitively, and may be up to 64 characters long.
 
 **`<query_string>`** (optional)<br/>
-`key=value` pairs that are forwarded with the dispatched action and merged into the target URL's query string by the server. Link-supplied values override registry-supplied values on key conflict.
+`key=value` pairs that are forwarded with the dispatched action and merged into the target URL's query string by the server. Link-supplied values override registry-supplied values on key conflict. Up to 50 entries; each key may be up to 128 characters and each value up to 2048 characters.
 
 ## The `mm_blocks_actions` registry
 
-The `mm_blocks_actions` post prop is a map keyed by action ID. Each entry describes how the server should handle clicks on that action.
+The `mm_blocks_actions` post prop is a map keyed by action ID. Each entry describes how the server should handle clicks on that action. The registry supports up to 50 action entries.
 
 ```json
 {
@@ -163,8 +164,8 @@ The `mm_blocks_actions` post prop is a map keyed by action ID. Each entry descri
 | --- | --- | --- |
 | `type` | yes | Action type. See [Action types](#action-types) below. |
 | `url` | depends on type | Target URL for the integration's callback endpoint. Required for `external`. |
-| `context` | no | Object of server-side context values forwarded to the integration in the post-action request body. Not visible to the client. |
-| `query` | no | Static `string -> string` map merged into the target URL's query string by the server. Combined with any query parameters supplied in the `mmaction://` link — link values win on key conflict. |
+| `context` | no | Object of server-side context values forwarded to the integration in the post-action request body. Not visible to the client. Up to 50 entries; each key may be up to 128 characters. |
+| `query` | no | Static `string -> string` map merged into the target URL's query string by the server. Combined with any query parameters supplied in the `mmaction://` link — link values win on key conflict. Up to 50 entries; each key may be up to 128 characters and each value up to 2048 characters. |
 
 ### Action types
 
@@ -178,6 +179,22 @@ Additional action types may be introduced as the broader Interactive Messages fr
 
 The diagram below describes the lifecycle of a single click on a markdown action button.
 
+{{< mermaid >}}
+sequenceDiagram
+    participant Integration
+    participant Server as Mattermost server
+    participant Client
+    Integration->>Server: Create post (mmaction link + mm_blocks_actions)
+    Server->>Server: Validate post and store action registry
+    Server->>Client: Deliver post
+    Client->>Client: Render link as button
+    Client->>Server: POST /api/v4/posts/{id}/actions/{action_id}
+    Server->>Server: Merge query parameters into action URL
+    Server->>Integration: POST action callback
+    Integration->>Server: Post-action response
+    Server->>Client: Update post / ephemeral message
+{{</ mermaid >}}
+
 1. **Integration** creates a post with an `mmaction://<id>` link and a matching `mm_blocks_actions[<id>]` entry.
 2. **Mattermost server** validates the post (`mm_blocks_actions` schema and limits) and stores it.
 3. **Client** renders the link as a button. Clicking it dispatches `POST /api/v4/posts/{post_id}/actions/{action_id}` with the link's query string in the request body.
@@ -186,28 +203,15 @@ The diagram below describes the lifecycle of a single click on a markdown action
 
 ## Receiving action callbacks
 
-When a user clicks a markdown action button, the Mattermost server sends an HTTP POST request to the `url` configured in the matching `mm_blocks_actions` entry. The request body follows the same `PostActionIntegrationRequest` shape used by [message attachment]({{< ref "/integrate/reference/message-attachments" >}}) buttons — the integration responds with the same post-action response format.
-
-## Validation limits
-
-Posts that exceed any of the following limits are rejected at create or update time.
-
-| Limit | Value |
-| --- | --- |
-| Maximum entries in `mm_blocks_actions` | 50 |
-| Maximum length of an action ID (map key) | 64 characters |
-| Action ID character set | `[A-Za-z0-9]+` |
-| Maximum entries in `query` (link or registry) | 50 |
-| Maximum length of a query key | 128 characters |
-| Maximum length of a query value | 2048 characters |
+When a user clicks a markdown action button, the Mattermost server sends an HTTP POST request to the `url` configured in the matching `mm_blocks_actions` entry. The request body follows the same `PostActionIntegrationRequest` shape used by [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) and legacy [message attachment]({{< ref "/integrate/reference/message-attachments" >}}) buttons — the integration responds with the same post-action response format.
 
 ## Error reference
 
 The following error IDs may be returned by the post-action and post-create APIs when processing markdown action requests.
 
 | Error ID | Cause |
 | --- | --- |
-| `api.post.do_action.query.app_error` | The query parameters supplied with the action click exceeded one of the limits above. |
+| `api.post.do_action.query.app_error` | The query parameters supplied with the action click exceeded one of the limits described in [Link syntax](#link-syntax) or [The `mm_blocks_actions` registry](#the-mm_blocks_actions-registry). |
 | `api.post.do_action.merge_query.app_error` | The server could not merge the supplied query parameters into the action's target URL — typically because the URL is malformed. |
 
 ## Security considerations
@@ -216,12 +220,13 @@ Markdown action buttons follow the same security model as message attachment act
 
 - The action `url` is invoked server-to-server, never directly from the client.
 - `context` values are server-only and are not exposed to the rendering client.
-- Action IDs are validated as alphanumeric strings and matched case-sensitively.
+- Action IDs must match the pattern `[A-Za-z0-9_-]+` — alphanumerics, underscore, and hyphen — and are matched case-sensitively.
 - Action entries with malformed or unknown `type` values are rejected at post-create time and never reach the click-dispatch path.
 
 ## See also
 
-- [Interactive messages]({{< ref "/integrate/plugins/interactive-messages" >}}) — message-attachment buttons and menus.
+- [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) — block-based buttons, menus, and layout.
+- [Interactive messages]({{< ref "/integrate/plugins/interactive-messages" >}}) — overview and legacy attachment actions.
 - [Message attachments]({{< ref "/integrate/reference/message-attachments" >}}) — broader message format reference.
 - [Incoming webhooks]({{< ref "/integrate/webhooks/incoming" >}}) — submitting posts via webhooks.
 - {{< newtabref href="https://api.mattermost.com/#operation/CreatePost" title="REST API: create post" >}}

site/content/integrate/reference/message-attachments/_index.md

@@ -9,7 +9,11 @@ aliases:
 
 For additional formatting options, and for compatibility with Slack non-markdown integrations, an `attachments` array can be sent by integrations and rendered by Mattermost.
 
-You can also add interactive message buttons as part of attachments. They help make your integrations richer by completing common tasks inside Mattermost conversations, increasing user engagement and productivity. For more information, see [documentation]({{< ref "/integrate/plugins/interactive-messages" >}}).
+{{<note "Legacy interactive content">}}
+For new integrations, prefer [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}) over attachment `actions` for buttons and menus. Legacy attachments remain fully supported — Mattermost translates them into MM Blocks at render time — but native MM Blocks give you more layout control and a unified action registry in `props.mm_blocks_actions`.
+{{</note>}}
+
+You can also add interactive message buttons as part of attachments. They help make your integrations richer by completing common tasks inside Mattermost conversations, increasing user engagement and productivity. For more information, see [interactive messages]({{< ref "/integrate/plugins/interactive-messages" >}}) and [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}).
 
 ## Attachment options
 
@@ -139,7 +143,9 @@ And here is how it renders in Mattermost:
 
 Yes, you can use the {{< newtabref href="https://api.mattermost.com/#operation/CreatePost" title="create post RESTful API" >}}.
 
-You need to add an `attachments` key to the post’s `props` JSON field. The value is an array of message attachments you want attached to the post. See below for an example curl command.
+You need to add an `attachments` key to the post's `props` JSON field. The value is an array of message attachments you want attached to the post. See below for an example curl command.
+
+For new interactive content, prefer `props.mm_blocks` and `props.mm_blocks_actions` instead. See [MM Blocks]({{< ref "/integrate/reference/mm-blocks" >}}).
 
 `curl -i -X POST -H 'Content-Type: application/json' -d '{"channel_id":"qmd5oqtwoibz8cuzxzg5ekshgr", "message":"Test message #testing", "props":{"attachments": [{"pretext": "This is the attachment pretext.","text": "This is the attachment text."}]}}' https://{your-mattermost-site}/api/v4/posts`