Rocket.Chat provides mobile apps for iOS and Android, so you can stay connected while on the move. To keep communication secure, administrators can configure mobile app settings and push notifications to match their organization’s policies.
Configure mobile settings
Administrators can manage mobile settings by going to: Administration > Workspace > Settings > Mobile
From here, you can define how the Rocket.Chat mobile app behaves on users’ devices.
Available options
Options | What it does | Default |
---|---|---|
Allow Save Media to Gallery | Lets users save images, videos, or other files shared in chats directly to their device’s gallery. | Enabled (toggle on) |
Force Screen Lock | Requires users to set up a PIN, biometric authentication, or Face ID to unlock the Rocket.Chat mobile app. | Disabled (toggle off) |
Force Screen Lock After | Defines the time (in seconds) after the last session ends before the app asks for authentication again. Example: If set to | This option only applies when Force Screen Lock is enabled. |
Mobile app push notifications
Rocket.Chat supports push notifications on mobile devices so users don’t miss important messages. You can configure this in two ways:
Push Gateway (recommended): This is the recommended method if your users rely on the official Rocket.Chat mobile applications. With this option, Rocket.Chat securely manages the keys required to send notifications through Apple’s APN and Google’s FCM services. This means you don’t have to handle sensitive credentials yourself, and push alerts will reliably reach users through the official apps.
Self-Configured: This is required if you prefer not to use Rocket.Chat’s gateway. In that case, you will need to run your own push server and white-label the Rocket.Chat mobile app so it can communicate with your infrastructure. For detailed instructions on how to do this, refer to the Mobile App White Labeling guide.
If your server is behind a firewall, make sure to allow access to the Rocket.Chat gateway URL:
gateway.rocket.chat
You can find the complete list of required URLs in the Firewall Configuration documentation.
Configure push notifications
To use push notifications, you must first accept the Cloud Service Privacy Terms Agreement in:
Administration > Workspace > Settings > Setup Wizard > Cloud Info.
After that, go to Administration > Workspace > Settings > Push to configure the following options.
General push settings
Setting | Description | Notes |
---|---|---|
Enable | Turns push notifications on or off for your workspace. | Changing this value requires restarting Rocket.Chat. |
Enable Gateway | Allows your workspace to use the Rocket.Chat push gateway for notifications. Requires that your server is registered in the Setup Wizard and that you have accepted the Cloud Service Privacy Terms Agreement. | Changing this value requires restarting Rocket.Chat. If disabled, you must configure your own certificates and keys for APN/FCM. |
Gateway | Defines the push gateway to use. Default: | Changing this value requires restarting Rocket.Chat. |
Production | Enables push notifications for production environments. | Changing this value requires restarting Rocket.Chat. |
Send a test push to my user | Sends a test notification to your logged-in mobile device. | You must be logged in on mobile and minimize/close the app to test successfully. |
Important notes:
Cloud-hosted workspaces always use the Rocket.Chat gateway by default. This cannot be changed.
Self-managed workspaces can either use the default Rocket.Chat gateway or configure a custom gateway.
Community edition workspaces include up to 10,000 free push notifications per month. For unlimited push notifications, upgrade to one of Rocket.Chat’s premium plans .
Certificates and Keys
If you disable the gateway, Rocket.Chat falls back to direct communication with Apple (APN) and Google (FCM). In that case, you need to provide valid certificates and keys:
APN Passphrase
APN Key
APN Certificate
APN Dev Passphrase
APN Dev Key
APN Dev Certificate
Google FCM API Credentials
For more details, see the Configuring Push Notifications guide.
Privacy
Use these settings to control how much information is included in push notifications:
Show Channel/Group/Username in Notification: Displays the channel name, group name, or username in notifications.
Show Message in Notification: Makes the message text visible in the notification.
Hide message content from Apple and Google (and the Gateway, if enabled):
Available only on a Premium plan. Instead of sending message content, Rocket.Chat sends only a message ID. The mobile client then fetches the message content directly from the server before displaying it. If the fetch fails, the notification displays “You have a new message.” This option is useful for compliance scenarios where sensitive information must not be exposed to third-party services.
When Enabled
When privacy is enabled, contextual information (such as message content) is included in push notifications.
When Disabled
When privacy is disabled, push notifications are sent without contextual information.
The user only receives a generic notification.
To see the full message details, the user must open the Rocket.Chat application.
This setup is often required for compliance-sensitive environments (e.g., HIPAA) to prevent sensitive information from being disclosed in push notifications.
Next steps for notification management
After completing push configuration, set default user notification preferences via the Default User Preferences guide.
Manage channel-based notifications using the Channel Notifications guide.
On some channels, notifications may stop if the number of users exceeds the set limit. You can adjust this under Administration > General > Notifications. See Notifications guide for more details.
Cloud sync
For self-managed customers who purchase a push notification package:
Go to Administration > Workspace > Subscription.
Click Sync license updates.
This updates your workspace with the latest push notification entitlements from Rocket.Chat Cloud.
Managing notifications
Checking notification usage
To check the number of notifications used per month:
Go to cloud.rocket.chat.
Open the Workspaces tab and select your workspace.
In the Push notifications block, you’ll see the number of notifications used against your monthly limit.
Setting notification preferences
After completing push configuration, users can update their notification settings in several ways:
Account preferences: Users can manage their notification preferences in their profile.
Room preferences: Users can manage notification preferences for individual rooms they belong to.
These settings do not affect other workspace members.
Workspace administrators can define default notification settings for all users under:
Administration > Workspace > Settings > Accounts > Default user preferences.
Push notification rules
Notifications are determined by server settings, user preferences, and subscriptions.
User status (
online
,away
,offline
) is no longer considered.Notifications are queued and sent based on the following rules:
User state | Notification timing |
---|---|
Online | Scheduled in 120 seconds |
Away | Scheduled in 120 seconds minus away time |
Online | Sent immediately |
Additional rules:
When a user reads a channel, all their queued notifications are cleared.
When a notification is processed, any other scheduled notifications for that user are rescheduled to the current time. The current notification is re-queued and ordered by creation date.
Troubleshooting: why notifications may not be delivered
Notifications will not be sent if:
Room notifications are disabled.
The user ignores the sender.
@here
and@all
notifications are disabled, and the message includes one of these mentions.The user is not active or their status is set to Busy.
The user’s device is not connected (Desktop/Mobile).
The user has not enabled Always display mobile notifications.
User or room preference is set to Nothing.
The room member count exceeds the notification limit set in Administration.
Push notifications workflow
Rocket.Chat’s push notification workflow ensures that notifications are delivered quickly, reliably, and with flexibility. This process allows users to stay updated with new messages and channel activity, even when they are not actively using the app.
The diagram below illustrates the complete workflow, from the moment a message is sent in Rocket.Chat to when the push notification is received on a user’s mobile device.
Frequently Asked Questions (FAQs)
Why do I see the error ‘Server notifications are misconfigured!’?
This usually means your server is not properly set up for push notifications. Check the following:
Your Rocket.Chat server version is 0.74.3 or later.
Your server is registered with Rocket.Chat Cloud. You can verify this under:
http://<yourserver>/admin/cloud
Why are my users not receiving push notifications?
Ensure the following:
Push notifications are enabled in Administration > Workspace > Settings > Push.
The server has internet access and can reach
https://gateway.rocket.chat
.The workspace has not exceeded its monthly push notification quota (Community workspaces are limited to 10,000 per month).
Users have not disabled notifications in their account or room preferences.
Why do notifications sometimes stop working in large channels?
Notifications may stop if the number of members in a channel exceeds the configured notification limit. You can adjust this under:
Administration > General > Notifications.
Can I hide message content in push notifications for compliance reasons (e.g., HIPAA)?
Yes. In the Privacy settings, enable Hide message content from Apple and Google (and the Gateway, if enabled). This ensures that only a message ID is sent, and the mobile app fetches the content securely. Note that this feature requires a Premium plan.
Do I need to restart Rocket.Chat after changing push settings?
Yes. Many push-related changes (e.g., Enable, Enable Gateway, Gateway URL, Production) require a server restart before they take effect.
Why does the “Send a test push to my user” button not work?
To successfully receive a test push, ensure:
You're logged into the Rocket.Chat mobile app using the same account.
The app is minimized or closed (pushes won’t appear if the app is open and active).
Push notifications are correctly enabled and configured in Administration > Workspace > Settings > Push.
Can I test push notifications for other users?
No. The “Send a test push to my user” button only works for the currently logged-in user. Admins cannot use this to test on behalf of others.
Can I use a custom push gateway instead of Rocket.Chat’s?
Yes. To do this:
Disable the Enable Gateway toggle.
Provide your own certificates and keys in the Certificates and Keys section.
This is required for white-labeled mobile apps or enterprise deployments.
What happens when the monthly notification limit is reached?
Rocket.CFhat stops sending push notifications once the quota is exhausted.
Community workspaces have a limit of 10,000 push notifications per month.
To continue receiving notifications, you can upgrade to a Premium plan.