pushmatrix

Simple selfhosted REST API for sending end to end encrypted push notifications over Matrix protocol, build with matrix-nio.

It allows to send encrypted messages with simple HTTP request, that you can receive in any Matrix client, like Element

curl -X POST 127.0.0.1:8571/message \
   -H 'Content-Type: application/json' \
   -d '{"message":"Low disk space - 1 GB", "title":"system"}'

Usage

Start server

docker run -d \
	--name pushmatrix \
	-p 8571:8571 \
	-e USER_ID="@username:matrix.org" \
	-e PASSWORD="password" \
	-e RECEIPIENTS="@user1:matrix.org @user2:matrix.org @user3:matrix.org" \
	-e ROOM_NAME="pushmatrix" \
	-e APP_TOKEN="QOL4OO73EC1DEXE5A2N4" \
	bonukai/pushmatrix

or with docker compse

# docker-compose.yaml
version: "3.7"
services:
  pushmatrix:
    container_name: pushmatrix
    image: bonukai/pushmatrix
      ports:
        - 8571:8571
      environment:
        USER_ID: "@username:matrix.org"
        PASSWORD: "password"
        RECEIPIENTS: "@user1:matrix.org @user2:matrix.org @user3:matrix.org"
        ROOM_NAME: "pushmatrix"
        APP_TOKEN: "QOL4OO73EC1DEXE5A2N4"

docker-compose up -d

If your homeserver supports registration without email adress and captcha, then you can receive notifications from different users for every title.

docker run -d \
	--name pushmatrix \
	-p 8571:8571 \
	-v ./avatars:/avatars:ro \
	-e USER_ID="@username:matrix.org" \
	-e PASSWORD="password" \
	-e RECEIPIENTS="@user1:matrix.org @user2:matrix.org @user3:matrix.org" \
	-e ROOM_NAME="pushmatrix" \
	-e APP_TOKEN="QOL4OO73EC1DEXE5A2N4" \
	-e NEW_USER_FOR_TITLE="yes" \
	bonukai/pushmatrix

If your server doesn't support registration of new users, but you have access to the command line, you can still use this feature. Calculate the internal user name for the topics you plan to use. In this example for the topic doorbell:

echo -n "doorbell" | base64 
ZG9vcmJlbGw=

The internal username for doorbell will be pushmatrix_ZG9vcmJlbGw=. You can create this user with the same password that you use for the general pushmatrix user. For Synapse the command looks like this:

register_new_matrix_user -u pushmatrix_ZG9vcmJlbGw= -p password -c /data/homeserver.yaml https://matrix.example.org

When you use the topic for the first time, pushmatrix will set a more user-friendly displayname for that user - and also an avatar image if you put an appropriately named image into the avatar/ folder.

Authentication

Access to the API can be limited by providing APP_TOKEN environment variable

API

POST /message

Data constraints

{
  "title": "[title]",
  "messgage": "[message]",
  "token": "[optional app token]"
}

Data example

{
  "title": "System",
  "messgage": "Low disk space",
  "token": "QOL4OO73EC1DEXE5A2N4"
}

Success Response

Code : 200 OK

Content example

Ok

Web interface

There is avalible simple web interface for sending messages