Mattermost Rest Notifications for Home Assistant

This post details how to send notifications from Home Assistant to Mattermost. This uses Home Assistants RESTful command functionality to delivery messages to webhook defined in Mattermost.

The following needs to be added to your: configuration.yaml restart HA after.

rest_command:
  mattermost:
    url: 
    content_type: 'application/json'
    verify_ssl: true
    method: 'post'
    timeout: 20
    payload: >
      {
        {%- if card is defined -%}
          "props": {
            "card": "{{ card }}"
          },
        {%- endif -%}
        {%- if as_attachment is defined -%}
          "attachments": [
            {
              {%- if fallback is defined -%}
                "fallback": "{{ fallback }}",
              {%- endif -%}
              {%- if color is defined -%}
                "color": "{{ color }}",
              {%- endif -%}
              {%- if pretext is defined -%}
                "pretext": "{{ pretext }}",
              {%- endif -%}
              {%- if author_name is defined -%}
                "author_name": "{{ author_name }}",
              {%- endif -%}
              {%- if author_icon is defined -%}
                "author_icon": "{{ author_icon }}",
              {%- endif -%}
              {%- if author_link is defined -%}
                "author_link": "{{ author_link }}",
              {%- endif -%}
              {%- if title is defined -%}
                "title": "{{ title }}",
              {%- endif -%}
              {%- if title_link is defined -%}
                "title_link": "{{ title_link }}",
              {%- endif -%}
              {%- if image_url is defined -%}
                "image_url": "{{ image_url }}",
              {%- endif -%}
              {%- if message is defined -%}
                "text": "{{ message }}"
              {%- endif -%}
            }
          ],
        {%- endif -%}
        {%- if channel is defined -%}
          "channel": {{ channel }},
        {%- endif -%}
        {%- if username is defined -%}
          "username": {{ username }},
        {%- endif -%}
        {%- if as_attachment is not defined -%}
          "text": "{{ message }}"
        {%- else -%}
          "text": ""
        {%- endif -%}
      }

The webhook configuration will allow you to send:

• Plain text
• Plain text + info bubble
• Attachment (rich formatted text) – Note not to be confused with a file attachment; this is a rich formatting option.
• Attachment (rich formatted text) + info bubble

Supported parameters

The full list of support parameters include:

message: "A test message",
channel: "home",                                # only works if the webhook is not locked to a channel.
username: "Oddineers",                          # only works if you have allowed username overrides on webhooks.
card: "Example",
fallback: "Example",
pretext: "Example",
author_name: "Example",
author_icon: "Example",
author_link: "https://oddity.oddineers.co.uk",
title: "Example",
title_link: "https://oddity.oddineers.co.uk",
channel: "Example",
username: "Example",
as_attachment: "Example"

Testing with Home Assistant Developer Tools

Remember to properly escape any special characters in any payload values.

Examples payload using plain text

Simple plain text message.

action: rest_command.mattermost
data: {
  message: "This is a test message"
}

Examples payload using plain text and a info bubble card

Simple plain text message with a info bubble containing additional information; note that info bubbles are only visible on the desktop.

action: rest_command.mattermost
data: {
  message: "This is a test message",
  card: "More detail in a info bubble, \\n\\nDesktop only.",
}

Examples payload using and attachment

A rich formatted attachment message, features a left coloured border. Additional parameters are supported review list above.

action: rest_command.mattermost
data: {
  message: "This is a test message",
  color: "#FF8000",
  as_attachment: 1,
  pretext: "Pretext example...",
  title: "This is an example..."
}

Examples payload using and attachment and a info bubble card

A rich formatted attachment message with a info bubble, features a left coloured border. Additional parameters are supported review list above.

action: rest_command.mattermost
data: {
  message: "This is a test message",
  color: "#FF8000",
  as_attachment: 1,
  card: "More detail in a info bubble, \\n\\nDesktop only.",
  pretext: "Pretext example...",
  title: "This is an example..."
}

When using the as_attachment param the value can be anything; this changes the integration from posting a plain text message to use a attachment card. The message is used for options.

The examples below demonstrate how to use the RESTFul command; in Home Assistant you can use the the Developer Tools > Actions.

References:

• Mattermost – Webhooks
• Mattermost – Message Attachments
• Home Assistant – Templating