Mobile push notification service¶
Zulip’s iOS and Android mobile apps support receiving push notifications from Zulip servers to let users know when new messages have arrived. This is an important feature to having a great experience using the Zulip mobile apps.
For technical reasons (explained below), in order to deliver mobile push notifications in the app store versions of our mobile apps, you will need to register your Zulip server with the Zulip mobile push notification service. This service will forward push notifications generated by your server to the Zulip mobile app automatically.
How to sign up¶
Starting with Zulip 1.6 for both Android and iOS, Zulip servers support forwarding push notifications to a central push notification forwarding service. You can enable this for your Zulip server as follows:
PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'line in your
/etc/zulip/settings.pyfile (i.e. remove the
#at the start of the line), and restart your Zulip server. If you installed your Zulip server with a version older than 1.6, you’ll need to add the line (it won’t be there to uncomment).
If you’re running Zulip 1.8.1 or newer, you can run the registration command:
# As root: su zulip -c '/home/zulip/deployments/current/manage.py register_server' # Or as the zulip user, you can skip the `su zulip -c`: /home/zulip/deployments/current/manage.py register_server
This command will print the registration data it would send to the mobile push notifications service, ask you to accept the terms of service, and if you accept, register your server. If you have trouble, email email@example.com with the output of this command.
If you or your users have already set up the Zulip mobile app, you’ll each need to log out and log back in again in order to start getting push notifications.
Congratulations! You’ve successfully setup the service.
If you’d like to verify that everything is working, you can do the following. Please follow the instructions carefully:
- Configure mobile push notifications to always be sent (normally they’re only sent if you’re idle, which isn’t ideal for this sort of testing).
- On an Android device, download and login to the Zulip Android app. If you were already logged in before configuring the server, you’ll need to logout first, since the app only registers for push notifications on login.
- Hit the home button, so Zulip is running in the background, and then have another user send you a private message (By default, Zulip only sends push notifications for private messages sent by other users and messages mentioning you). A push notification should appear in the Android notification area.
Updating your server’s registration¶
Your server’s registration includes the server’s hostname and contact
email address (from
/etc/zulip/settings.py, aka the
manage.py register_server again.
If you’d like to rotate your server’s API key for this service
zulip_org_key), you need to use
manage.py register_server --rotate-key option; it will automatically generate a new
zulip_org_key and store that new key in
Why this is necessary¶
Both Google’s and Apple’s push notification services have a security model that does not support mutually untrusted self-hosted servers sending push notifications to the same app. In particular, when an app is published to their respective app stores, one must compile into the app a secret corresponding to the server that will be able to publish push notifications for the app. This means that it is impossible for a single app in their stores to receive push notifications from multiple, mutually untrusted, servers.
Zulip’s solution to this problem is to provide a central push notification forwarding service, which allows registered Zulip servers to send push notifications to the Zulip app indirectly (through the forwarding service).
Security and privacy¶
Use of the push notification bouncer is subject to the Zulipchat Terms of Service. By using push notifications, you agree to those terms.
We’ve designed this push notification bouncer service with security and privacy in mind:
- A central design goal of the the Push Notification Service is to avoid any message content being stored or logged by the service, even in error cases. We store only the necessary metadata for delivering the notifications. This includes the tokens needed to push notifications to the devices, and user ID numbers generated by your Zulip server. These user ID numbers are are opaque to the Push Notification Service, since it has no other data about those users.
- All of the network requests (both from Zulip servers to the Push Notification Service and from the Push Notification Service to the relevant Google and Apple services) are encrypted over the wire with SSL/TLS.
- The code for the push notification forwarding service is 100% open source and available as part of the Zulip server project on GitHub.
- The push notification forwarding servers are professionally managed by a small team of security expert engineers.
- If you’d like an extra layer of protection, there’s a
PUSH_NOTIFICATION_REDACT_CONTENTsetting available to disable any message content being sent via the push notification bouncer (i.e. message content will be replaced with
***REDACTED***). Note that this setting makes push notifications significantly less usable. We plan to replace this feature with end-to-end encryption which would eliminate that usability tradeoff.
If you have any questions about the security model, contact firstname.lastname@example.org.
Systems using the Mobile Push Notifications Service will, by default, submit basic usage statistics (e.g. Zulip version, number of users, number of messages sent) to the service. These statistics help the Zulip open source project understand how many people are using Zulip, and help us allocate resources towards supporting self-hosted installations.
Our use of these statistics is governed by the same ToS and
itself. If your organization does not want to submit these
statistics, you can disable this feature at any time by setting
Here are legacy instructions for signing a server up for push notifications, for Zulip 1.8 and older.
- First, contact email@example.com with the
zulip_org_keyvalues from your
/etc/zulip/zulip-secrets.conffile, as well as a
contact emailaddress you’d like us to use in case of any issues (we hope to have a nice web flow available for this soon).
- We’ll enable push notifications for your server on our end. Look for a reply from Zulipchat support within 24 hours.
Sending push notifications directly from your server¶
As we discussed above, it is impossible for a single app in their stores to receive push notifications from multiple, mutually untrusted, servers. The Mobile Push Notification Service is one of the possible solutions to this problem. The other possible solution is for an individual Zulip server’s administrators to build and distribute their own copy of the Zulip mobile apps, hardcoding a key that they possess.
This solution is possible with Zulip, but it requires the server administrators to publish their own copies of the Zulip mobile apps (and there’s nothing the Zulip team can do to eliminate this onerous requirement).
The main work is distributing your own copies of the Zulip mobile apps configured to use APNS/GCM keys that you generate. This is not for the faint of heart! If you haven’t done this before, be warned that one can easily spend hundreds of dollars (on things like a DUNS number registration) and a week struggling through the hoops Apple requires to build and distribute an app through the Apple app store, even if you’re making no code modifications to an app already present in the store (as would be the case here). The Zulip mobile app also gets frequent updates that you will have to either forgo or republish to the app stores yourself.
If you’ve done that work, the Zulip server configuration for sending push notifications through the new app is quite straightforward:
- Create a
GCM push notifications
key in the Google Developer console and set
/etc/zulip/zulip-secrets.confto that key.
- Register for a
mobile push notification certificate
from Apple’s developer console. Set
APNS_CERT_FILEto be the path of your APNS certificate file in
- Restart the Zulip server.