Skip to content

README.md

Latest commit

 

History

History
286 lines (233 loc) · 8.76 KB

README.md

File metadata and controls

286 lines (233 loc) · 8.76 KB

Mattermost Notification Component for Home Assistant

Validate HACS

This Home Assistant custom component lets you send notification to Mattermost servers. You can send simple or rich messages and attachments.

Features

  • Text Notifications: Send formatted text notifications to Mattermost channels
  • Attachments: Upload and share local or remote images/files with messages
  • Multi-Channel Support: Send notifications to multiple channels simultaneously
  • Token Authentication: Uses both bot tokens and personal access tokens (PATs [personal access tokens] are required for Agent-style bots)

Screenshots

Weather Alert

Customized Plex Alert

(Plex example uses custom author fields)

Requirements

  • A Mattermost server running 11.x
  • A token (bot or personal) with appropriate (post:all or post:#channel) permissions

Setup

  1. Create a Bot Account in Mattermost

    • Go to your Mattermost server
    • Navigate to System Console → Integrations → Bot Accounts
    • Create a new bot account (e.g., "Home Assistant Bot")
    • Note the bot access token generated (note: NOT the token ID)

  2. Install the Component

    • Install this component from HACS
    • Restart Home Assistant

  3. Configure via UI:

    • Go to Configuration → Integrations
    • Add "Mattermost" integration
    • Provide:
      • Server URL (e.g., https://chat.company.com or 192.168.1.100:8065)
      • Token (from step 1)
      • Default Channel (e.g., #general or notifications)

    Note: For the server URL, you can provide either a full URL like https://chat.company.com or just the hostname/IP like 192.168.1.100:8065 (HTTPS will be assumed).

Usage

Basic Text Notification

action: notify.mattermost
data:
  message: "Hello from Home Assistant!"
  target: "general"

Message with Title

action: notify.mattermost
data:
  title: "System Alert"
  message: "Motion detected in living room"
  target: "alerts"

Send to Multiple Channels

action: notify.mattermost
data:
  message: "System status update"
  target:
    - "#general"
    - "#alerts"
    - "#notifications"

Send Local File

action: notify.mattermost
data:
  message: "Security camera snapshot"
  target: "security"
  data:
    file:
      path: "/config/www/camera_snapshot.jpg"

Send Remote File

action: notify.mattermost
data:
  message: "Weather radar image"
  target: "weather"
  data:
    file:
      url: "https://example.com/radar.png"
      username: "optional_username"  # if authentication required
      password: "optional_password"

Rich Message Attachments

action: notify.mattermost
data:
  message: "System Status Report"
  target: "#monitoring"
  data:
    attachments:
      - fallback: "System Status: All systems operational"
        color: "#36a64f"
        # author_name and author_icon are automatically added by default
        # You can override them by specifying different values:
        # author_name: "Custom Name"
        # author_icon: "https://example.com/custom-icon.png"
        title: "Daily Status Report"
        title_link: "https://your-ha-instance.com"
        text: "All systems are running normally"
        fields:
          - title: "CPU Usage"
            value: "15%"
            short: true
          - title: "Memory Usage"
            value: "45%"
            short: true
          - title: "Disk Space"
            value: "82% used"
            short: false
        image_url: "https://cdn-icons-png.flaticon.com/512/1114/1114045.png"
        footer: "Generated by Home Assistant"
        footer_icon: "https://cdn-icons-png.flaticon.com/512/1114/1114045.png"

Configuration Parameters

Notification Data Options

File Attachments

  • file.path: Local file path (must be in allowed directories)
  • file.url: Remote file URL
  • file.username: Optional username for authenticated URLs
  • file.password: Optional password for authenticated URLs

Message Attachments

Rich formatting following Mattermost's attachment API.

Note: The integration automatically adds author_name: "Home Assistant" and author_icon: "https://www.home-assistant.io/images/favicon-192x192-full.png" to all attachments unless you explicitly specify different values.

  • fallback: Plain text fallback for notifications (note: this is what will show up in a Mattermost push notification, so make sure you populate it if you use those)
  • color: Hex color for attachment border (e.g., "#ff0000")
  • pretext: Text shown above attachment
  • author_name: Author name (defaults to "Home Assistant")
  • author_link: URL for author name link (defaults to nothing)
  • author_icon: 16x16px icon for author (defaults to Home Assistant favicon)
  • title: Attachment title
  • title_link: URL for title link
  • text: Main attachment text (supports Markdown)
  • fields: Array of field objects with title, value, short properties
  • image_url: URL to image (displayed full-size)
  • thumb_url: URL to thumbnail (75x75px)
  • footer: Footer text
  • footer_icon: 16x16px footer icon

Automation Examples

Motion Detection Alert

automation:
  - alias: "Motion Alert"
    trigger:
      platform: state
      entity_id: binary_sensor.motion_sensor
      to: "on"
    action:
      service: notify.mattermost
      data:
        title: "🚨 Motion Detected"
        message: "Motion detected in {{ trigger.to_state.attributes.friendly_name }}"
        target: "security"
        data:
          attachments:
            - color: "#ff9900"
              author_name: "Home Assistant Security"
              fields:
                - title: "Location"
                  value: "{{ trigger.to_state.attributes.friendly_name }}"
                  short: true
                - title: "Time"
                  value: "{{ now().strftime('%Y-%m-%d %H:%M:%S') }}"
                  short: true

System Status with Image

automation:
  - alias: "Daily Status Report"
    trigger:
      platform: time
      at: "08:00:00"
    action:
      - service: camera.snapshot
        target:
          entity_id: camera.front_door
        data:
          filename: "/config/www/daily_snapshot.jpg"
      - service: notify.mattermost
        data:
          title: "Daily Home Status"
          message: "Good morning! Here's your daily status report."
          target: "family"
          data:
            file:
              path: "/config/www/daily_snapshot.jpg"
            attachments:
              - color: "#36a64f"
                author_name: "Home Assistant"
                title: "System Status"
                text: "All systems operational"
                fields:
                  - title: "Temperature"
                    value: "{{ states('sensor.temperature') }}°C"
                    short: true
                  - title: "Humidity"
                    value: "{{ states('sensor.humidity') }}%"
                    short: true

Troubleshooting

Common Issues

  1. "Invalid authentication" error

    • Verify your bot token is correct
    • Ensure the bot has permission to post in channels
    • Check that the Mattermost server URL is accessible from the Home Assistant machine
    • If you recently deleted and recreated this integration, restart Home Assistant to clear cached data

  2. "Could not find channel" error

    • Verify the channel name is correct (without #)
    • Ensure the bot has access to the target channel
    • Check that the channel exists

  3. File upload failures

    • Verify file paths are in Home Assistant's allowed directories
    • Check file permissions
    • Ensure file size limits aren't exceeded
    • For remote files, verify URLs are accessible and allowed

  4. Connection timeouts

    • Check network connectivity to Mattermost server
    • Verify server SSL certificate if using HTTPS
    • Consider increasing timeout values if on slow network

Debugging

Enable debug logging in configuration.yaml:

logger:
  logs:
    custom_components.mattermost: debug

Security Considerations

These are all brought to you by Claude but are generally pretty smart...

  • Store bot tokens securely using Home Assistant's secrets
  • Use HTTPS for Mattermost server connections
  • Limit bot permissions to only necessary channels
  • Regularly rotate bot tokens
  • Be cautious with file path permissions

Contributing

Contributions welcome! Please submit issues and pull requests on the project repository. I am a total newbie to Mattermost so I may have missed opportunities, let me know.