Sygnal is a reference Push Gateway for Matrix.
See https://spec.matrix.org/latest/push-gateway-api/#overview for a high level overview of how notifications work in Matrix.
The Matrix Specification describes the protocol that Matrix Home Servers use to send notifications to Push Gateways such as Sygnal.
Looking to contribute to Sygnal? See CONTRIBUTING.md
Sygnal is configured through a YAML configuration file. By default, this
configuration file is assumed to be named
sygnal.yaml and to be in the
working directory. To change this, set the
variable to the path to your configuration file. A sample configuration
file is provided in this repository; see
apps: section is where you set up different apps that
are to be handled. Each app should be given its own subsection, with the
key of that subsection being the app's
app_id. Keys in this section
take the form of the
app_id, as specified when setting up a Matrix
See the sample configuration for examples.
You can find a docker image for sygnal on DockerHub.
There are two supported App Types:
This sends push notifications to iOS apps via the Apple Push Notification Service (APNS).
The expected configuration depends on which kind of authentication you wish to use.
For certificate-based authentication, it expects:
certfileparameter to be a path relative to sygnal's working directory of a PEM file containing the APNS certificate and unencrypted private key.
For token-based authentication, it expects:
keyfileparameter to be a path relative to Sygnal's working directory of a p8 file
topicparameter, which is most commonly the 'Bundle Identifier' for your iOS application
For either type, it can accept:
platformparameter which determines whether the production or sandbox APNS environment is used. Valid values are 'production' or 'sandbox'. If not provided, 'production' is used.
push_typeparameter which determines what value for the
apns-push-typeheader is sent to APNs. If not provided, the header is not sent.
This sends messages via Google/Firebase Cloud Messaging (GCM/FCM)
and hence can be used to deliver notifications to Android apps. It
expects the 'api_key' parameter to contain the 'Server key',
which can be acquired from Firebase Console at:
Sygnal will, by default, automatically detect an
environment variable on start-up.
If one is present, it will be used for outbound traffic to APNs and GCM/FCM.
Currently only HTTP proxies with the CONNECT method are supported. (Both APNs and FCM use HTTPS traffic which is tunnelled in a CONNECT tunnel.)
If you wish, you can instead configure a HTTP CONNECT proxy in
The following parameters can be specified in the
dictionary which is given when configuring the pusher via
default_payload: a dictionary which defines the basic payload to
be sent to the notification service. Sygnal will merge information
specific to the push event into this dictionary. If unset, the empty
dictionary is used.
This can be useful for clients to specify default push payload content. For instance, iOS clients will have freedom to use silent/mutable notifications and be able to set some default alert/sound/badge fields.
With default configuration file name of
python -m sygnal.sygnal
With custom configuration file name:
SYGNAL_CONF=/path/to/custom_sygnal.conf python -m sygnal.sygnal
Python 3.7 or higher is required.
Sygnal's logging appends to files but does not use a rotating logger.
The recommended configuration is therefore to use
logrotate. The log
file will be automatically reopened if the log file changes, for example
More documentation for Sygnal is available in the