Notifications
Push notifications let you reach your users directly on their devices — even when they are not actively using your app. From Linkzly, you can connect your exist
Notifications
Push notifications let you reach your users directly on their devices — even when they are not actively using your app. From Linkzly, you can connect your existing push notification provider, build reusable message templates, and send targeted notifications to specific audiences, all from a single interface. You can schedule one-time sends, set up recurring messages, and deep link users directly into a specific screen in your app when they tap the notification.
The Push section is accessible from the Push category in the left sidebar. It contains eight sub-sections: Notifications, Providers, Content Library, Deeplinks, Analytics, Failed Jobs, Audit Log, and Settings. The entire feature is gated behind the pushEnabled feature flag (NEXT_PUBLIC_FEATURE_PUSH_ENABLED).
9.1 Connecting Providers
Before you can send any notifications, you need to connect at least one push notification provider. Linkzly acts as an orchestration layer on top of your provider — it does not replace your existing setup, it uses the credentials you already have. Subscriber management and audience segmentation remain in your provider.
Supported Providers
| Provider | Description |
|---|---|
| OneSignal | Cross-platform push notifications for iOS, Android, and Web |
| Firebase Cloud Messaging (FCM) | Google's messaging service for Android, iOS (via APNs bridge), and Web |
| Braze | Customer engagement platform with cross-channel campaign support |
How to Connect a Provider
- In the left sidebar under Push, click Providers.
- Click Add Provider.
- In the dialog, fill in the following fields:
Provider Type — Select OneSignal, FCM, or Braze.
Environment — Choose Production to send to real users, or Staging during development.
Credential fields by provider:
| Provider | Required Fields |
|---|---|
| OneSignal | App ID, REST API Key |
| FCM | Service Account JSON (paste the full JSON from your Firebase console) |
| Braze | Braze REST Endpoint, App Group ID, Rest API Key |
- Click Verify to test your credentials. Linkzly will confirm the connection or display an error message.
- Click Discover Apps to pull in the list of apps registered under that provider account.
- Use Select Apps to choose which apps this provider connection should manage.
- Save the connection. The provider card will show Active.
Managing Connected Providers
From the Providers page you can:
- Edit credentials — Update the API key or other credentials for any connected provider.
- Toggle active / disabled — Disable a provider temporarily without removing it. Disabled providers will not receive notifications.
- Remove a provider — Permanently disconnect a provider. Any notifications assigned to it will need to be updated.
Status indicators:
| Badge | Meaning |
|---|---|
| Active (green checkmark) | The provider is connected and operational |
| Disabled (gray x) | The provider has been manually disabled |
| Error (red alert) | The credentials are invalid or the provider returned an error |
Note on subscribers and GDPR: Linkzly does not maintain an independent subscriber database. Audiences and segments are defined and managed inside your provider (OneSignal, FCM, or Braze). Unsubscribe requests and GDPR compliance are handled entirely by your provider's native tools — Linkzly does not expose a separate unsubscribe or data deletion flow.
9.2 Creating a Notification
Go to Push > Notifications in the sidebar. The page title is Notifications with the subtitle "Create, manage, and track push notifications".
Click New Notification to open the campaign builder.
Builder: Campaign Basics
| Field | Description | Required |
|---|---|---|
| Campaign Name | An internal label for this notification. Not shown to end users. | Required |
| Select Provider | The push provider connection to send through. Only Active providers are listed. | Required |
| Select Apps | One or more apps registered under the selected provider. | Optional |
Builder: Content
Define the message content for your notification. The content section includes a live device preview panel that renders how your notification will appear on iOS, Android, and Web in real time as you type.
| Field | Description |
|---|---|
| Title | The bold headline shown at the top of the notification. |
| Body / Message | The main text of the notification. |
| Image URL | A URL pointing to an image to include as a rich media attachment. The image is referenced by URL and is not uploaded to Linkzly. |
| Add Button | Add action buttons to the notification. Each button takes a label and a URL. |
Builder: Audience
Choose who receives this notification using one of four targeting modes:
| Mode | Description |
|---|---|
| All | Send to all subscribers registered under the selected provider and apps. |
| Segment | Target a named segment defined inside your provider. Enter the segment ID from OneSignal, FCM, or Braze. |
| Users | Enter a specific list of user IDs to target. |
| Advanced | Provide a raw JSON targeting object for full control over provider-native filters (device type, locale, country, app version, custom attributes, etc.). |
Builder: Scheduling
| Option | Description |
|---|---|
| Send Now | Delivers the notification immediately after saving. |
| Scheduled | Delivers the notification once at a specific future date and time. Shows a date/time picker and a timezone selector (defaults to UTC). |
| Recurring | Repeats the notification on a schedule defined by an RFC 5545 RRULE expression (for example, FREQ=DAILY;COUNT=10). Supports an optional end date and maximum occurrence count. Full IANA timezone support is included. |
Quiet Hours — Available under Advanced Settings. Toggle quiet hours on to specify a start hour and end hour (0–23). Notifications will not be delivered during that window. A timezone can be applied to the quiet hours window independently.
Builder: Deep Link
Optionally attach a deep link to open a specific screen in your app when the user taps the notification.
| Field | Description |
|---|---|
| Select Deep Link Route | Choose a pre-configured route from the Deeplinks section. |
| Route Parameters | Enter the parameters for the route template as a JSON object. Example: {"productId": "12345"}. |
Builder: Advanced Settings
Click the Advanced Settings section to expand it.
| Field | Description |
|---|---|
| Target Platforms | Check iOS, Android, and/or Web to restrict delivery to specific platforms. |
| Quiet Hours | Toggle on to set a delivery blackout window. Enter start and end hours (0–23). |
| Deep Link Policy | Select a policy that defines fallback behavior if the deep link cannot be resolved (app not installed, route not found, etc.). |
| Select Template | Pull in content from a saved template in your Content Library. This overwrites the content fields with the template's locale-aware content. |
Builder: Action Buttons
The builder toolbar offers three actions:
| Button | Description |
|---|---|
| Save Draft | Saves the notification without sending. Status becomes Draft. |
| Send Now | Saves and immediately sends the notification. |
| Test Send (flask icon) | Opens the Test Send panel to send a test notification to a specific device before going live. |
9.3 Sending a Test Notification
Click Test Send (the FlaskConical icon) from the builder toolbar or from the ⋮ menu on any notification card.
The Send Test Notification panel lets you choose how to identify the target device:
| Target Type | Description |
|---|---|
| External ID | Your own user ID. Requires that the app has called OneSignal.login(userId) to register the ID. |
| Device Token | The raw device push token issued by APNs (iOS) or FCM (Android/Web). |
| OneSignal ID | The OneSignal-internal user ID, retrieved from OneSignal.User.getOnesignalId() in the app. |
Enter one or more identifiers (comma-separated). Each identifier appears as a removable chip. Click Send to deliver the test.
9.4 Managing Notifications
Notifications List
The Notifications page shows all your notifications as cards.
Each card shows:
- A status icon with a colored background
- The notification name
- A status badge
- The schedule type and creation date
Status badges:
| Status | Badge Label | Meaning |
|---|---|---|
draft |
Draft (slate) | Saved but not sent. Can be edited or deleted. |
scheduled |
Scheduled (blue) | Waiting for its scheduled send time. |
sending |
Sending (amber, animated spinner) | Currently being delivered. |
sent |
Sent (green) | All deliveries are complete. |
partially_sent |
Partial (orange) | Some deliveries succeeded and some failed. |
failed |
Failed (red) | Delivery failed. |
canceled |
Canceled (slate) | Manually canceled before or during sending. |
Status filter values: All Status | Draft | Scheduled | Sending | Sent | Failed | Canceled
Use the search bar to find notifications by name. Use the status filter dropdown to narrow the list.
Per-Notification Actions (⋮ Menu)
| Action | When Available | Description |
|---|---|---|
| View Details | Always | Opens the full notification detail page. |
| Edit | Draft only | Opens the builder to edit the notification. |
| Send Test | Always | Opens the Test Send panel. |
| Duplicate | Always | Creates a copy of the notification as a new Draft. |
| Delete | Draft only | Permanently deletes the notification. Cannot be undone. |
| Cancel | Scheduled only | Cancels the scheduled send before it fires. |
| Stop Sending | Sending only | Halts an in-progress delivery immediately. |
Empty state: When no notifications exist, the page shows "No notifications yet" with a "Create Notification" call-to-action.
9.5 Content Library
The Content Library is where you create and manage reusable notification templates. A template defines the title, body, image, and action buttons for a notification and supports multiple locales so you can send the right language to each user automatically.
Go to Push > Content Library in the sidebar.
How to Create a Template
- Click Create Template (Plus icon).
- In the dialog, fill in:
| Field | Description |
|---|---|
| Template Name | An internal label. Not shown to end users. |
| Default Locale | The primary language for this template (default: en). Used as the fallback when a user's device locale is not matched. |
| Fallback Chain | An ordered list of locale codes to try if the user's locale is not found. |
- Click Create to save the template shell. The template card will appear in the list.
Adding Locale Variants
Click Add Locale on a template card to add a language version. The Add Locale dialog contains:
| Field | Description |
|---|---|
| Locale | Select from: en, es, fr, de, pt, ja, zh, ko, ar, hi, it, ru |
| Title | The notification headline for this locale. |
| Body | The main notification text for this locale. |
| Image URL | A URL to a rich media image. The image is not uploaded to Linkzly — it is referenced by URL. |
| Media Type | Set to image (currently the supported type). |
| RTL | Check this box for right-to-left languages (Arabic, Hebrew). |
| Buttons | A JSON editor for defining action buttons (label + URL pairs). |
Template cards on the list page show the template name, default locale, number of locale variants, and an expand/collapse arrow to view all locales at a glance.
9.6 Deep Links
The Deeplinks section lets you define navigational routes inside your app. When a user taps a notification, the route tells the app exactly which screen to open and what parameters to pass.
Go to Push > Deeplinks in the sidebar.
How to Create a Route
Click Add Route and fill in the Create Route dialog:
| Field | Description | Required |
|---|---|---|
| Route Key | A unique string identifier. No spaces. Example: product_detail, level_select. |
Required |
| Route Title | A human-readable label shown in the route picker when building notifications. Example: Product Detail Page. |
Required |
| Route Template | The URL pattern for navigation. Use colon-prefixed tokens for parameters. Example: /product/:productId. |
Required |
| Screen Name | The screen or view name used by your mobile framework for programmatic navigation. Example: ProductDetailScreen. |
Optional |
| Parameter Schema | A JSON Schema definition of the parameters your route accepts. Used to validate parameter values at send time. | Optional |
| Supported Platforms | Check iOS, Android, and/or Web to indicate which platforms support this route. | Optional |
| Minimum App Version | The minimum app version (per platform) required for this route. Users on older versions will fall back to the deep link policy's fallback behavior. | Optional |
Click Save Route. Routes appear in the route picker inside the notification builder.
9.7 Analytics
The Analytics page gives you an aggregated view of push notification performance across all notifications.
Go to Push > Analytics in the sidebar.
Page title: "Push Analytics" Subtitle: "Overview of push notification performance and metrics"
Date Range
Use the From Date and To Date pickers and click Fetch Metrics to load data for a specific period. The default view covers the last 30 days.
Metric Cards
| Metric | Color | Description |
|---|---|---|
| Total Sent | Blue | Total notifications submitted to providers for delivery |
| Delivered | Green | Confirmed deliveries to user devices |
| Opened | Green | Taps that opened the app from the notification |
| Clicked | Green | Taps on action buttons inside the notification |
| Failed | Red | Notifications that could not be delivered |
Campaign Performance Table
Below the metric cards, a table lists each notification's individual performance:
| Column | Description |
|---|---|
| Campaign ID | Internal identifier |
| Campaign Name | The notification's name |
| Sent | Total submitted |
| Delivered | Confirmed deliveries |
| Opened | App opens from notification |
| Clicked | Action button taps |
| Failed | Failed deliveries |
Per-notification metrics can also be viewed from the notification detail page, which shows breakdowns by platform (iOS / Android / Web) and by locale.
9.8 Failed Jobs
The Failed Jobs page (accessible at Push > Failed Jobs) shows delivery jobs that encountered errors and could not be completed successfully.
Table Columns
| Column | Description |
|---|---|
| Job ID | The internal identifier for this delivery job. |
| Status | The current job status. |
| Error Message | The error returned by the provider or internal queue. |
| Created At | When the job was created. |
| Retry Count | How many delivery attempts have been made. Maximum retries: 3. |
Job Actions
| Button | Description |
|---|---|
| Replay | Re-queues the failed job for another delivery attempt. |
| Cancel | Permanently discards the job so it will not be retried. |
The delivery queue processes jobs in batches of up to 50, with a maximum concurrency of 10 concurrent deliveries. If a job exceeds the retry limit it remains in the Failed Jobs list until you Replay or Cancel it.
9.9 Audit Log
The Audit Log records every change made to your push notification configuration. This helps you track who changed what and when, which is useful for security, compliance, and debugging.
Go to Push > Audit Log in the sidebar.
Table Columns
| Column | Description |
|---|---|
| Timestamp | The exact date and time of the action. |
| Action | The type of operation performed (for example: provider.created, template.updated, campaign.deleted). |
| Resource | The type and identifier of the record that was affected (provider, template, notification, route, etc.). |
| User | The team member who performed the action. |
| Status | Whether the action succeeded or failed. |
All create, update, and delete operations on providers, templates, notifications, deep link routes, and delivery jobs are logged automatically.
9.10 Plan Limits
The following limits apply on the Free plan:
| Resource | Free Limit |
|---|---|
| Providers | 1 |
| Templates (Content Library) | 5 |
| Notifications per month | 5 |
| Push Apps | 3 |
Limits for Starter, Professional, and Enterprise plans are visible in your account's billing and plan settings.
Tips
-
Connect your provider first. The notification builder will not let you proceed without at least one Active provider connection. Go to Push > Providers and connect before creating your first notification.
-
Use the Content Library for reusable messages. If you send similar notifications to different audiences, create a template in the Content Library once and reference it in the builder's Advanced Settings. This keeps your content consistent and saves time.
-
Preview before you send. The builder's live device preview (iOS, Android, Web) shows exactly how your notification will look on each platform. Check it before clicking Send Now.
-
Always send a test first. Use the Test Send button to deliver the notification to your own device before sending to your audience. This catches formatting issues, broken deep links, and credential problems before they reach real users.
-
Quiet hours protect your users. Enable quiet hours in Advanced Settings to avoid sending notifications during sleeping or off-hours for your audience's timezone. This reduces unsubscribes and improves engagement rates.
-
Segments live in your provider. Linkzly does not manage subscribers or segments — those are defined in OneSignal, FCM, or Braze. Use the Segment audience mode in the builder to reference a segment you have already set up in your provider dashboard.
-
Recurring notifications use RFC 5545 RRULE syntax. For example,
FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12sends a notification on Monday, Wednesday, and Friday for 12 occurrences. Combine withschedule_timezoneto keep the send time anchored to the right timezone. -
Failed jobs can be replayed. If a delivery fails due to a transient provider error, go to Push > Failed Jobs and click Replay on the affected job. The system will attempt delivery again without requiring you to recreate the notification.
-
The Audit Log is your paper trail. Any time a provider credential changes or a notification is deleted, the Audit Log records who did it and when. Check this page first when investigating unexpected changes to your push configuration.
Was this helpful?
Help us improve our documentation