Matrix Chat for Home Assistant (custom component, media + optional E2EE gateway)

Share your Projects! Custom Integrations
1

Hi all,

I open-sourced a Home Assistant custom integration for Matrix messaging.

GitHub:

What it supports

  • Send messages to Matrix users and rooms.
  • Send media (image/video/file) with Element X compatible payloads.
  • Reply, edit, and reaction support.
  • notify.matrix_chat notify platform.
  • Optional encrypted gateway for E2EE rooms and encrypted DMs.
  • Inbound webhook events for automations.
  • Optional command dispatch (!ha) with strict allowlists.
  • Outbound retry queue and manual flush tools.
  • Room/user helper services (resolve_target, list_rooms, join_room, invite_user, ensure_dm, ensure_room_encrypted).

Installation (quick)

  1. Copy custom_components/matrix_chat to /config/custom_components/matrix_chat
  2. Restart Home Assistant
  3. Add integration: Settings -> Devices & Services -> Add Integration -> Matrix Chat

Minimal config example

matrix_chat:
  homeserver: "https://matrix.example.org"
  user_id: "@ha_bot:matrix.example.org"
  access_token: !secret matrix_access_token
  verify_ssl: true
  dm_encrypted: true

Service examples

Send text:

service: matrix_chat.send_message
data:
  target: "@user:matrix.example.org"
  message: "Home Assistant event: motion detected."

Send image:

service: matrix_chat.send_media
data:
  target: "!roomid:matrix.example.org"
  file_path: "/config/www/camera/snapshot.jpg"
  message: "Camera snapshot"

Send video:

service: matrix_chat.send_media
data:
  target: "!roomid:matrix.example.org"
  file_path: "/config/www/camera/clip.mp4"
  message: "Camera clip"
  auto_convert: true

Notify platform:

service: notify.matrix_chat
data:
  target:
    - "!roomid:matrix.example.org"
  message: "System check: OK"

Optional encrypted gateway

cd encrypted_gateway
cp .env.example .env
mkdir -p data/store
docker compose up -d --build

Documentation

  • README
  • docs/HOWTO.md
  • docs/DEVELOPER_GUIDE.md
  • docs/OPERATIONS_AND_LESSONS.md
  • wiki/ pages for onboarding, troubleshooting, and deep-dive details

Feedback and issues are welcome.