---
title: "Mattermost Blocks"
description: "Mattermost Blocks are the canonical format for structured, interactive integration posts. Use props.mm_blocks for layout and controls, and props.mm_blocks_actions for server-side action dispatch."
sidebar_label: "Mattermost Blocks"
sidebar_position: 42
---

Mattermost Blocks are the structured post format for integration messages. An integration sends a block tree in `props.mm_blocks` to define layout, text, images, buttons, and menus, and registers action handlers in `props.mm_blocks_actions` so the server can dispatch clicks and menu selections back to the integration.

:::note[Feature flag]
Mattermost Blocks are controlled by the `MmBlocksEnabled` feature flag (enabled by default). When disabled, Mattermost Blocks payloads are not rendered and Mattermost Blocks action cookies are rejected.
:::

## How it works

An interactive Mattermost Blocks post has two parts:

1. **`props.mm_blocks`** — an array of block objects that define layout, text, images, buttons, and menus. A post may contain up to 100 blocks in total, counting nested blocks throughout the tree.
2. **`props.mm_blocks_actions`** — a map keyed by action ID. Each entry tells the server what to do when a user clicks a button, selects a menu option, or activates a [markdown action button](/developers/integrate/reference/markdown-actions).

When the post is stored, the server validates that every referenced action ID has a matching registry entry (and no unused entries remain). It then encrypts the action registry into an opaque cookie string that clients send back when dispatching actions.

## Example post payload

The following payload posts a message with text, a primary button, and a static select menu:

```json
{
  "channel_id": "qmd5oqtwoibz8cuzxzg5ekshgr",
  "message": "Deployment #42 finished.",
  "props": {
    "mm_blocks": [
      {
        "type": "text",
        "text": "Deployed `main` to **staging**. Choose a follow-up action:"
      },
      {
        "type": "container",
        "flow": "horizontal",
        "gap": "small",
        "content": [
          {
            "type": "button",
            "text": "View logs",
            "style": "primary",
            "action_id": "view_logs"
          },
          {
            "type": "button",
            "text": "Rollback",
            "style": "danger",
            "action_id": "rollback"
          },
          {
            "type": "static_select",
            "action_id": "next_step",
            "placeholder": "Select next step…",
            "options": [
              {"text": "Promote to production", "value": "promote"},
              {"text": "Run smoke tests", "value": "smoke"}
            ]
          }
        ]
      }
    ],
    "mm_blocks_actions": {
      "view_logs": {
        "type": "external",
        "url": "https://integration.example.com/actions/view-logs",
        "context": {"deployment_id": "42"}
      },
      "rollback": {
        "type": "external",
        "url": "https://integration.example.com/actions/rollback",
        "context": {"deployment_id": "42"}
      },
      "next_step": {
        "type": "external",
        "url": "https://integration.example.com/actions/next-step",
        "context": {"deployment_id": "42"}
      }
    }
  }
}
```

