FAQ about push notifications

How do conversions work with push notifications?

Conversions are tracked on people, but we indicate which message drove that conversion. They’re attributed to the last email or message sent before the person enters a conversion segment. If you are tracking users performing an action or entering a segment after receiving a push, then the end-user will be marked as converted, regardless of the device we reached them on.

What Firebase permissions does Customer.io need in order to send push notications?

Firebase’s documentation says that we need the cloudmessaging.messages.create permission since we use the FCM HTTP API to send push notifications, that permission however does not belong to the Firebase Cloud Messaging Admin role. The roles that have that permission (found here) include:

  • Owner (roles/owner)
  • Editor (roles/editor)
  • Firebase Admin (roles/firebase.admin)
  • Firebase Grow Admin (roles/firebase.growthAdmin)
  • Firebase Admin SDK Administrator Service Agent (roles/firebase.sdkAdminServiceAgent)
  • Firebase SDK Provisioning Service Agent (roles/firebase.sdkProvisioningServiceAgent)

Alternatively, if you wanted to provide even more limited permissions, you should be able to define a custom role with only the cloudmessaging.messages.create permission.

How do I know if a push notification was opened?

To do this, you’ll need to add some code to your app; first, to detect when it occurs, then to send an event to our API. We are not able to automatically track the “Opened” metric yet. You’ll need to include the CIO-Delivery-ID and CIO-Delivery-Token parameters from the push, as documented in our Technical Integration Guide.

How do I know if a push notification failed because the app has been uninstalled?

Push notification services don’t provide a reliable way of detecting this with absolute certainty. However, when you look at a push notification’s status, getting a Bad Device Token error for a device is a reasonable indicator that this particular person no longer has the app installed.

Is there a character limit or best practice?

Because push notifications go to so many devices, their text might get cut off at different points. What looks great on an iPad’s lock screen might get awkwardly truncated in a Pixel’s notification center.

As devices and operating systems change, so do the number of ways a push notification can be seen. The only concrete restriction is a message size limit: 4KB (4096 bytes) for both Apple Push Notification service (APNs) and Android’s Firebase Cloud Messaging (FCM). This isn’t just for the message text, but for the entire payload— this includes any other custom data being sent along with that notification.

Tip: To reduce payload size, omit whitespace and line breaks!

To make sure your notifications are as successful as possible, we encourage you to:

  • Keep it brief! A good general guideline is to make it actionable and beneficial in less than 40 characters.
  • Test them! This way, you can see how they’re appearing in the wild, and make them shorter if you need to.

I’ve set up push for iOS, but am getting an invalid token error!

You might be receiving an error that looks like this:

Invalid device token (APNs BadDeviceToken)

This means that Apple doesn’t recognize the token you added via our updateDevice API call as valid for that app or environment. There are a few reasons why that might occur:

  • You are using an incorrect token for that particular end-user, or an old token that no longer exists.
  • Your app is built using the development configuration rather than production. Device tokens are unique to each environment and today, we only support the production environment.

Device tokens can also be rotated by Apple for several reasons, one of which is the end-user reinstalling the app or updating their OS. Due to how frequently these tokens rotate, our recommendation is to send us an updateDevice API call every time your app is launched to ensure that we’ve always got the latest device token.

To fix it, confirm that:

  1. The iOS .p8 app certificate you’ve uploaded is the same one that’s in use for the app that generated the device token. Device tokens are not re-used - they’re unique to the app and certificate.
  2. The device token is for the production environment, not using the development/sandbox environment.
  3. You’re attempting to send to the most recently generated device token. Once a new token has been generated, the old one will fail.

If you’re still getting this error, get in touch with us at win@customer.io.

How is the last used device determined?

A given user’s “last used device” is the device they last used to access your app. It’s determined by the timestamp in the most recent identifyDevice API call. We recommend calling this every time your app is launched to keep the “Last Used” value up to date.

This is sometimes a friendlier way of targeting people rather than sending to every device they own, because it means they only receive one message.

How do I know that a person saw or dismissed the push notification?

iOS and Android’s push notification services don’t generally provide this information. There are some platform-specific ways to add code to your app to detect that a notification was received when the app is in the foreground or background. However, this won’t catch notifications received when your app isn’t running.

You can do this with our custom payloads feature right now, by using raw JSON code. It’s not available in the UI just yet, but is on our roadmap for the feature! Get in touch and tell us what you need! We’re looking to hear more about the types of content you need in the push notifications you’ll be sending.

How should I set up testing?

We recommend that you set up a separate Workspace for testing your push notifications, even if (in the case of iOS, for example) you use the same configuration credentials for testing and production.

If you have different versions of your app, notifications will be routed correctly based on the device ids each apps sends to Customer.io which should be unique per app. If you choose to use separate workspaces per version of your app (e.g., dev/staging/production) then each version of your app should ensure that it registers devices in the proper Workspace per your needs.

How do I find a device token so I can send a test push from the composer?

Device tokens are located on an individual’s Person page:


Find them by searching for a specific person to whom you’d like to send the test, and then heading to the Devices tab. You can then quickly copy and paste the token for the device you’d like to send to by clicking the clipboard icon on hover.


How do I target a test version of my app?

To do this, we recommend that you create a new workspace, in which push notifications are configured with the certificates for your test app. You can also swap the certificates in your configuration.

Can I send to iOS via FCM/Firebase?

Yes, you can! You will see this option in your iOS configuration:


It will be available for you if you have not set up Android as well. If you select this option, you will still need to setup the configuiration for Android if you haven’t yet done so.

Whether or not you should do this depends entirely upon your setup and what’s easier for you. For example, if FCM is a critical part of your infrastructure, and you don’t plan on configuring the Apple Push Notification Service anytime soon, this may be a valuable option.

I want to send push notifications only to Android/iOS. How?

On the push notification workflow item, you’ll be able to select a specific platform:


A push notification with a platform specified here will only be sent if a customer has a device with that platform!

I need [FEATURE]! When will you add it?

If you find that push notifications are missing a critical feature, let us know what it is, and what kind of messages you’d like to send using it. As an intermediate workaround, webhooks are really powerful!

Copied to clipboard!