Push - Common Issues & FAQ

LAST EDIT Dec 21 2021

Delivery Condition Not Matched


Most of the time, not receiving push notifications results from a use case that the API does not handle. Our current API implementation supports push notifications under specific cases:

  • The target user must be offline.

  • The target user has at least one device registered with the Stream App.

  • The target user is a member of the channel that will send notifications.

  • The target user has not muted the channel the pushed message is from.

  • The target user has not muted the user that created the pushed message.

  • The channel has less than 100 members.

  • If using thread, the user is part of the thread that messages are sent in (i.e previously posted at least one message or were mentioned in that thread)

If one of these conditions is not met, then the API will not trigger any push. As a result, you will not receive any push notification AND you won't see any data on this push notification attempt in the Dashboard Push Logs.

Device Registration


At least one device must be registered for a specific user in order to receive push notifications. This is also a push delivery condition and  a mandatory step in the push integration logic.

One of the common reasons for not receiving a push notification on a device is the absence of a device token. Without this, a device cannot be registered on the Stream database. Note: if this is the issue, it will not be reported in the Dashboard Push logs.

This is why we recommend testing your push integration using the Stream CLI tool first, as it runs some checks such as having a registered device. You can learn more the CLI tool here.

You can also check if a device is registered by retrieving the list of devices for a given user.

Token Invalidation


Push provider Token, or much commonly known as a registrationToken is a unique token string that is tied to each client app instance. The registration token is required for single device and device group messaging.

An existing registration token may cease to be valid in a number of scenarios, including:

  • If the client app unregisters with FCM.

  • If the client app is automatically unregistered, which can happen if the user uninstalls the application. For example, on iOS, if the APNs Feedback Service reported the APNs token as invalid.

  • If the registration token expires (for example, Google might decide to refresh registration tokens, or the APNs token has expired for iOS devices).

  • If the client app is updated but the new version is not configured to receive messages. For example, any configuration/credentials changes from your FCM project would lead to all devices being in an invalid state and should be re-added (ex: APN development/production mode)

Usually, when facing this issue, the Push Logs should report an Unregistered error (i.e your app instance was unregistered from FCM). This usually means that the token used is no longer valid and a new one must be provided.

For all these cases :

  • Check that push configuration is up-to-date,

  • Check your refresh token logic (sometimes integration issues can lead to the device not being registered with the latest token retrieved from the library).

  • You will need to remove this existing registration token from the Stream (i.e Remove Device) and stop using it to send messages

  • Add a new valid registration token for that device (i.e Add Device).

User Offline/Online Transition


Stream API supports user presence changes and provides offline/online statuses for users. Push notifications are only sent when a user does not have an active Websocket connection (i.e they are offline).

However, when your app goes to the background or is killed, your device will keep the Websocket connection alive for up to 1 minute. This means it can take up to 1 minute for the API to consider the user offline, and during this time the device will not receive any push notifications.

The general best practice for handling this edge case is to set up local push notifications to trigger push notifications when the Stream API Push system cannot (i.e delivery conditions are not met). Some of our mobile SDKs provide the background disconnection logic out-of-the-box and examples. It will ultimately be up to you to implement local push notification logic as you see fit.

Push Provider Drops Notification


Considering the above section on Push Logs, the dashboard reports the FCM response, but not the device response itself.

Therefore, there are cases where the dashboard reports push notifications have been successful (i.e. 200 responses), but you are still unable to see any push notifications on your device. In general, this behavior relates to FCM dropping the push notification after receiving and accepting the request.

When receiving a push request from Stream, APN and Firebase:

  1. Run protocols to validate it based on the authentication information (credentials, device ID, etc...) and format of the request.

  2. Send an HTTP response with status to Stream. See possible errors: https://getstream.io/chat/docs/push_logs/

  3. Run further checks such as Message (payload) data & format.

If the notification message generated from configured templates and data does not respect the format or has wrong data, the FCM provider will drop the notification. Also, in this case, the FCM provider does not send any information to Stream.

Related issues are mostly due to a bad template configuration.

Please note that you can still detect those issues or find more details about them from your FCM project console (Firebase/APN).

Template issue


The majority of issues that are visible to Stream and still prevent devices from receiving push notifications are due to providers dropping the notification. Usually, those are related to a template issue (notification or data).

Both Firebase and APN have specific protocols and payload keys. You need to ensure the Android data and notification template, respectively APN template will reflect and respect the keys values, types, objects format. For example, common issues are :

  • APN : Key type mismatch - e.g set template with {...,“badge”: “{{ unread_count }} “,...} is wrong. According to APNs docs, the "badge" key should be a Number(integer), however, once {{unread_count}} replaced, it will render the following : {...,“badge”: “1“,...} . In this case, APN will drop the notification without notifying 3rd party services like Stream API.

  • Firebase : Wrong data passed -According to Firebase docs e.g the "click_action" key refers to the action associated with a user click on the notification. By default set to "click_action":"OPEN_ACTIVITY_1", but if referencing a custom activity, you need to make sure it exists in your project. Otherwise, Firebase might drop the notification.

Please note that the Stream Dashboard and API do not apply any checks regarding your notification templates but only ensure the rendered template respects JSON format. In addition to the APN docs and Firebase docs, you can also refer to our Push template documentation section with detailed information and examples for configuration.