Skip to content

Revert "chore: Update mobile app push and deeplinking guide" #564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
muhsin-k wants to merge 1 commit into from
Closed

Revert "chore: Update mobile app push and deeplinking guide" #564

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 3 additions & 85 deletions contributing-guide/mobile-app/setup-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,93 +113,11 @@ npx expo install package-name
pnpm install package-name
```

## Push notifications
## Push notification

Chatwoot supports mobile push notifications through Firebase Cloud Messaging (FCM). There are two delivery paths depending on your setup:
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.

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

<Note>
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).
</Note>

### 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:

<Tabs>
<Tab title="Android">
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.
</Tab>
<Tab title="iOS">
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.
</Tab>
</Tabs>

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

<Warning>
Keep this file secure. It grants access to send push notifications on behalf of your Firebase project.
</Warning>

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

<Note>
Push notifications do not work on iOS simulators. You must use a physical device to test.
</Note>
For more details, please refer to the [push notification documentation](https://www.chatwoot.com/hc/handbook/articles/1687935909-push-notification).

## Build & Submit using EAS

Expand Down