Zodiac Tech CRM Docs

Push notifications

How push alerts work in the Android app — bring-your-own Firebase setup, what triggers a push, deep links, and how to test it.

sales admin Easy ⏱ 5 min Updated 2026-10-05

Push notifications

Push notifications let the app alert an agent the moment something happens — a new assigned lead, a due follow-up, an appointment reminder. Push is optional: the CRM works without it (you just won't get alerts on the lock screen), and the app is honest about which of the four states it is in.

Who this is for

  • Admins connecting the workspace's Firebase project.
  • Agents wondering why a colleague gets alerts and they don't.

Difficulty: Easy · Time: about 5 minutes · Prerequisites: a workspace admin with access to the CRM's mobile settings; a Firebase project (free tier is fine).

How it fits together (bring your own Firebase)

Push uses Firebase Cloud Messaging (FCM). Each workspace connects its own Firebase project — there is no shared vendor project and no google-services.json baked into the APK:

  1. An admin creates a Firebase project and adds an Android app for com.zodiactech.crm (the app's application ID; demo flavor: com.zodiactech.crm.demo), then copies the app's Firebase options (API key, project ID, app ID, sender ID).
  2. In the CRM, the admin pastes those values into the workspace's Mobile App Login / push settings (Super Admin → Mobile & app settings; tenant-level override in the workspace's mobile_auth settings — see Mobile app setup).
  3. The app fetches the options automatically at login (auth-config) and registers this device's FCM token with the CRM (POST /api/v1/mobile/device/register).

If a workspace never configures Firebase, nothing breaks: the app simply stays on in-app notifications.

Step 1 — Set up on the phone

  1. Install and log in (see Login & workspace selection).
  2. When Android asks to allow notifications (Android 13+), tap Allow. Declining sets the push state to PERMISSION_DENIED — fix it any time from More → Device health → Push notifications (FCM) → ALLOW / SETTINGS.
  3. Open More → Device health and check the Push notifications (FCM) row. It shows one of four real states:
State shown Meaning
Registered — "Registered — this device receives push alerts." All good; token posted to the CRM
Permission denied Notifications are off at the OS level; pushes arrive silently. Use ALLOW / SETTINGS
Not configured The workspace hasn't connected Firebase. In-app notifications still work
Pending Token not posted yet; the app retries automatically (or tap RETRY)

Step 2 — What triggers a push

Push alerts ride the CRM's notification system: when the CRM creates an in-app notification for you (new assigned lead, due follow-up, appointment, WhatsApp-related alerts), the same event is pushed to your phone if it is registered. Tapping the push opens the app via a deep link straight to the record:

Deep link Opens
crm://lead/{id} That lead
crm://call/{id} That call
crm://followup/{id} That follow-up
crm://appointment/{id} That appointment
crm://notification/{id} Notifications list

Step 3 — Test it

  1. From the CRM server, run the platform's test-push Artisan command for your account (your developer/operator can run php artisan leadhub:test-push you@example.com).
  2. Keep the app logged in and the phone online.
  3. The phone should show a notification within seconds; tapping it opens the linked screen.

Expected result

  • Device health shows Push notifications (FCM): Registered for phones that should get push.
  • A tapped notification lands on the exact lead/call/follow-up it is about.
  • Phones without Firebase configured still show the same alerts inside the app's Notifications screen.

Common mistakes

Mistake What happens Fix
Editing Firebase values in the wrong settings group App never receives options Configure at Super Admin → Mobile & app settings (or the workspace's mobile login settings)
Pasting Firebase web values FCM registration fails silently Use the Android app options from the Firebase project
Expecting push after denying notifications State is Permission denied Allow from Device health SETTINGS
Testing with an account that has no device registered No push target Log in on the phone once so device/register runs; check Device health shows Registered

Troubleshooting

  • State stuck at Pending — the app could not reach the server or Firebase. Check connectivity, then tap RETRY in Device health.
  • Registered but nothing arrives — check the workspace's Firebase project is the one configured, and run the test-push command. Check the phone's battery saver isn't killing the app's messages (exempt it — Device health → Battery optimization).
  • Two phones, only one gets push — each phone must be logged in and registered; check the second phone's Device health row.
  • Notifications appear silently — PERMISSION_DENIED state; re-allow notifications.

Technical details

  • CRM side: notification → PushDatabaseNotifications listener → queued SendPushToUser job (queue notifications, 2 tries with 30/120 s backoff) → FCM; payload deep link is built by PushService::buildPayload as crm://{entity_type}/{entity_id}.
  • App side: com.leadhub.sales.push.PushRegistration (State: REGISTERED, PERMISSION_DENIED, NOT_CONFIGURED, PENDING) and LeadHubMessagingService for data-only FCM messages; the raw token is never shown in the UI.
  • Device tokens are stored server-side in devices / device_tokens; the registration call is POST /api/v1/mobile/device/register with push_token and app_version.
  • Diagnostics command: php artisan leadhub:test-push <email>.

Was this page helpful?