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:

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.
• Your account needs multi-app support, which sends one delivery to each device.
• You create silent pushes in Design Studio.

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.
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 . 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, 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 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, 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. 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, 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.