Troubleshoot push notifications

Trace one test notification from its audience or API request to the destination screen. Record its message or campaign ID, channel, contact, app version, platform and time. Keep tokens and access keys out of shared logs. Reconcile the original send before retrying an uncertain outcome.

The test contact is not selected

Inspect the campaign's list or segment, suppression settings and recipient limit. Confirm the selected contact has a current Push identifier for this channel and the intended campaign subscription preference. An email address or contact record alone is not a Push destination. Follow identity and subscription setup.

For a direct API send, check receiver.contacts[].identifierKey is push-{channelId}, with the same channel ID as the URL. The value must start with firebase:, apns: or web: and contain the current token for that gateway. A OneSignal subscription ID, Firebase installation ID or bare customer ID is not interchangeable with that destination.

The campaign runs, but no notification appears

Inspect the original message with GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId} using Authorization: AccessKey .... The first-notification example includes the command. Read status and the public API's failure.code, failure.description and failure.source when present.

Evidence	Check	Next action
API request rejected	Workspace/channel ID, AccessKey authorization and JSON body.	Correct the request; retain the failed attempt in your test record.
Send fails with a destination-format error	Channel-scoped key and gateway prefix; preserve internal token colons.	Use the client's current registration in the documented receiver shape.
Send fails with an empty message body	Push uses body.type: "list", with list.title and list.text.	Replace a generic text body with the Push list shape.
Gateway credentials rejected	FCM project/service credentials, APNs identity/environment or Web Push configuration.	Match credentials and destination to the installed app environment.
Expired or invalid destination	Current SDK registration and account association.	Retire the stale value; obtain a fresh registration before another useful send.
Accepted or sent, but no visible notification	Device permission, connectivity, OS settings, app handler and browser worker.	Inspect the receiving device; provider acceptance does not prove presentation.
Response lost or receipt absent	Original message ID and available send history.	Keep outcome unknown until reconciled; absence alone does not authorize another send.

For web, confirm HTTPS or localhost, the configured service-worker file, its origin/scope and a granted browser permission. Check the developer console for SDK initialization or VAPID errors. On iPhone/iPad, test the installed Home Screen web app. For a campaign, a simulated-contact preview checks content but does not establish delivery to a device.

It appears in one app state but not another

Test foreground, background and a cold start separately. On iOS, connect the SDK's foreground presentation, background and notification-response delegates, plus the configured extensions. On Android, verify the Bird messaging service and notification permission/channel settings. Bird's FCM path can carry notification content in a data payload; a custom handler that only reads remoteMessage.notification may miss it. Follow the SDK setup rather than assuming the behavior of a Firebase console notification.

On web, inspect the active service worker and the SDK interaction event. A Received event is not a tap. Check whether your app and SDK both render or navigate, causing duplicates. Follow deep-link handling.

The wrong account receives a notification

Pause account-specific traffic to the affected installation. Inspect its contact identifier before and after sign-out, the new signed identity and the current registration. Local identity reset alone does not detach a remote Push identifier. Reproduce with two test accounts, and verify A's private test notification cannot reach the device after B signs in. Use the logout sequence.

Also test one customer on two devices: retiring the shared installation must not accidentally change a contact-wide campaign preference for the other device. Keep unresolved offline cleanup in your application's work queue.

The notification opens the wrong screen

Inspect the configured tap action, the actual URL/deep link, the launch intent or notification response and the app's sign-in redirect. Confirm that a cold start retains the destination and that the server authorizes the signed-in customer. Reject unknown routes and hosts; show a useful state for deleted or changed records. Verify the destination before sending another campaign.

If the technical path works but the notification is unhelpful, review copy, timing and design. A tap should lead to the action promised by the title and body. Return to Push resources.