zulip/docs/prod-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 Android and Zulip 1.7 for 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](prod-maintain-secure-upgrade.html#updating-settings).
   Note that if you installed Zulip older than 1.6, you'll need to add
   the line (it won't be there to uncomment).

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][notification-settings]
  (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](https://play.google.com/store/apps/details?id=com.zulip.android).
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.

[notification-settings]: https://zulipchat.com/help/configure-mobile-notifications

Note that use of the push notification bouncer is subject to the
[Zulipchat Terms of Service](https://zulipchat.com/terms/). 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 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](https://github.com/zulip/zulip).
  The service's logging is designed to protect the privacy of users of
  Zulip servers that are using the forwarding service.
* The push notification forwarding servers are professionally managed
  by a small team.

If you have any questions about the security model, contact
support@zulipchat.com.