Skip to main content

Understanding Push Notifications

To best understand how push notifications are setup in Matrix, a good place to start is with the diagram below from the Push Gateway API.

                                   +--------------------+  +-------------------+
                  Matrix HTTP      |                    |  |                   |
             Notification Protocol |   App Developer    |  |   Device Vendor   |
                                   |                    |  |                   |
           +-------------------+   | +----------------+ |  | +---------------+ |
           |                   |   | |                | |  | |               | |
           | Matrix homeserver +----->  Push Gateway  +------> Push Provider | |
           |                   |   | |                | |  | |               | |
           +-^-----------------+   | +----------------+ |  | +----+----------+ |
             |                     |                    |  |      |            |
    Matrix   |                     |                    |  |      |            |
 Client/Server API  +              |                    |  |      |            |
             |      |              +--------------------+  +-------------------+
             |   +--+-+                                           |
             |   |    <-------------------------------------------+
             +---+    |
                 |    |          Provider Push Protocol
                 +----+

         Mobile Device or Client

The process starts when a user installs a Matrix client, for example on an iOS device or Android device, and signs in. The client is configured with the push gateway location (URL) and also acquires a push key to identify itself from its push provider, Apple Push Notification (APN) service or Firebase Cloud Messaging (FCM). The client then registers a pusher on the users' homeserver providing the URL, push key etc.

On the Matrix Homeserver (for instance, Synapse), a pusher is registered for a user. The pusher information details1:

  • app_display_name: A string that will allow the user to identify what application owns this pusher.
  • app_id: This is a reverse-DNS style identifier for the application. Max length, 64 chars.
  • url: The URL to use to send notifications to the push gateway.
  • device_display_name: A string that will allow the user to identify what device owns this pusher.
  • pushkey: This is a unique identifier for this pusher. (Acquired from APN / FCM)

1 See pushers/set and pushers for more information

When a notification is received the homeserver sends this information to the registered Push Gateway, i.e. Sygnal from the users' pushers. The push gateway is where you configure your App Types - APNS GCM. The push gateway, Sygnal in this instance, recieves the request and forwards it to the required notification service (APN or FCM) using the pushkey. If successful, the push gateway confirms the success to the homeserver.

You can find a good overview of the entire process on Sygnal's Notes for Application Developers.

What information the payload holds regarding the specific device?

Per the above payload example, a pusher contains a display name for the App (client), that app's reverse-DNS style identifier, a device name and finally the push key. The pushkey is the unique identifier of the pusher.

See an example of a set pusher from the Client-Server APIs Push Notifications section:

{
  "pushers": [
    {
      "app_display_name": "Appy McAppface",
      "app_id": "face.mcapp.appy.prod",
      "data": {
        "url": "https://example.com/_matrix/push/v1/notify"
      },
      "device_display_name": "Alice's Phone",
      "kind": "http",
      "lang": "en-US",
      "profile_tag": "xyz",
      "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A="
    }
  ]
}

How does e.g Apple APNS know that my device is suppose to get the push notice?

When the application on a user's device registers for push notifications, it acquires a pushkey from the push provider. So for iOS, the client will acquire this key from APN and use it when registering the pusher with synapse.

Does the payload hold any information about my device? E.g. IMEI etc?

Per the sample payload provided above, only a device_display_name and pushkey are included, as such it does not contain a devices' IMEI etc.

Back to top