You can send this payload using the [create post REST API](https://api.mattermost.com/#operation/CreatePost), an [incoming webhook](/developers/integrate/webhooks/incoming), a [custom slash command](/developers/integrate/slash-commands/custom), or from a [plugin](/developers/integrate/plugins/components/server).

### Submit using an incoming webhook

```bash
curl -X POST $MM_URL/hooks/$WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Deployment #42 finished.",
    "props": {
      "mm_blocks": [
        {"type": "text", "text": "Deployed `main` to **staging**."},
        {
          "type": "button",
          "text": "View logs",
          "style": "primary",
          "action_id": "view_logs"
        }
      ],
      "mm_blocks_actions": {
        "view_logs": {
          "type": "external",
          "url": "https://integration.example.com/actions/view-logs",
          "context": {"deployment_id": "42"}
        }
      }
    }
  }'
```

For webhook payloads, place `mm_blocks` and `mm_blocks_actions` inside `props`. The top-level `attachments` array remains available for legacy integrations.

### Submit from a plugin

```golang
post := &model.Post{
    ChannelId: channelID,
    UserId:    p.botID,
    Message:   "Deployment #42 finished.",
    Props: model.StringInterface{
        "mm_blocks": []any{
            map[string]any{
                "type": "text",
                "text": "Deployed `main` to **staging**.",
            },
            map[string]any{
                "type":      "button",
                "text":      "View logs",
                "style":     "primary",
                "action_id": "view_logs",
            },
        },
        "mm_blocks_actions": map[string]any{
            "view_logs": map[string]any{
                "type":    "external",
                "url":     fmt.Sprintf("/plugins/%s/actions/view-logs", manifest.Id),
                "context": map[string]any{"deployment_id": "42"},
            },
        },
    },
}
_, err := p.API.CreatePost(post)
```

## Block types

Each element of `props.mm_blocks` is an object with a required `type` field. The supported block types are:

| Type | Purpose |
| --- | --- |
| [`text`](#text) | Markdown-formatted text |
| [`image`](#image) | Remote image with optional sizing and alignment |
| [`divider`](#divider) | Horizontal rule between blocks |
| [`button`](#button) | Interactive button |
| [`static_select`](#static-select) | Dropdown menu with static options or dynamic data sources |
| [`container`](#container) | Groups blocks with optional border, accent bar, background, and layout flow |
| [`collapsible`](#collapsible) | Expandable section with separate header and content block arrays |
| [`column_set`](#column-set-and-column) | Horizontal row of columns |
| [`column`](#column-set-and-column) | Column inside a `column_set` (not valid as a top-level block) |

Nested layout blocks (`container`, `collapsible`, `column_set`, and `column`) may nest up to 32 levels deep.

Malformed blocks are omitted at render time; valid sibling blocks still display.

### Text

```json
{
  "type": "text",
  "text": "Hello **from** Mattermost Blocks.",
  "is_subtle": false,
  "size": "default"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `text` | yes | Markdown-formatted content. Supports @mentions. All `text` and [button](#button) `text` fields in a post share a combined limit of 16,000 characters. |
| `is_subtle` | no | When `true`, renders in a muted color. Does not change font size. |
| `size` | no | Typography scale: `small` or `default`. Omitted is equivalent to `default`. |

### Image

```json
{
  "type": "image",
  "url": "https://example.com/logo.png",
  "alt_text": "Company logo",
  "title": "Logo",
  "size": "medium",
  "max_width": 400,
  "max_height": 300,
  "image_style": "default",
  "horizontal_alignment": "center"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `url` | yes | Image URL (GIF, JPEG, PNG, BMP, or SVG). |
| `alt_text` | no | Accessible description. |
| `title` | no | Plain-text tooltip shown on hover. |
| `size` | no | Preset sizing: `auto`, `xsmall`, `small`, `medium`, `large`, or `stretch`. Defaults to `stretch`. |
| `max_width` | no | Maximum width in pixels. |
| `max_height` | no | Maximum height in pixels. |
| `image_style` | no | `default` or `person` (avatar-style crop). |
| `horizontal_alignment` | no | `left`, `center`, or `right`. |

### Divider

```json
{"type": "divider"}
```

### Button

```json
{
  "type": "button",
  "text": "Approve",
  "action_id": "approve",
  "style": "primary",
  "tooltip": "Approve this change",
  "disabled": false,
  "query": {"ticket": "ISS-101"}
}
```

| Field | Required | Description |
| --- | --- | --- |
| `text` | yes | Button label. Supports Markdown. Counts toward the combined 16,000-character limit for [text](#text) and button blocks. |
| `action_id` | yes | Must match a key in `mm_blocks_actions`. |
| `style` | no | Semantic color: `default`, `primary`, `danger`, `good`, `success`, or `warning`. Hex colors such as `#2d81ff` are also accepted. |
| `tooltip` | no | Help text shown on hover. |
| `disabled` | no | When `true`, the button renders but cannot be clicked. |
| `query` | no | Static query parameters merged into the action URL when clicked. Up to 50 entries; each key may be up to 128 characters and each value up to 2048 characters. |

### Static select

```json
{
  "type": "static_select",
  "action_id": "pick_region",
  "placeholder": "Pick a region",
  "options": [
    {"text": "North", "value": "north"},
    {"text": "South", "value": "south"}
  ],
  "initial_option": "north",
  "disabled": false,
  "data_source": "channels"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `action_id` | yes | Must match a key in `mm_blocks_actions`. |
| `placeholder` | yes | Placeholder text for the menu. |
| `options` | depends on | Array of `{text, value}` pairs. Required unless `data_source` is set. |
| `initial_option` | no | Pre-selected option value. |
| `disabled` | no | When `true`, the menu renders but cannot be used. |
| `data_source` | no | Dynamic option source: `channels` or `users`. When set, `options` is optional. Users can only select public channels in their teams. |

When a user selects an option, the integration callback receives `selected_option` in the request `context` with the chosen value (or user/channel ID for dynamic data sources).

### Container

```json
{
  "type": "container",
  "content": [
    {"type": "text", "text": "Container title"},
    {"type": "divider"},
    {"type": "text", "text": "Body copy", "is_subtle": true, "size": "small"}
  ],
  "border": true,
  "accent_color": "primary",
  "background": "gray",
  "flow": "vertical",
  "gap": "small",
  "max_height": "medium"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `content` | yes | Array of nested blocks. |
| `border` | no | When `true`, draws a border around the container. |
| `accent_color` | no | Left accent bar color. Semantic values: `default`, `primary`, `good`, `warning`, or `danger`. CSS colors such as `#439FE0` are also accepted. |
| `background` | no | `none` (default) or `gray`. |
| `flow` | no | Child layout direction: `horizontal` or `vertical`. Defaults to `vertical`. |
| `gap` | no | Spacing between children: `none`, `small`, `medium`, `large`, or `xlarge`. Defaults to `none`. |
| `max_height` | no | Maximum height preset: `none`, `small`, `medium`, or `large`. Overflowing content scrolls inside the container. On mobile, users can open scrollable content in a dedicated full-screen view. |

### Collapsible

```json
{
  "type": "collapsible",
  "collapsed": false,
  "header": [
    {"type": "text", "text": "**Details**"}
  ],
  "content": [
    {"type": "text", "text": "Expanded content goes here."}
  ]
}
```

| Field | Required | Description |
| --- | --- | --- |
| `header` | yes | Blocks shown in the always-visible header row. |
| `content` | yes | Blocks shown when expanded. |
| `collapsed` | no | Initial collapsed state. Defaults to `false`. |

### Column set and column

```json
{
  "type": "column_set",
  "gap": "medium",
  "columns": [
    {
      "type": "column",
      "width": "stretch",
      "gap": "small",
      "items": [
        {"type": "text", "text": "Left column"}
      ]
    },
    {
      "type": "column",
      "width": "auto",
      "items": [
        {"type": "text", "text": "Right column"}
      ]
    }
  ]
}
```

`column` blocks are only valid inside a `column_set`. Each column has an `items` array of nested blocks.

## The `mm_blocks_actions` registry

The `mm_blocks_actions` post prop is a map keyed by action ID. Each entry describes how the server handles clicks on that action. The registry supports up to 50 action entries. Each action ID must match `[A-Za-z0-9_-]+`, may be up to 64 characters long, and is matched case-sensitively.

```json
{
  "mm_blocks_actions": {
    "<action_id>": {
      "type": "<action_type>",
      "url": "...",
      "context": { ... },
      "query": { ... }
    }
  }
}
```

| Field | Required | Description |
| --- | --- | --- |
| `type` | yes | Action type. See [Action types](#action-types) below. |
| `url` | depends on type | Target URL. Required for `external` and `openURL`. |
| `context` | no | Server-side context forwarded to the integration in the post-action request body. Not visible to clients. 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. Combined with any per-control `query` on the block — block values win on key conflict. Up to 50 entries; each key may be up to 128 characters and each value up to 2048 characters. |

Every action ID referenced by interactive content — Mattermost Blocks controls, markdown `mmaction://` links, Block Kit actions, or Adaptive Card actions — must have a matching registry entry. Unused registry entries are rejected at post-create time.

After the post is stored, clients receive an encrypted cookie string in place of the plaintext registry map.

### Action types

| Type | Behavior |
| --- | --- |
| `external` | The server sends an HTTP POST request to `url` with the standard post-action request body. The integration responds with a post-action response (update, ephemeral message, or navigation). Relative plugin paths such as `/plugins/myplugin/action` are supported. |
| `openURL` | Navigates the user without calling an integration. Relative paths (for example `/myteam/channels/off-topic`) navigate inside Mattermost. `http://` and `https://` URLs open in a new browser tab. Plugin paths are not allowed. |

Additional action types may be introduced in future releases. Entries with an unknown `type` value are rejected at post-create time.

## Action dispatch flow

```mermaid
sequenceDiagram
    participant Integration
    participant Server as Mattermost server
    participant Client
    Integration->>Server: Create post (mm_blocks + mm_blocks_actions)
    Server->>Server: Validate and encrypt action registry
    Server->>Client: Store and deliver post
    Client->>Client: Render blocks
    Client->>Server: POST /api/v4/posts/{id}/actions/{action_id}
    alt openURL
        Server->>Client: Navigate user
    else external
        Server->>Integration: POST action callback
        Integration->>Server: Post-action response
        Server->>Client: Update post / ephemeral message
    end
```

1. **Integration** creates a post with `mm_blocks` controls and matching `mm_blocks_actions` entries.
2. **Mattermost server** validates the pairing, encrypts the action registry, and stores the post.
3. **Client** renders the blocks. When the user clicks a button or selects a menu option, the client sends `POST /api/v4/posts/{post_id}/actions/{action_id}` with the encrypted cookie, optional `query`, `selected_option` (for menus), and `integration_format: "mm_block"`.
4. **Mattermost server** decrypts the cookie, resolves the action, merges query parameters, and either navigates (`openURL`) or POSTs to the integration endpoint (`external`).
5. **Integration** responds with a standard post-action response.

Action IDs in the URL path must match `[A-Za-z0-9_-]+`.

## Receiving action callbacks

When a user activates an `external` action, the Mattermost server sends an HTTP POST request to the configured `url`. The request body uses the same `PostActionIntegrationRequest` shape as [legacy message attachment](/developers/integrate/reference/message-attachments) buttons:

```json
{
  "user_id": "rd49ehbqyjytddasoownkuqrxe",
  "user_name": "alice",
  "channel_id": "j6j53p28k6urx15fpcgsr20psq",
  "channel_name": "town-square",
  "team_id": "5xxzt146eax4tul69409opqjlf",
  "team_domain": "myteam",
  "post_id": "gqrnh3675jfxzftnjyjfe4udeh",
  "trigger_id": "...",
  "type": "button",
  "context": {
    "deployment_id": "42",
    "selected_option": "promote"
  }
}
```

For static select menus, the selected value is added to `context.selected_option`.

Integrations respond with the same post-action response format used by attachment actions:

```json
{
  "update": {
    "message": "Updated!",
    "props": {
      "mm_blocks": [
        {"type": "text", "text": "Deployment promoted to production."}
      ]
    }
  },
  "ephemeral_text": "Promotion started.",
  "goto_location": "/myteam/channels/releases"
}
```

| Response field | Description |
| --- | --- |
| `update` | Replaces the original post message and props. Use `update.props.mm_blocks` to refresh the block layout. |
| `ephemeral_text` | Sends a private message visible only to the user who clicked. |
| `goto_location` | Navigates the user to a URL after the action completes. Supports in-app paths and external URLs. |
| `error` | Returns a custom error message displayed below the interactive content. |
| `skip_slack_parsing` | Set to `true` to bypass Slack-compatibility parsing of `ephemeral_text`. |

See [interactive messages](/developers/integrate/plugins/interactive-messages) for error handling details and `update.props` semantics.

## Legacy format compatibility

Mattermost continues to accept these older payload formats:

| Prop | Format | Notes |
| --- | --- | --- |
| `attachments` | Legacy [message attachments](/developers/integrate/reference/message-attachments) | Attachment `actions` arrays are translated into Mattermost Blocks buttons and selects at render time. |
| `blocks` | Slack Block Kit | Translated into Mattermost Blocks. Interactive Block Kit elements require matching `mm_blocks_actions` entries keyed by `action_id`. |
| `cards` | Microsoft Adaptive Cards | Translated into Mattermost Blocks. Interactive card actions require matching `mm_blocks_actions` entries keyed by action `id`. |

New integrations should prefer native `mm_blocks` for full control over layout and action registration.

## Security considerations

Mattermost Blocks follow the same security model as legacy interactive messages:

- Integration `url` values are invoked server-to-server, never directly from the client.
- `context` values are server-only and are not exposed to rendering clients.
- After create, the plaintext `mm_blocks_actions` map is replaced with an encrypted cookie.
- Action IDs are validated and must match referenced interactive content exactly.
- `openURL` actions reject plugin paths and path-traversal segments.

## See also

- [Troubleshoot Mattermost Blocks](/developers/integrate/reference/mm-blocks/troubleshooting) — common rendering, action, and mobile issues.
- [Interactive messages](/developers/integrate/plugins/interactive-messages) — overview, error handling, and legacy attachment actions.
- [Markdown action buttons](/developers/integrate/reference/markdown-actions) — inline `mmaction://` links using the same action registry.
- [Message attachments](/developers/integrate/reference/message-attachments) — legacy attachment format reference.
- [Incoming webhooks](/developers/integrate/webhooks/incoming) — submitting posts via webhooks.
- [REST API: create post](https://api.mattermost.com/#operation/CreatePost)