Once you have successfully integrated the SDK, you are now ready to create your first Push Notifications. 
In this article, we will walk through the steps to create Push Notifications for each notification type.

Getting Started

Depending on the Push Notifications Type you want to create (One-time, Automated, or API Notifications), click the tab (e.g., One-time notification), then click the + New Message button in the top-right corner of the page.

Creating One-Time Push Notification

Info & Targeting

In this step, give your notification a name, select the target platform(s) (Android, iOS, or both), and choose a targeting method:

• All push-enabled users: Sends the notification to all users who have opted in to push notifications on the selected platform. The estimated audience size is displayed once this option is selected.
• Use segmentation: Narrows your audience using one or more of the following filters:
  • Cohort(s): Targets all users within the selected Cohort(s).
  • Geolocation(s): Targets users within specific geographic areas. This option is only visible if the Geolocation feature is enabled. See here for more details.
• When to determine the users: Choose whether to calculate the target audience now or at send time. 

Delivery

The Delivery step is where you configure when and how your notification is sent.

• Send Now: Sends the notification immediately after setup is complete
• Schedule for Later: Sends the notification at a future date and time. Selecting this reveals the following options:
  • Timezone: Controls when users receive the notification:
    • Deliver to all users at the same time: The notification goes out at a single chosen time, regardless of each user's location.
    • Deliver in the user's local timezone as per device timezone: the notification is sent when the user's device reaches the specified time. Requires Countly SDK version 16.12+ (iOS and Android). If the SDK hasn't reported a timezone yet, Countly falls back to the app's default timezone.
  • What if the user is past the scheduled time? Only applicable when using local timezone delivery. If a user's timezone has already passed the scheduled time, you can choose to either skip them or deliver the notification the following day at the same time.
  • Expiration Time: The expiration time indicates the number of days after which push notifications that have been undelivered due to device connectivity issues or other errors will stop retrying delivery.

Push Content

This step is where you compose the notification itself, including messaging, media, localization, and buttons. Many fields adapt based on your platform selection and other choices made in this step. Each field below that needs to be filled remains the same for all notification types.

Notification Format

Notifications can be of two types: Content Message and Silent Notification. 

• Content Message: A visible notification that the user can see and interact with.
• Silent Notification: A data-only notification with no visible message or sound. Used to wake the app in the background and refresh its data without the user seeing anything.

Message & Media

• Message Title (optional): A short title is displayed above the message body.
• Message Text (required): The main notification body, limited to 4,096 characters on Android and 2,048 on iOS.
• Button URL: You can add up to two buttons, each with a label and a URL. Buttons are optional, and if none are added, users will see only the text message.
• Media URL: Attach an image or media file to the notification. iOS 10+ supports full media attachments; Android supports images only; iOS 9 has no media support. If media isn't supported on the user's device, only the message text is shown. This URL applies to both platforms unless overridden in Platform Settings.

Personalization with Variables

Notifications can be personalized for each recipient using variables pulled from Countly User Profiles, including default, custom, and external properties.

To add a variable, click Add Variable in the message title or body and select the property you want to insert (e.g., first name, company). You'll also need to set a Fallback value for cases where the user doesn't have that property set.

Built-In Message Localization

Push Content includes built-in localization support. You can customize the message for each available language. If no localized version exists for a user's language, it falls back to the default message.
 

Platform Settings

Customizable settings for Android:

Customizable settings for iOS:

Review

In this step, you can review all the details that you have added in the previous steps. 

If you wish to edit anything, click the Previous Step button, make the necessary changes, and move on to the next step until you reach the review step. 

You can also run a test at this step. Each field below that needs to be filled remains the same for all notification types.

Testing your notification

You can send messages to test users on the production app by setting up test users in Push in Settings. You can define test users by adding user IDs or selecting cohorts from the provided list. The number of test users is shown in the review step.

Debugging

There are situations in which an issue may occur during Push Notification transmission. In those cases, you can enable this option, which will keep individual push records for each user and store them under the countly.push_stats collection in the database. This can come in handy for debugging the issue. 

Confirmation

At this stage, your next steps are determined by whether Push Approver is enabled or not, as follows:

• If the Push Approver plugin is not enabled: When you check the confirmation message, the Complete button is enabled, the message is created, and the process is completed. Or you can save the notification by clicking the Save as Draft button. 
• If the Push Approver plugin is enabled: When you check the confirmation message, the Send for Approval button is enabled, the message is created, and the message is queued for approval. Alternatively, you can simply save it by clicking the Save as Draft button.

Creating Automated Push Notifications

Info & Targeting

In this step, give your notification a name and select the target platform(s) (Android, iOS, or both).
 

You can enable Geolocation targeting to restrict delivery to users within specific regions. If enabled, use the dropdown to select the targeted areas.

Additionally, instead of Targeting like in the One-Time notifications setup, automated notifications are driven by Triggers, conditions that determine when the notification fires:

• Cohort Entry: Triggered when a user enters any of the selected cohorts.
• Cohort Exit: Triggered when a user exits any of the selected cohorts.
• Performed Event(s): Triggered when a user performs specified Events.

Depending on the trigger selected, you may need to fill in one or more of the following:

• Delivery Date Calculation: Determines the reference point for scheduling delivery. Choose between Relative to the date the event arrived at the server or Relative to the date the event occurred on the device.
• Behavior when trigger condition is no longer met (Cohort-based triggers only): Controls what happens if the trigger condition changes after the notification is queued:
  • Send anyway: Resends the notification each time the user enters or exits the cohort.
  • Cancel when user re-enters selected cohort(s): Sends only on the first entry or exit, and cancels if the condition is met again.
