Push notification troubleshooting

Troubleshooting guide for when a notification does not arrive, or does not reach who it should. Cases are ordered by symptom, from the most frequent cause to the least. Each check says how to run it.

I send one to myself as a test and it does not arrive

This is the most common case, and it almost always has one of these causes.

1. The device did not accept notifications. Without permission there is no push token and nothing to send to. How to check: on iOS, Settings › Notifications › app name; on Android, Settings › Apps › app name › Notifications. If they are off, turn them on and open the app again.
2. The app was uninstalled and reinstalled. The token changes and the old one stops working. How to check: if the device was reinstalled after the audience was built, it is not in it.
3. The device is not in the audience of the send. How to check: review the list the audience was built from, or send to the whole base to rule out segmentation.
4. The notification expired before delivery. If the device was off or offline for longer than the send’s expiry, it does not receive it. How to check: repeat the send with the device on and connected.

It arrives late

Apple’s and Google’s notification services do not guarantee immediate delivery. Before opening a ticket, check these causes on the device:

1. Battery saving on Android. Some manufacturers apply aggressive background restrictions that delay notifications. How to check: Settings › Battery, and make sure the app is neither restricted nor optimised.
2. Focus or Do Not Disturb mode on iOS and Android. Notifications are silenced or grouped until it ends. How to check: see whether a mode was active at the time of the send.
3. No connection at the time of the send. The notification is delivered when the device is back online, as long as it has not expired.

It reaches some devices and not others

1. The pattern follows the operating system. A failure only on iOS or only on Android points to that platform’s configuration. How to check: group the affected devices by operating system.
2. The ones that do not receive it have old tokens. It is normal for part of the tokens to stop being valid over time. How to check: ask whether the user uninstalled, changed phone or withdrew the permission.
3. The audience was built from a CSV exported a while ago. How to check: regenerate the list and repeat the send.

See users, devices and tokens.

Delivered or opened metrics do not add up

A send is not a delivery, and a delivery is not an open. The definitions of each metric, and why tokens are not users, are in users, devices and tokens.

The notification arrives but does not open the right content

1. The send’s URL is wrong or not public. How to check: open it in a browser outside the app.
2. The URL does not belong to a domain associated with the app. How to check: see deep links.
3. The URL has been rewritten by a tracking tool. How to check: the final link starts with a domain other than yours.

What to send to support

Write to support with this information. The more the ticket brings, the less back and forth:

• App name and environment.
• Approximate date and time of the send, with time zone.
• How the send was made: backoffice or API.
• If it was via API, the payload sent without the API key and the response received.
• One or two specific identifiers of devices that did not receive the notification.
• Operating system and version of the affected devices.
• Whether the problem is widespread or only on some devices.

For technical teams: the API send returns an error

1. Is the x-api-key header correct, and is the key still active?
2. Does the payload include the required fields: title and the recipients in deviceId?
3. If you send dateEnd, is it a Unix timestamp in seconds, and is it in the future?
4. Are the deviceId values current hashed installation IDs and not identifiers of another kind?

See push notifications API.