Mattermost Notification Component for Home Assistant

    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

      (Plex example uses custom author fields)  

Requirements

 

• A Mattermost server
• 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"

 

High-Priority Notification

 

action: notify.mattermost
data:
  message: "Immediate attention required for a critical system alert."
  target: "alerts"
  data:
    important:
      message: "System breach detected! Immediate attention required."
      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"

 

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.