Sygnal reference Push Gateway for Matrix service

• full documentation
• source code
• support

Sygnal is a reference Push Gateway for Matrix, allowing Matrix application developers to make their custom Matrix application deliver push notifications (to Android , iOS ) via their own push gateway.

Who is it for?

Most Matrix users don’t need to install their own push gateway. As Sygnal’s Notes for application developers documentation says:

It is not feasible to allow end-users to configure their own Sygnal instance, because the Sygnal instance needs the appropriate FCM or APNs secrets that belong to the application.

However, if you’re developing your own application, be it from scratch or by forking on of the existing Matrix client applications , you may need a Sygnal push gateway. We can configure and host Sygnal for you, and you can then integrate it into your own Matrix application .

Configuration

You can use Sygnal to push notifications (via your custom Matrix application) to:

• Android (and others), via Firebase Cloud Messaging (previously Google Cloud Messaging)
• iOS , via Apple Push Notification service

For your Sygnal instance, you can enable one or both of these push modules depending on your needs.

Firebase Cloud Messaging (previously Google Cloud Messaging)

You can deliver push notifications to Android devices (and also to iOS, web, etc.) using Firebase Cloud Messaging . For iOS push notifications, you can also use Apple Push Notification service directly.

To obtain an API key:

• go to the Firebase Console
• create a new project
• go to All products -> Cloud Messaging (e.g. URL: https://console.firebase.google.com/project/<PROJECT NAME>/settings/cloudmessaging/)
• create an Android application and obtain the API key

Finally, send over your application ID (e.g. com.example.messenger) and this API key over to us, so we can configure your Sygnal instance.

Apple Push Notification service

You can deliver push notifications to iOS devices using the Apple Push Notification service .

For this, you will need to enroll into the Apple Developer Program .

The APNS module for Sygnal can be configured in 2 ways:

1. (Legacy) Certificate-based authentication: Uses a certificate file that Apple signs based on a Certificate Signing Request. Things you will need to send over to us:

• certfile: a .pem file containing the APNS certificate and unencrypted private key

2. (More recent) Token-based authentication.

• keyfile: the key file - a .p8 file
• key_id: a string like XF32BUG6NW
• team_id: a string like 42G2X6393F
• topic: a string like com.example - this is most commonly the ‘Bundle Identifier’ for your iOS application
• platform: a string, either production and sandbox - it determines whether the production or sandbox APNS environment is used. This is optional and defaults to production
• push_type: optional string, which determines what value to set for the apns-push-type header sent to APNs. Read more when to use push types and what values are available.

We recommend that you go with the newer Token-based authentication method, but you can choose either one.

For iOS, we can configure multiple APNs push instances with different push_type configuration (e.g. alert, voip, etc.)

Whichever method you choose, send over your application ID (e.g. com.example.messenger) and configuration (as documented above), so we can configure your Sygnal instance.

Integrating into your application

Our job ends with configuring Sygnal with the Firebase Cloud Messaging and Apple Push Notification service settings described above.

We will deploy your Sygnal instance at a URL like: https://sygnal.your-server.com.

You then need to continue and actually make use of your push gateway in your custom Matrix application.

Your Push Gateway may be used with your own Matrix server (the one we host for you) or with any other Matrix server accessed through your application - as long as people are using your application, they can use your push gateway wih any server they access through it.

For more details about integrating a push gateway into your custom Matrix application, see the applications documentation page in the Sygnal project.