> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Push

> Sending mobile notifications and managing the device subscriptions that receive them.

Push is how you nudge a customer back into the app. There are two halves to the integration, and both are required before a single notification lands:

* **Notifications** — created from your backend, targeted and scheduled.
* **Device subscriptions** — registering each device that should receive them.

Typical drivers are a CMS publishing new content, a marketing automation trigger, or a moment in the customer lifecycle.

## Notification lifecycle

```mermaid theme={"system"}
flowchart LR
    D["Draft"] --> R["Ready"]
    R --> S["Scheduled"]
    S --> G["Delivering"]
    G --> V["Delivered"]
    G --> F["Failed"]
```

A notification is created with `IsReadyToDistribute` set to `false` while you prepare it, then flipped to `true` to release it. `DeliveryDate` schedules the send; `ExpirationDate` stops delivery after a cut-off, which matters for time-sensitive content.

A `DeepLink` object sends the customer to a specific screen when they tap through.

<Warning>
  **Editing and deleting have hard windows.**

  * A notification can only be updated **before delivery starts**, and an update is a full object replacement — send every field, not just the ones you changed.
  * Only notifications in `Draft` or `Ready` can be deleted, and deletion is permanent.
  * Nothing can retract a notification already on a device. It stays in the app's notification history.
</Warning>

## Targeting

| Mode          | `SegmentationType` | Reaches                                                                                                                   |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Broadcast     | `null` or `None`   | Everyone with the app installed                                                                                           |
| Audience      | `Audience`         | Segments named in `AudienceIds`, via the [Audience](/integration/other-integrations/audience-lobyco-segmentation) service |
| Customer list | `Customer`         | Named customers, from an uploaded customer ID list                                                                        |

## Subscribing a device

A device receives nothing until it is subscribed. Do this when a customer first signs in, when they grant notification permission, after a reinstall, when they sign in on another device, and whenever the OS refreshes the token.

<Steps>
  <Step>
    ### Check permission

    Confirm the customer has granted push permission at OS level. Without it there is no token to register.
  </Step>

  <Step>
    ### Get the device token

    Request it from the platform:

    * iOS — `UIApplication.shared.registerForRemoteNotifications()`
    * Android — `FirebaseMessaging.getInstance().getToken()`
    * Huawei — HMS Push Kit SDK
  </Step>

  <Step>
    ### Generate an installation ID

    Create it on first launch and keep it for the life of the installation. It is what distinguishes one of the customer's devices from another.
  </Step>

  <Step>
    ### Subscribe

    Send the customer ID, token, platform and installation ID.
  </Step>

  <Step>
    ### Watch for token changes

    Tokens rotate on OS updates, reinstalls and security refreshes. Listen for the change and re-subscribe with the **same installation ID** so you update the existing subscription instead of creating a duplicate.
  </Step>
</Steps>

### What you send

| Field            | Value                                                                            |
| ---------------- | -------------------------------------------------------------------------------- |
| `customerId`     | Your identifier for the customer — loyalty card number, customer ID, email hash. |
| `TokenHandle`    | The push token from APNs, FCM or HMS.                                            |
| `Platform`       | `ios`, `android`, or `huawei` for Huawei devices without Google Play Services.   |
| `InstallationId` | Stable per app installation, generated by your app.                              |

<Info>
  A customer can hold **several active subscriptions at once** — personal phone, tablet, work phone. Each device subscribes individually with its own token and installation ID. Subscriptions persist until they are explicitly removed or the device goes quiet for long enough to be treated as inactive.
</Info>

## Unsubscribing a device

Unsubscribing is **device-specific**: only the installation ID you name stops receiving notifications, and the customer's other devices carry on.

| Trigger                                                          | What to do                                                                                    |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Opt-out** — the customer turns push off in your app's settings | Unsubscribe that installation. The device receives nothing further until it re-subscribes.    |
| **Logout** — the customer signs out                              | A product decision. Some apps keep devices subscribed for general announcements after logout. |
| **Account deletion** — the customer deletes their account        | Unsubscribe every device associated with them, so nothing is sent to a deleted account.       |

<Info>
  Unsubscribing is a **soft delete**. The subscription is marked inactive rather than removed, so reporting and the audit trail stay intact, and the same installation ID can be reused when re-subscribing. Notifications already delivered stay on the device.
</Info>

## API reference

Endpoint documentation for this service: [Push](/api-reference/communication/push).