• Select Event(s) (Performed Event(s) trigger only): Use the dropdown to select one or more events that will fire the notification.

Once complete, click Save as Draft to save your progress, or Next Step to continue.

Delivery

Automated Push Notifications offer different delivery options than One-Time notifications. Here's a breakdown of each setting:

• Delivery Timeframe: Sets the active period for the campaign. Choose when to start (Start Now or Schedule) and optionally set an End Date, after which the server will stop sending this notification.
• Campaign Delivery Method: Controls when the notification is sent after the trigger fires:
  • Immediately: Sent as soon as the triggering cohort is recalculated.
  • Delayed: Delivery is postponed until a specific day and hour that you define.
• Delivery Time (optional): If enabled, restricts delivery to a specific time of day selected from the list.
• Capping: Controls how frequently a single user can receive this notification, helping avoid over-messaging:
  • No capping: The notification is sent every time the user entered to or exited from the cohort.
  • Capped: Limits how often a user receives the notification. Requires the following:
    • Maximum messages per user: The total number of times a user can receive this notification over the campaign's lifetime.
    • Minimum time between messages: The user must re-trigger the campaign conditions after this period has passed before they become eligible again.
• Expiration Time: The expiration time indicates the number of days after which push notifications that have been undelivered due to device connectivity issues or other errors will stop retrying delivery.

Content & Review

Creating Transactional Messages via API

API Notifications, or Transactional Notifications as they are also known, can be created via the Countly dashboard or via an API endpoint. Let's go through both options and see how to create an API notification.

Creating an API Notification via the UI

The four steps for creating an API notification through the UI use the same settings and options as when creating a One-Time notification. Please refer to the section here for more details about the four steps: Info & Targeting, Delivery, Push Content, and Review. 

The notification you just created will show up in the notifications table with a Scheduled status. In this state, the notification won't be sent to any users. After creating the API notification, you'll need to add users. To do that, call the API endpoint /i/push/message/push. 

• _id of the notification you have created;
• start to define the start date when to send the notification on;
• filter is used to define the specific user groups who will receive the notification. It could be a specific user, cohorts, etc. 

Example:

{
    "_id": "69c6b8a6d0ae09b35c17a1f1", // messageID of your new API notification
    "start": "2026-03-27T17:03:26.471Z", // date to send the PN
    "filter": {
       "cohorts": ["6af1d6fe101086dce03f627511aac384"] // target cohort to send PN 
    }
}

Creating an API Notification via API Endpoint

Create a Notification by calling the /i/push/message/create endpoint. Fill in the request JSON body just as you would with regular notifications. 

Example: 

{
  "app": "6824d4fafd2e42cb25e1a692", // your app ID
  "platforms": ["i"], // platforms "i" for iOS and "a" for Android
  "triggers": [
    {
      "kind": "api",
      "start": 1774656695,
      "delayed": false
    }
  ],
  "contents": [
    {
      "message": "Testing",
      "title": "API Notification!"
    }
  ],
  "filter": {
       "user": "{\"did\": \"1a920a94-fb27-2d64-c075-224a54cc25fe\"}"
    }
}

Then, add users to this notification by calling /i/push/message/push:

• _id of the notification you have created in the first step;
• start to define the start date when to send the notification on;
• filter is used to define the specific user groups who will receive the notification. It could be a specific user, cohorts, etc. 

Sending Push Notifications for selected Geolocation(s)

Countly can send messages to users located in an area defined by a circle in Countly. By default, the Countly SDKs determine users' locations using the GeoIP database. If your app uses GPS or can provide better location accuracy, you can call the Countly SDK's setLocation method of your choice to provide a better location.

To define the locations that are used while sending push notifications, go to Locating Targeting in Sidebar > Management. Here, you can create new locations by providing the location name, the location on the map, and the radius around the location that should contain the target audience for your push notification. Optionally, you can also limit the location to a single application. For more information, review the Utilities User Guide.

Push Approver

Ensure that the Push Approver feature is enabled under Management -> Feature Management -> Push Approver:

The Push Approver feature allows a 2-step procedure for sending push notifications:

1. Create a notification and save it for approval
2. Approve this notification, effectively sending it right away, or scheduling it for a specific date specified during the Push Notification creation.

Without Push Approver enabled, Countly allows any user with User access to see notifications and any Global Admin to create and send notifications. To make this 2-step procedure possible, the Countly user role system introduces another role - Push Approver.

After creating the notification, a user with the Push Approver role will log in and see notifications waiting for their approval located in the standard table of messages, which they can approve or delete:

The Push Approver role only grants the ability to approve notifications. It does not allow the user to create them. To view notifications for a specific app, the Push Approver must also be a User of that app.

A notification cannot be created and approved by the same user. If multiple Push Approvers are registered, Push Approver 2 can approve notifications created by Push Approver 1, and vice versa.

A Push Approver who is also a Global Admin can create notifications, but these will still be placed on hold and require approval from another Push Approver.

Once the Push Approver feature is enabled, the Complete button is replaced with Send for Approval for all users who can create notifications. Meaning no notification is sent immediately, as it waits for a Push Approver to review and send it.

Troubleshooting & FAQ

For common issues, error codes, and frequently asked questions about push notifications, see our dedicated troubleshooting page: