> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt).
> Last updated: November 13, 2026
> To take actions in Customer.io from an agent, use the [Customer.io CLI](https://docs.customer.io/ai/cli/get-started.md) or the [MCP server](https://docs.customer.io/ai/mcp/get-started.md).

# Silent push

A silent push wakes your iOS or Android app in the background and hands it data, without showing anything to the person. Use it to tell your app to refresh content or sync an account.

## How it works

A silent push has no title, body, image, link, or sound. When it arrives, the device wakes your app in the background, and our SDK hands your app the key/value data you set on the message. Your app decides what to do with that data, like refreshing an inbox or downloading new content. Nothing appears on the person’s device.

Your app needs a version of our SDK that supports silent push, and your developers need to add code that handles the data:

SDK

Minimum version

Setup

iOS

5.2.0, or 5.2.1 if you install with CocoaPods

[iOS silent push](https://docs.customer.io/integrations/sdk/ios/push/silent-push/)

Android

5.1.0

[Android silent push](https://docs.customer.io/integrations/sdk/android/push/silent-push/)

React Native

7.3.0

[React Native silent push](https://docs.customer.io/integrations/sdk/react-native/push-notifications/silent-push/)

Flutter

5.2.0

[Flutter silent push](https://docs.customer.io/integrations/sdk/flutter/push-notifications/silent-push/)

Expo

Plugin 4.5.0, with React Native SDK 7.3.0

[Expo silent push](https://docs.customer.io/integrations/sdk/expo/push-notifications/silent-push/)

Customer.io doesn’t check which SDK version a device uses. A device with an older version of your app still receives the silent push, but nothing reads the data and the device doesn’t report *Delivered*.

## Before you begin

*   Set up your app to handle silent pushes. Your developers can follow the setup page for your SDK, listed in [how it works](#how-it-works).
*   Your account needs [multi-app support](https://docs.customer.io/messaging/channels/push/getting-started/#add-your-apps-and-push-credentials), which sends one delivery to each device.
*   You create silent pushes in [Design Studio](https://docs.customer.io/messaging/design-studio/overview/).

## Create a silent push

1.  Open your push in Design Studio. You can start from either place:
    *   In a **Push Notification** action, a broadcast, or a transactional push message, select or create a Design Studio push message, then click **Edit in Design Studio**.
    *   In Design Studio, click **Create**, select *New push*, and link the push to a message later.
2.  Click next to **Visual** and **Code**, and select *Convert to silent push*. If your push has a title, body, image, link, or sound, click **Switch to Silent** to confirm. Switching deletes those fields.
3.  Add the data your app needs. In the **Key/value** view, enter one key and one value on each row. To write or paste JSON instead, click **JSON**. Both views edit the same data. See [what the data can hold](#data).
4.  Choose an **Android priority**. With **Normal**, the default, Android can hold the message while a device is idle. Choose **High** if your app needs the data right away, or if your developers ask for it. Firebase may lower the priority of high-priority messages that keep showing no notification, so **High** doesn’t guarantee the data arrives right away.
5.  Click **Publish** to send your changes to the message your push is linked to.

To turn a silent push back into a notification, switch it to **Visual**, add a title and a body, and publish it. Sends from then on go out as notifications.

### What the data can hold

Your data is a flat set of keys and values, and every value is text. For example:

```
{
  "action": "refresh_orders",
  "order_id": "{{event.order_id}}"
}
```

*   **Liquid**: Keys and values can both contain [liquid](https://docs.customer.io/journeys/liquid/using-liquid) . If a key renders empty, renders the same as another key, or renders to a reserved name, that send fails, and delivery history shows the reason.
*   **Reserved keys**: Apple, Google, and Customer.io use some keys themselves, so you can’t use them: `aps`, `cio`, `notification`, `from`, `message_type`, `collapse_key`, and any key that starts with `cio-`, `google`, or `gcm`. Customer.io ignores case when it checks them.
*   **Other keys**: Keys named `title` or `body` are ordinary data. Your app gets them like any other key, and nothing shows on the device.
*   **Size**: Apple and Google limit the whole push to 4 KB. If your data makes the push bigger than that, the push provider refuses that send.

## Who receives a silent push

Customer.io sends a silent push to the iOS and Android devices your message targets, the same way it sends any push. Message limits, subscription preferences, and time windows apply too. An app that doesn’t handle silent pushes ignores them.

Some devices never get a silent push:

*   **Web browsers**: You can’t link a Design Studio push to a message that sends to web, like a **Web Push** action or a transactional message set to **Web** or **iOS, Android & Web**.
*   **visionOS devices**: Customer.io skips them and records why in delivery history. The devices stay on the person’s profile.

A silent push doesn’t add a message to your [notification inbox](https://docs.customer.io/messaging/channels/push/send-push/#notification-inbox), even when **Add to Notification Inbox** is on.

## Delivery and metrics

Apple and Google don’t guarantee that a silent push arrives, or that it arrives once:

*   The same silent push can arrive more than once. Our SDKs give your app a delivery ID so your developers can skip repeats.
*   Android can hold normal-priority messages while a device is idle.
*   Apple treats silent pushes as low priority and can delay or drop them. Apple’s guidance is to send no more than two or three an hour.
*   iOS doesn’t wake an app that the person force-quit. While a device is offline, Apple keeps only the newest push for your app.

Use a silent push as a signal for your app to fetch the latest state from your own systems. That way, your app catches up on anything a dropped push missed.

A silent push never reports *Opened*, since nothing appears for the person to tap. [Silent push metrics](https://docs.customer.io/messaging/channels/push/notifications-tracking/#silent-push-metrics) explains when it reports *Sent* and *Delivered*.

When you resend a silent push delivery, Customer.io sends it as a silent push again.

## Send a silent push through the API

To send a silent push with the [transactional API](https://docs.customer.io/messaging/send/transactional/push/), link a silent push to a transactional push message. Then send a request to `/v1/send/push`.

Use `custom_data` to set the data for a send. It replaces the data saved on the message. Every value must be text.

```
{
  "transactional_message_id": 44,
  "identifiers": {
    "id": "12345"
  },
  "custom_data": {
    "action": "refresh_orders",
    "order_id": "A-1001"
  }
}
```

Leave `title`, `message`, `image_url`, `link`, `sound`, and `custom_payload` out of requests for a silent message. A silent push never sends them, so a request that includes any of them creates a delivery that fails.

## Test a silent push

Send a test to an iOS or Android device token, the way you [test any push](https://docs.customer.io/messaging/channels/push/send-push/#test). Customer.io sends the test as a silent push, so nothing appears on the device. Ask your developers to confirm that your app received the data. You can’t send a silent push test to a browser.

## Replace a data-only custom payload

If you already send data-only pushes with a [custom payload](https://docs.customer.io/messaging/channels/push/custom-payloads/), those messages keep sending as they are. To move one to silent push:

1.  Create a silent push in Design Studio with the same data. In a custom payload, the iOS keys outside `aps` and the Android `message.data` keys are your data.
2.  Link the silent push to a new automation action, broadcast, or transactional message. You can’t link it to a message that already holds a push made outside Design Studio.
3.  Stop using the old message. Sends that are already queued for it go out as the old message.