How push notifications work#

When something happens in the CRM that a person must know about — a lead is assigned, a call is logged, an appointment approaches — the CRM sends them a notification. In the browser it appears in the notification bell. On the Android app, the same notification also arrives as a push, and tapping it opens the exact screen the notification is about.

Push is optional per workspace: it works out of the box through the platform's Firebase configuration, and a workspace can bring its own Firebase project for full control.

sequenceDiagram
    autonumber
    participant E as CRM event (lead, call, task…)
    participant N as Database notification
    participant L as PushDatabaseNotifications listener
    participant J as SendPushToUser job
    participant F as FCM (v1)
    participant A as Android app

    E->>N: e.g. LeadAssigned notification
    N->>L: NotificationSent (database channel)
    L->>L: PushService builds payload + deep link
    L->>J: dispatch SendPushToUser
    J->>F: data-only push message
    F-->>A: delivered to device
    A->>A: crm://{entity_type}/{entity_id} → opens screen

The trace in plain language#

1. An event happens. The CRM creates a database notification for a user (this is the same notification you see under the bell in the web app).
2. A bridge notices. The PushDatabaseNotifications listener reacts to the NotificationSent event — only for notifications that went to the database channel.
3. A payload is built. PushService decides whether the notification has a linked entity and builds the payload, including a deep link in the form crm://{entity_type}/{entity_id}.
4. A job is queued. SendPushToUser runs on the queue and hands the message to the FCM provider (FcmPushProvider, Firebase Cloud Messaging v1 API), as a data-only message — the app, not Google, decides how to present it.
5. The phone receives it. The Android app's LeadHubMessagingService maps the payload to the correct crm:// deep link and shows the notification.
6. Tapping navigates. The deep link opens the right screen — lead, call, appointment or task.

What deep-links to what#

Where Firebase credentials come from#

Push resolution is layered — the first configured source wins:

1. The workspace's own Firebase service account (settings.push.firebase_service_account_json) — bring-your-own-Firebase.
2. The platform's configured service account (platform settings row).
3. The server's environment (services.fcm.service_account_json).

If none is configured, pushes are simply not sent; in-app notifications continue to work. Nothing breaks.

Troubleshooting notes#

Technical details#

• Listener: App\Listeners\PushDatabaseNotifications reacts to NotificationSent (database channel) → PushService::buildPayload() → SendPushToUser job → FcmPushProvider (FCM v1, data-only payload).
• Token resolution: the user's registered devices (devices.push_token), populated by the app's PushRegistration.
• Entity map (PushService::ENTITY_LINKS): lead_id → lead, call_id / lead_call_id → call, appointment_id → appointment, task_id / followup_id → followup; deep link format crm://{entity_type}/{entity_id}.
• Service account precedence: tenant settings.push.firebase_service_account_json → platform settings → services.fcm.service_account_json env.

Related guides#

• Push notifications (FCM) · Push notifications
• Notifications · How a Meta lead becomes a CRM lead
• Mobile not syncing / push not arriving