Administrators can control how the Rocket.Chat mobile app behave on user devices and how push notifications reach those devices. This page covers both: the Mobile settings, which apply to the app itself, and the Push settings, which control whether, how, and what notifications are sent.
Configure mobile settings
Mobile settings define what users can do in the mobile app and whether the app must be unlocked before use.
To configure mobile settings:
Go to Manage → Workspace → Settings →Mobile.
Update the settings below as required, then click Save changes.
Setting
Description
Allow Save Media to Gallery
Lets users save images, videos, and files from conversations to their device gallery.
Force screen lock
Requires users to unlock the app with a PIN or biometric authentication, such as fingerprint or Face ID.
Force screen lock after
Available under Screen Lock. Sets how long, in seconds, after the user's latest session ends before the app asks them to unlock it again. The default is
1800(30 minutes).
Use Force screen lock together with a short Force screen lock after value when your organization's policies require stricter device-level security.
Choose a push delivery method
Push notifications alert users to new messages when they aren't actively using the mobile app. Rocket.Chat can deliver them in two ways:
Method | When to use it | What you manage |
|---|---|---|
Rocket.Chat push gateway (recommended) | Your users use the official Rocket.Chat mobile apps from the App Store or Google Play. | Nothing beyond enabling the gateway. Rocket.Chat holds the Apple (APN) and Google (FCM) credentials the official apps need. |
Your own credentials | You publish your own white-labeled version of the mobile app. | Your own APN and FCM credentials, and your own build of the app. See the Mobile App White Labeling guide. |
The official mobile apps only work with the Rocket.Chat gateway. If you disable the gateway and enter your own credentials, users must install your white-labeled app to receive notifications.
Enable push notifications
Before you begin
To use the Rocket.Chat push gateway, your workspace must meet these requirements:
The workspace is registered under Setup Wizard → Organization Info → Register Server. If it isn't registered, the gateway won't work even when Enable Gateway is on.
You have accepted the Cloud Service Privacy Terms Agreement under Manage → Workspace → Settings → Setup Wizard → Cloud Info → Cloud Service Privacy Terms Agreement.
If your server is behind a firewall, it can reach
gateway.rocket.chat. See Firewall Configuration for the full list of required URLs.
To enable push notifications:
Go to Manage → Workspace → Settings → Push.
Update the settings below as required, then click Save changes.
Restart Rocket.Chat.
Changes to Enable, Enable Gateway, Gateway, and Production take effect only after a restart.
Click Send a test push to my user to confirm notifications arrive. Before testing, log in to the mobile app with the same user and put the app in the background.
Setting | Description |
|---|---|
Enable | Turns push notifications on or off for the workspace. |
Enable Gateway | Sends notifications through the Rocket.Chat push gateway. Available only when Enable is on, the workspace is registered, and the Cloud Service Privacy Terms are accepted. Turn it off only if you use your own credentials (see the next section). |
Gateway | The gateway address. The default is |
Production | Available only when the gateway is turned off. When on, Rocket.Chat uses your production APN credentials. When off, it uses your APN dev credentials and Apple's sandbox environment, for testing development builds of your app. |
Send a test push to my user | Sends a test notification to the mobile devices of the user you're logged in as. Available when Enable is on. |
Use your own APN and FCM credentials
When Enable Gateway is off, Rocket.Chat sends notifications directly to Apple (APN) and Google (FCM) using credentials you provide. Use this method only with a white-labeled mobile app built for your workspace.
In Manage → Workspace → Settings → Push → Certificates and Keys, fill in the credentials for the platforms you support:
Platform | Settings |
|---|---|
iOS, production | APN Passphrase, APN Key, APN Cert |
iOS, development | APN Dev Passphrase, APN Dev Key, APN Dev Cert (used when Production is off) |
Android | Google FCM API Credentials |
For how to generate these credentials, see the Configuring Push Notifications guide.
Control what notifications show
Privacy settings control how much of a message appears in a push notification and who can see its content on the way to the device. Find them under Manage → Workspace → Settings → Push → Privacy.
Setting | Description |
|---|---|
Show Channel/Group/Username in Notification | When on, the notification shows the room or sender name. |
Show Message in Notification | When on, the notification shows the message text. When off, users see a generic notification and must open the app to read the message. |
Hide message content from Apple and Google (and the Gateway, if enabled) | Premium plans only. When on, Rocket.Chat sends only a message ID. The mobile app then fetches the message directly from your server before displaying it, so the content never passes through Apple, Google, or the gateway. |
For compliance-sensitive environments, such as those subject to HIPAA, turn on Hide message content from Apple and Google so message content stays on your server.
Set default notification preferences
The Push Notifications Default Alert setting decides which messages trigger a push for users who haven't chosen their own preference. Set it under Manage → Workspace → Settings → Accounts → Default User Preferences.
Users can override this default in two places:
Account preferences: applies to all their rooms.
Room preferences: applies to a single room and takes priority over account preferences.
In large rooms, Rocket.Chat stops sending notifications for every message once the room exceeds Max Room Members Before Disabling All Message Notifications (default: 100). Users can still change their preference for that room to receive all notifications. Change the limit under Manage → Workspace → Settings → General → Notifications, or set it to 0 to disable it. See Notifications settings.
Monitor push notification usage
Push notifications sent through the Rocket.Chat gateway count toward your workspace's monthly limit. To check your usage:
Log in to Rocket.Chat Cloud portal.
Click Workspaces in the left menu and select your workspace.
Under Push Notifications (current month), see how many push notifications your workspace has used this month, followed by its limit.
To see past usage, go to Push Notifications Usage, choose Monthly or Daily, and select a period.
To raise the limit, see Rocket.Chat plans.
When push notifications are sent
Whether a user gets a push depends on server settings, notification preferences, mentions, and room membership, not on their status. When a push is due, Rocket.Chat queues it and decides when to send it based on the user's connection state:
Connection state | When the push is sent |
|---|---|
Online (active in a Rocket.Chat session) | After 120 seconds |
Away (connected but idle) | Immediately |
Offline (no active session) | Immediately |
The 120-second delay gives online users time to read the message on the device they're already using. If they do, the push is never sent.
Rocket.Chat also manages the queue as follows:
When a user reads messages, all of their queued notifications are cleared.
When one of a user's notifications is sent, any other notifications waiting for that user are sent right away.
Self-managed workspaces can change these delays with the environment variables NOTIFICATIONS_SCHEDULE_DELAY_ONLINE, NOTIFICATIONS_SCHEDULE_DELAY_AWAY, and NOTIFICATIONS_SCHEDULE_DELAY_OFFLINE, in seconds. A negative value stops push notifications for users in that state.
Troubleshoot push notifications
If users don't receive push notifications, first click Send a test push to my user under Manage → Workspace → Settings → Push. If the test fails, check that push is enabled, that you restarted Rocket.Chat after changing push settings, and that your server can reach the gateway.
If the test succeeds but a user still misses notifications, check whether one of these applies:
The user's account or room preference for mobile notifications is set to Nothing, or the user has no preference and Push Notifications Default Alert is set to Nothing.
The user turned off notifications for the room.
The user has ignored the sender.
The message mentions
@allor@here, and the user muted group mentions for the room.The room has more members than Max Room Members Before Disabling All Message Notifications.
The message is in a thread the user isn't following.
The user read the message on another device within 120 seconds, so the queued push was cleared.
The user isn't logged in to the mobile app on their device.
The user's status, including Busy, does not stop push notifications. It affects desktop notifications only.
For more help, see the Push Notifications FAQ.