Skip to main content

Step 2: OneSignal Configuration

OneSignal is the push notification service used to send real-time alerts to your mobile app users. This guide will walk you through setting up OneSignal for both iOS and Android platforms.

Create OneSignal App​

Step 1: Sign Up or Log In​

  1. Go to https://onesignal.com
  2. Sign up for a free account or log in if you already have one
  3. Click "New App/Website" button

Step 2: Create New App​

  1. Enter your App Name (e.g., "WhautoChat Business")
  2. Select Mobile App as the platform
  3. Click "Create"

iOS Configuration (Apple Push Notification Service)​

Step 1: Generate APNs Auth Key​

You need to create an APNs (Apple Push Notification service) authentication key in your Apple Developer account.

  1. Log in to Apple Developer Portal
  2. Go to Certificates, Identifiers & Profiles
  3. Click Keys in the sidebar
  4. Click the blue plus (+) button to create a new key
  5. Enter a Key Name (e.g., "WhautoChat Push Notifications")
  6. Check Apple Push Notifications service (APNs) and make sure Sandbox & Production is selected
  7. Click Continue, then Register
  8. Download the .p8 file (you can only download this once!)
  9. Note the Key ID (10-character string, shown next to your key name in the Keys section)
  10. Note your Team ID (10-character string, found in the top right of the developer portal)
Important

The .p8 key file can only be downloaded once. Store it securely. If you lose it, you'll need to create a new key.

Key ID and Team ID are both 10-character strings in different locations, double-check you haven't swapped them.

Step 2: Configure iOS in OneSignal​

  1. In your OneSignal app dashboard, go to Settings → Push & In-App → Platforms
  2. Click Apple iOS (APNs)
  3. Select .p8 Auth Key (Recommended) as the authentication method
  4. Upload your .p8 file
  5. Enter your Key ID
  6. Enter your Team ID
  7. Enter your Bundle ID (e.g., chat.whauto.app)
  8. Click Save & Continue

Android Configuration (Firebase Cloud Messaging)​

Step 1: Create Firebase Project​

  1. Go to Firebase Console
  2. Click "Add project" or "Create a project"
  3. Enter your Project name (e.g., "WhautoChat Business")
  4. Disable Google Analytics (optional, not needed for push notifications)
  5. Click "Create project"

Step 2: Add Android App to Firebase​

  1. In your Firebase project, click the Android icon to add an Android app
  2. Enter your Android package name (same as your Bundle ID, e.g., chat.whauto.app)
  3. Enter App nickname (optional, e.g., "WhautoChat Android")
  4. Leave Debug signing certificate SHA-1 empty for now
  5. Click "Register app"
  6. Download the google-services.json file
  7. Click Continue and Finish

Step 3: Generate a Firebase Service Account Private Key​

Legacy Server Keys are deprecated

OneSignal no longer accepts the old Cloud Messaging API (Legacy) Server Key (the key starting with AAAA... or AIz...). Firebase Cloud Messaging now uses the HTTP v1 API, which requires a Service Account JSON private key instead. Follow the steps below.

  1. In Firebase Console, click the gear icon → Project settings
  2. Go to the Cloud Messaging tab and confirm Firebase Cloud Messaging API (V1) shows as Enabled. If it is disabled, click the three-dot menu, select Manage API in Google Cloud Console, and enable it.
  3. Go to the Service accounts tab
  4. Click Generate new private key, then confirm in the popup dialog
  5. A .json file downloads automatically, store it securely (this is your Service Account key)
info

The Service Account must have both the cloudmessaging.messages.create and firebase.projects.get permissions. These are granted by default when Firebase creates the account.

Step 4: Configure Android in OneSignal​

  1. In your OneSignal app dashboard, go to Settings → Push & In-App → Platforms
  2. Click Google Android (FCM)
  3. Under the Service Account section, click Select file and choose the .json private key you downloaded from Firebase
  4. Click Save & Continue to validate the credentials
info

If you receive an "Invalid request" error, verify the Service Account roles in Google Cloud Console under IAM & Admin → IAM.

Verify Configuration​

