diff --git a/source/deployment-guide/mobile/mobile-troubleshooting.rst b/source/deployment-guide/mobile/mobile-troubleshooting.rst index ae79aadf1e9..8ace98a03df 100644 --- a/source/deployment-guide/mobile/mobile-troubleshooting.rst +++ b/source/deployment-guide/mobile/mobile-troubleshooting.rst @@ -166,3 +166,8 @@ If you did not receive a push notification when testing push notifications, use To conserve disk space, once your push notification issue is resolved, go to **System Console > Environment > Logging > File Log Level**, then select **ERROR** to switch your logging detail level from **DEBUG** to **Errors Only**. If push notifications are not being delivered on the mobile device, confirm that you're logged in to the **Native** mobile app session through **Profile > Security > View and Log Out of Active Sessions**. Otherwise, the ``DeviceId`` won't get registered in the ``Sessions`` table and notifications won't be delivered. + +Integration posts (MM Blocks) do not render or respond +------------------------------------------------------- + +If buttons, menus, or structured content from an integration post is missing or unresponsive on mobile, see the `MM Blocks reference `_ in the developer documentation. diff --git a/source/end-user-guide/access/client-availability.rst b/source/end-user-guide/access/client-availability.rst index 704036a3957..502ade34d82 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| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ +| `MM Blocks `_ [1]_ | Conditional | Conditional | Conditional | ++-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Message attachments `_ | |checkmark| | |checkmark| | |checkmark| | +-----------------------------------------------------------------------------------------------------------------+-------------+-------------+-----------------+ | `Message buttons `_ | |checkmark| | |checkmark| | |checkmark| | @@ -158,6 +160,8 @@ 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. + Authentication ~~~~~~~~~~~~~~ diff --git a/source/end-user-guide/messaging-collaboration.rst b/source/end-user-guide/messaging-collaboration.rst index 79b9f46ce37..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. +* :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/integrations-guide/faq.rst b/source/integrations-guide/faq.rst index c064d334c8a..04e46c47ca9 100644 --- a/source/integrations-guide/faq.rst +++ b/source/integrations-guide/faq.rst @@ -48,7 +48,18 @@ What are attachments? When "attachments" are mentioned in Mattermost integrations documentation, it refers to Slack's message attachments functionality. These "attachments" can be optionally added as an array in the data sent by an integration, and are used to customize the formatting of the message. -Mattermost doesn't currently support the ability to attach files to a post made via webhook. You can use the API to attach files to a message if needed. +Mattermost doesn't currently support the ability to attach files to a post made via webhook. You can use the API to attach files to a message if needed. + +What are MM Blocks? +-------------------- + +MM Blocks are Mattermost's structured format for rich, interactive integration posts. Integrations can extend messages with text, images, buttons, menus, collapsible sections, and different layout options. + +Starting in Mattermost v11.10, MM Blocks are the recommended replacement for `message attachments `_. They are the preferred way to create interactive messages for integrations such as :doc:`incoming webhooks `, plugins, and bot accounts. + +Legacy message attachments and other interactive message formats continue to work; clients translate them into the MM Blocks format at render time. We encourage new and updated integrations to use MM Blocks instead. + +For payload structure, block types, action handling, migration guidance, and troubleshooting, see the `MM Blocks reference `_ in the developer documentation. Where can I find existing integrations? --------------------------------------- diff --git a/source/integrations-guide/incoming-webhooks.rst b/source/integrations-guide/incoming-webhooks.rst index a201342dec7..226584da387 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 :ref:`What are MM Blocks? `. + Using incoming webhooks in Mattermost requires only basic setup. You generate a webhook URL using the Mattermost interface, then point another service to send data to that address. No coding is required if your external service triggering the events is able to send data via webhooks or HTTP POST requests, which most modern applications and platforms support. Setting this up usually involves pasting the Mattermost webhook URL into the service’s settings and selecting what type of events you want it to send. Example Use Cases @@ -107,7 +109,7 @@ The JSON payload can contain the following parameters: - Required - Description * - ``text`` - - Yes (if ``attachments`` is not set) + - Yes (if ``props.mm_blocks`` is not set) - :doc:`Markdown-formatted ` message. Use ``@``, ``@channel``, and ``@here`` for notifications. * - ``channel`` - No @@ -121,15 +123,12 @@ The JSON payload can contain the following parameters: * - ``icon_emoji`` - 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. * - ``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 `_ 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,8 +223,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. -- `Message Attachments `_: Present rich, structured summaries such as status, priority, fields, links, or images for faster triage and comprehension. (Slack‑compatible schema.) -- `Interactive Messages `_: Make notifications actionable with buttons or menus such as Acknowledge, Assign, or Escalate that enable an immediate user response without switching tools or context. +- `MM Blocks `_: Create structured, interactive posts with text, images, buttons, and menus. - `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..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. +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/outgoing-webhooks.rst b/source/integrations-guide/outgoing-webhooks.rst index 4a7784d4780..96850a7caf5 100644 --- a/source/integrations-guide/outgoing-webhooks.rst +++ b/source/integrations-guide/outgoing-webhooks.rst @@ -6,7 +6,7 @@ Outgoing Webhooks **Technical complexity:** :ref:`Low-code ` -Outgoing webhooks can be used to create rich, interactive experiences in Mattermost by letting external services respond with rich message attachments, such as structured fields, buttons, and menus. Additionally, these responses can trigger interactive dialog forms where users provide additional input directly in Mattermost, or interactive messages that update dynamically based on user actions. Together, these capabilities turn simple keyword triggers into powerful in-product workflows that streamline how teams interact with external systems, all with minimal coding required. +Outgoing webhooks can be used to create rich, interactive experiences in Mattermost by letting external services respond with `MM Blocks `_—structured content with buttons, menus, and other interactive elements. Additionally, these responses can trigger interactive dialog forms where users provide additional input directly in Mattermost. Together, these capabilities turn simple keyword triggers into powerful in-product workflows that streamline how teams interact with external systems, all with minimal coding required. Outgoing webhooks require no coding to configure on in Mattermost, however the external service that receives the HTTP POST request needs to process the data, and then format and send a respond with a message back to Mattermost. This usually requires light coding to parse the request and format a JSON response payload, though many :ref:`automation platforms ` handle this without writing custom code. @@ -23,11 +23,11 @@ When a user types ``bug`` in a channel, an outgoing webhook sends the message to **Knowledge base lookup** -A keyword like ``docs`` triggers an outgoing webhook that queries a documentation service and returns a rich interactive message with a list of suggested articles, each with clickable buttons or menus. Users can refine their search or open links without leaving Mattermost. +A keyword like ``docs`` triggers an outgoing webhook that queries a documentation service and returns a response with `MM Blocks `_ listing suggested articles, each with clickable buttons or menus. Users can refine their search or open links without leaving Mattermost. **Security incident enrichment** -Typing a keyword like ``ioc`` (indicator of compromise) in a security channel can trigger an outgoing webhook that queries a threat intelligence platform. The response can return a formatted message attachment with reputation scores, related incidents, and quick-action buttons for escalating, investigating, or dismissing the alert. +Typing a keyword like ``ioc`` (indicator of compromise) in a security channel can trigger an outgoing webhook that queries a threat intelligence platform. The response can return `MM Blocks `_ with reputation scores, related incidents, and quick-action buttons for escalating, investigating, or dismissing the alert. Create ------- @@ -143,19 +143,17 @@ The JSON response can contain the following parameters: * - Parameter - Description * - ``text`` - - (Required if ``attachments`` is not set) :doc:`Markdown-formatted ` message. + - (Required if ``props.mm_blocks`` is 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`` - Overrides the default username. Requires :ref:`Enable integrations to override usernames ` to be enabled. * - ``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. * - ``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 `_ for rich, interactive content. * - ``priority`` - Sets the priority of the message. See `message priorities `_. @@ -184,21 +182,20 @@ 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 `MM Blocks `_ 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. -- `Interactive Messages `_: Present next-step actions (Acknowledge, Assign, Escalate) as buttons/menus directly in your response—no context switching. +- `MM Blocks `_: Return structured, interactive content with text, buttons, and menus. - `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 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 396c763e92e..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 as interactive message attachments with links. \ No newline at end of file +A command like ``/docs search authentication`` queries your documentation system and returns a list of relevant articles rendered using `MM Blocks `_ with links. \ No newline at end of file