zulip/docs/production/mobile-push-notifications.md

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:

1. First, contact support@zulipchat.com with the zulip_org_id and zulip_org_key values from your /etc/zulip/zulip-secrets.conf file, as well as a hostname and contact email address you'd like us to use in case of any issues (we hope to have a nice web flow available for this soon).

2. We'll enable push notifications for your server on our end. Look for a reply from Zulipchat support within 24 hours.

3. Uncomment the PUSH_NOTIFICATION_BOUNCER_URL = "https://push.zulipchat.com" line in your /etc/zulip/settings.py file, and restart your Zulip server. Note that if you installed Zulip older than 1.6, you'll need to add the line (it won't be there to uncomment).

4. 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.

That should be all you need to do!

If you'd like to verify the full pipeline, 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.

Note that use of the push notification bouncer is subject to the Zulipchat Terms of Service. By using push notifications, you agree to those terms.

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 implications

We've designed this push notification bouncer service with security and privacy in mind:

• 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 Service is designed to avoid any message content being stored or logged, even in error cases.
• The push notification forwarding servers are professionally managed by a small team of security experts.
• There's a PUSH_NOTIFICATION_REDACT_CONTENT setting 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 support@zulipchat.com.