Test iOS Push Notifications​

  1. In OneSignal dashboard, go to Messages → New Push
  2. Enter a test message
  3. Under Audience, select Test Users or Subscribed Users
  4. Select iOS as the platform
  5. Click Send Message

Test Android Push Notifications​

  1. In OneSignal dashboard, go to Messages → New Push
  2. Enter a test message
  3. Under Audience, select Test Users or Subscribed Users
  4. Select Android as the platform
  5. Click Send Message
tip

You'll be able to fully test push notifications after your app is built and installed on a device. These steps are for later verification.

Configure Server Environment Variables​

After obtaining your OneSignal credentials, you need to configure them in your WhautoChat server installation.

Step 1: Get OneSignal App ID and API Key​

  1. In OneSignal dashboard, go to Settings → Keys & IDs
  2. Copy your OneSignal App ID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
  3. Copy your REST API Key (this will be used as ONE_SIGNAL_API_KEY)

Step 2: Update web-server.env File​

  1. Navigate to your WhautoChat installation directory on your server
  2. Open the web-server.env file
  3. Add or update the following environment variables:
ONE_SIGNAL_APP_ID=your-onesignal-app-id
ONE_SIGNAL_API_KEY=your-onesignal-rest-api-key
  1. Save the file

Step 3: Restart the Server​

After updating the environment variables, restart your WhautoChat server for the changes to take effect:

docker-compose restart
Important

Make sure to configure these environment variables before running the installation. If you haven't installed WhautoChat yet, refer to the Installation Guide for complete setup instructions.

What Stays in Your Accounts vs. What WhautoChat Needs​

Most of what you set up above lives in your own OneSignal and Firebase/Apple accounts. WhautoChat does not need those credentials to build the app, only the items in the "Share with WhautoChat" list below.

Configured in your OneSignal account (do not send to WhautoChat)​

These are used by OneSignal to deliver push notifications and never leave your dashboard:

  • iOS APNs .p8 Key, Key ID, Team ID (uploaded under Apple iOS (APNs) settings)
  • Android Firebase Service Account JSON private key (uploaded under Google Android (FCM) settings)

Configured on your WhautoChat server (do not send to WhautoChat)​

The mobile app reads your OneSignal App ID at runtime from your server's /branding/mobile-config endpoint, so it does not get baked into the build.

Share with WhautoChat for the app build​

The only OneSignal/Firebase artifact needed for the build is the Android Firebase config file:

  • Firebase google-services.json file (required so the Android app can register for push)
  • Android Package Name (must match your Bundle ID, e.g. chat.whauto.app)
info

iOS push needs no extra file at build time, the push capability is included via your provisioning profile (see Apple Configuration). The remaining build inputs (icons, signing certificates, keystore, server URL, etc.) are collected in Step 6: Submit for Build.

Configuration Checklist​

Before proceeding, ensure you have:

  • Created OneSignal account and app
  • Generated APNs .p8 key from Apple Developer Portal
  • Configured iOS platform in OneSignal
  • Created Firebase project
  • Added Android app to Firebase
  • Downloaded google-services.json file
  • Generated Firebase Service Account JSON private key (FCM V1)
  • Configured Android platform in OneSignal
  • Noted your OneSignal App ID
  • Prepared all files and credentials for WhautoChat

Common Issues​

iOS: "Invalid APNs Certificate"​

Solution: Ensure you're using the correct Bundle ID and that your .p8 key has APNs enabled.

Android: "Invalid request" when uploading the Service Account key​

Solution: Make sure Firebase Cloud Messaging API (V1) is enabled in your Firebase project, and that you uploaded the Service Account JSON (not the google-services.json file). Verify the Service Account roles in Google Cloud Console under IAM & Admin → IAM.

"No devices subscribed"​

Solution: This is normal before the app is built and installed. Devices will appear after users install and open the app.

Next Steps​

Once you have completed the OneSignal configuration:

  1. Proceed to Apple Configuration for iOS certificates and provisioning
  2. Continue with Google Configuration for Android app signing
  3. Submit all credentials to WhautoChat for app build

Additional Resources​