From fefd8f1a26dfdf5484e7248159c4ec89cf58c0f1 Mon Sep 17 00:00:00 2001 From: Muhsin Date: Tue, 3 Mar 2026 16:03:26 +0400 Subject: [PATCH] chore: update push guide --- contributing-guide/mobile-app/setup-guide.mdx | 88 ++++++++++++++++++- 1 file changed, 85 insertions(+), 3 deletions(-) diff --git a/contributing-guide/mobile-app/setup-guide.mdx b/contributing-guide/mobile-app/setup-guide.mdx index bb32e8d5..67156a70 100644 --- a/contributing-guide/mobile-app/setup-guide.mdx +++ b/contributing-guide/mobile-app/setup-guide.mdx @@ -113,11 +113,93 @@ npx expo install package-name pnpm install package-name ``` -## Push notification +## Push notifications -If you are using the community edition of Chatwoot, you can now use the [official mobile app](https://www.chatwoot.com/mobile-apps) with push notifications without any additional configuration. +Chatwoot supports mobile push notifications through Firebase Cloud Messaging (FCM). There are two delivery paths depending on your setup: -For more details, please refer to the [push notification documentation](https://www.chatwoot.com/hc/handbook/articles/1687935909-push-notification). +- **Relay server (default)**: Self-hosted instances without Firebase credentials route notifications through the Chatwoot relay server, which forwards them to the **official Chatwoot mobile app**. +- **Direct FCM**: Instances with Firebase configured send notifications directly to your **custom-built mobile app**. + + +You must use either the official apps for both platforms or custom builds for both — mixing is not supported. For more details, refer to the [push notification documentation](https://www.chatwoot.com/hc/handbook/articles/1687935909-push-notification). + + +### Using the official mobile app + +If you are using the community edition of Chatwoot with the [official mobile app](https://www.chatwoot.com/mobile-apps), push notifications work out of the box with no additional configuration. The relay server is enabled by default (`ENABLE_PUSH_RELAY_SERVER=true`). + +### Setting up Firebase for custom builds + +If you are building a custom-branded mobile app, you need to configure Firebase on both the mobile app and the Chatwoot server. + +#### Step 1: Create a Firebase project + +1. Go to the [Firebase Console](https://console.firebase.google.com/) and create a new project (or use an existing one). +2. Register your Android app with your package name (e.g., `com.yourcompany.app`). +3. Register your iOS app with your bundle identifier (e.g., `com.yourcompany.app`). + +#### Step 2: Download Firebase config files + +Download the platform-specific configuration files from your Firebase project settings: + + + +1. In **Project Settings > General**, find your Android app and click **Download google-services.json**. +2. Place the file in the root of the mobile app repository. + + +1. In **Project Settings > General**, find your iOS app and click **Download GoogleService-Info.plist**. +2. Place the file in the root of the mobile app repository. + + + +#### Step 3: Configure mobile app environment variables + +Update your `.env` file to point to the Firebase config files: + +```bash +EXPO_PUBLIC_ANDROID_GOOGLE_SERVICES_FILE=./google-services.json +EXPO_PUBLIC_IOS_GOOGLE_SERVICES_FILE=./GoogleService-Info.plist +``` + +Then regenerate the native code so the new config is picked up: + +```bash +pnpm generate +``` + +#### Step 4: Generate a Firebase service account + +The Chatwoot server needs a service account to send push notifications via the FCM v1 API. + +1. In the Firebase Console, go to **Project Settings > Service accounts**. +2. Click **Generate new private key** to download a JSON credentials file. + + +Keep this file secure. It grants access to send push notifications on behalf of your Firebase project. + + +#### Step 5: Configure the Chatwoot server + +In your Chatwoot installation, navigate to **Super Admin > App Config** and set the following: + +| Config key | Value | +| ----------------------- | --------------------------------------------------------- | +| `FIREBASE_PROJECT_ID` | Your Firebase project ID (e.g., `my-project-12345`) | +| `FIREBASE_CREDENTIALS` | The full contents of the service account JSON file | + +Once both values are set, the server will send push notifications directly to FCM instead of using the relay server. + +#### Verifying the setup + +1. Build and install the custom app on a device (`pnpm run:ios` or `pnpm run:android`). +2. Log in to your Chatwoot instance from the mobile app. +3. From another browser session, send a message to a conversation assigned to the logged-in agent. +4. The device should receive a push notification. + + +Push notifications do not work on iOS simulators. You must use a physical device to test. + ## Build & Submit using EAS