Swift SDK Migration Guide is live —
Start your upgrade here
Netmera Docs

Notifications

Managing Devices and Notifications with Netmera Rest API

Welcome to the REST API documentation for managing devices and notifications in our system. This section provides comprehensive information on how to seamlessly register, unregister devices, send notifications, and retrieve essential device and notification details through our REST API.

Mobile Bulk Notification

Web Bulk Notification

Bulk Notifications with Features

Transactional Notification

Transactional Notifications with Features

Push Stats

Get Push Result

Geofence

Email

SMS

Inbox Feature

Mobile Bulk Notification

Send Bulk Notification

Following request is the minimal required parameters to send push notification.

curl -X POST \
-H "X-netmera-api-key: your_rest_api_key" \
-H "Content-Type: application/json" \
-d '{
  "message": {
    "title": "Push Notification Title",
    "platforms": ["IOS", "ANDROID"],
    "text": "This is the push notification text!"
  },
  "target": {
    "sendToAll": true
  }
}' \
https://restapi.netmera.com/rest/3.0/sendBulkNotification
Parameters

  • title (Required):

    • The campaign's name, aiding in the identification of notifications on the panel.

  • platforms (Required):

    • Specifies the platforms for push notification delivery.

  • text (Required):

    • The message content of the push notification displayed to the user.

  • target (Required):

    • The designated recipients for the push notification. If the sendToAll value is set to true, the notification will be dispatched to all users selected for the specified platform. For more intricate targeting options, refer to the advanced targeting section below.

Parameters

  • title (Inside Message Block):

    • Provides the campaign name within the panel for organizational purposes.

  • title (Inside iOS and Android Blocks):

    • Returns the title specifically for the push notification on iOS and Android platforms. This allows customization of the notification title on different operating systems.

Carousel Push

Slider Push

Parameters

  • Given:

    • Creation of a push to be sent via the Send bulk notification service via Postman

When:

  • Label information is added to the message.

  • Then:

    • The push notification is sent.

  • And:

    • Confirmation is observed as the label field appears in the push report generated on the panel.

Multilanguage

Custom Button

Warning:

  • It is crucial to create buttons initially in the panel under Settings > Button Sets.

  • Note that the "Button Name" is not mandatory.

For platform-specific deliveries, kindly specify separately for the desired browsers, including Android, iOS. This ensures accurate and tailored delivery based on the user's browser environment.

Android Live Push Update

An Android Live Push Update refers to the process of dynamically updating or modifying a push notification that has already been sent to users' Android devices. Unlike traditional push notifications that are static and cannot be changed once sent, a live push update allows developers to make real-time adjustments to the content or context of a notification even after it has been delivered to users.

  1. First send a push notification to your users using the provided sample code:

  1. Once the notification is sent, save the NotificationKey shown in the response.

  1. To modify the notification, add "refID": "NotificationKeyValue" inside "customJson": {. This change allows for different notification scenarios.

Android Live Push Update with Sound

Notification Grouping

Notification grouping allows push notifications from the same platform to be organized within the notification center. Using the thread-id parameter, notifications related to a specific category or event can be grouped together. This ensures a cleaner, more user-friendly experience by preventing notification clutter.

Supported Platforms: iOS, Android

  • By assigning the same thread-id to related notifications (e.g., "matchUpdates"), the notifications can be grouped together in the notification center. Users can expand the notification to see all updates within that group.

  • The sendBulkNotification and createNotificationDefinition services support the thread-id parameter for grouping notifications.

API Request Example

Use the following API request to send a grouped push notification:

Parameters
Parameter
Type
Description

title

String

Notification title

platforms

Array

Target platforms (iOS, Android)

text

String

Notification content

threadId

String

ID used to group notifications

sendToAll

Boolean

Whether to send to all users

Web Bulk Notification

Send Bulk Web Notification

Parameters

  • title (Required):

The name of the campaign, aiding in the identification of notifications on the panel.

  • text (Required):

The push notification message displayed to the user.

  • wpChromeImage:

For Windows Chrome and Firefox users, this parameter specifies the URL of the image to be displayed in the notification. The URL must begin with "https."

  • iconUrl:

Required if the platforms include Chrome or Firefox. Specifies the URL for the icon associated with the notification.

  • interactionRequired:

A boolean indicating whether the notification should persist until the user interacts with it, either by clicking or dismissing. The default value is false.

  • personalizedTitle

This field is provided and the corresponding profile attribute exists for the user, the Web push notification's title is set to the value of personalizedTitle. If the attribute is not set on the user, the notification will not be sent.

Custom Button

Warning:

  • It is crucial to create buttons initially in the panel under Settings > Button Sets.

  • Note that the "Button Name" is not mandatory.

For platform-specific deliveries, kindly specify separately for the desired browsers, including FIREFOX, EDGE, MACOS, and CHROME. This ensures accurate and tailored delivery based on the user's browser environment.

Bulk Notifications with Features

Bulk to Tag

Bulk to Multiple Tags

Users with any of the given tags will receive notification.

This is similar to:

If you use $and instead of $or, users with all of the given tags will receive notification.

Submitting notifications using the "or" logic of the attribute value in transactional pushes.

If you use $not, users who don't have any of the given tags will receive notification.

Bulk to Segment

Bulk to Multiple Segments

Users with any of the given segments will receive notification.

This is similar to:

If you use $and instead of $or, users with all of the given segments will receive notification

If you use $not, users who don't have any of the given segments will receive notification.

Bulk to Profile Attribute

With the request above, you can send notification to Female users who set language as English or Turkish. You can set one or more profile attribute. Notification will be sent to users who satisfy all attributes.

Bulk Personalized Push

With the request above, you can send personalized notification to users who have profile attributes which placeholders exists in personalizedMessage field. For example, a user has name attribute equals Susan and surname as Smith. She will receive that message as "Susan, Smith". If a user does not have any of name or surname attribute, they will receive the default message as "push text!!".

Bulk to Specific Location

Parameters

If you include location under the target, the following details are required:

  • latitude (Required):

    • The latitude of the center point.

  • longitude (Required):

    • The longitude of the center point.

  • radius (Required):

    • The radius value, in kilometers, from the center to search for users. This parameter determines the geographical area for targeting users based on their location.

Bulk with Category

When sending a notification with categories, keep in mind the following:

  • Category Definition:

    • Categories should be pre-defined in the panel. Ensure you create categories under the Settings/Message Categories menu.

  • Category Inclusion:

    • You can set a single or multiple categories for your notification.

Note: Make sure to define categories in the panel before attempting to use them in your notification. Categories provide a way to organize and classify your notifications for more targeted delivery.

Bulk with Sound & Vibration

When sending a notification with sound and vibration, consider the following steps:

  • Sound Definition:

    • Sounds must be pre-defined in the panel. Define your sounds under Developers/Sounds menu.

  • Platform-specific Sound Setting:

    • Set sounds for each platform accordingly. This ensures that the appropriate sound is played based on the user's device platform.

Note: Ensure that the sounds are defined in the panel under Developers/Sounds before attempting to use them in your notification. This allows for a customized and platform-specific audio experience for users.

Parameters

  • sound (Optional):

    • The name of the sound, as defined in the panel. Sounds should be added by platform. Include this parameter to specify the sound associated with the notification.

  • vibration (Optional - Android Only):

    • For Android, this parameter determines whether to enable or disable vibration when a device receives a push notification. Include this parameter if you want to control the vibration behavior on Android devices.

Bulk with Badge

Badge only for iOS:

  • Badges are enabled only for iOS. This means that the badge functionality is applicable and recognized on iOS devices.

Bulk with Badge Count

Bulk with Deeplink

  • Deeplinks:

    • You can add a deeplink to your notification, enabling you to redirect users to a specific view or content after they click on the notification.

Bulk with URL

  • URL Inclusion:

    • Add a URL to your notification, allowing you to open a landing page in a default web view after users click on the notification.

Bulk with "Do Nothing" Option

By including the "Do Nothing" option in your notification, you can override the automatic click handling mechanism, specifically on Android. With this option:

  • Custom Click Handling (Android Only):

    • No automatic click handling mechanism will be applied. Instead, you need to implement a custom click handler for Android.

Bulk with Rich Media

To send a notification with rich media content, utilize the following request, which allows inclusion of title, subtitle, and different types of media based on the platform:

  • Title and Subtitle:

    • Include title and subtitle in your notification.

  • Rich Media:

    • For Android, include an image. For iOS, include an image, sound, or video.

Bulk with Custom Parameters

To customize your notification further, consider adding custom parameters with the following request. These parameters can then be utilized on the device when the push notification is received.

  • Custom Parameters:

    • Include additional custom parameters to enhance the information or actions associated with the notification.

Bulk with Scheduled Notification

To schedule a notification for a future date, use the following "schedule" configuration in your request. This allows you to specify the date and time when the message should be delivered in the future.

Bulk in Packages

To send messages in chunks or packages, utilize the following "speed" configuration in your request. This allows you to control the rate at which notifications are sent.

Other parameters

Parameters

  • extRef (Optional):

    • External reference of the push notification. This is an identifier of the notification in your system. You can assign any id to a notification and query by that id later on.

  • limit (Optional):

    • The maximum number of users to whom the notification will be sent. If you have, for example, 1 million users and set the limit as 100,000, the notification will be sent to 100,000 users selected randomly. Additionally, as shown in the example, limits can be set by platform.

  • ttl (Optional):

    • Time to live value of the notification. If any target device does not receive the notification within the given period, it will never be received. Example usage: 15d means 15 days, 20h means 20 hours, and 30m means 30 minutes.

  • inbox (Optional):

    • A boolean value that determines whether to display the push notification in the inbox or not.

  • doNotNotify (Optional):

    • A boolean value that determines whether to show the push notification on the notification center or not.

Set Profile Attribute or Tag with Button Set

Integration Requirements:

For the successful execution of this feature, the button click action must be set as "Open App". The set attribute or tag operation will be triggered after the push open event within the application module.

Sample request for the setProfileAttribute feature in the sendBulkNotification

Sample request for the setProfileAttribute feature in the createNotificationDefinition

Sample request for the setTag feature in the sendBulkNotification

Sample request for the setTag feature in the createNotificationDefinition

Platform-Specific Click Actions in Bulk Notifications

Netmera provides the flexibility to define platform-specific message content and click actions when sending bulk push notifications. This allows you to tailor the user experience for different platforms such as iOS and Android within a single API request.

Example Request

Explanation

  • platforms: Defines the platforms to which the notification will be sent.

  • click: Provides a default click action for platforms where platform-specific values are not defined.

  • ios, android: Platform-specific overrides. You can define custom title, text, and click objects under these keys.

Supported Click Actions

You can customize the click behavior per platform using the following action formats:

1. Open a URL

  • Opens a web page in the device's default browser.

  • Supported on both iOS and Android.

2. Open a Deeplink

  • Launches your app via a registered deeplink URI.

  • Ensure the deeplink is configured correctly in the app.

  • Supported on both iOS and Android.

3. Do Nothing (Android only)

  • No action will be triggered when the user taps the notification.

  • Supported only on Android.

Transactional Notification

Transactional notifications refer to pre-configured messages from the panel that can be specifically sent to individual users.

Maximum 1000 Unique External IDs or Device Tokens in a Single REST API Request:

When initiating a request, it's crucial to note that a maximum of 1000 unique external IDs or Device Tokens can be included in a single REST API Request. This limitation ensures the efficiency and proper handling of requests. If there are more than 1000 different external IDs or Device Tokens, it is necessary to distribute them across multiple requests. This approach is designed to uphold the performance and reliability of the API.

Custom Parameter Overwrite Risk:

If a custom parameter is provided in the request and differs from the parameter existing in the panel, it will overwrite the pre-existing parameter. This emphasizes the importance of alignment between the provided custom parameters and those configured in the panel to avoid unintended parameter overwrites.

Single Request:

Single Request with Device Token:

Parameters

  • notificationKey (Required):

    • This is the key identifier for the specific notification intended for a user. The notification key is created and can be obtained from the panel.

  • target (Required):

    • Specifies the target user to whom the notification should be sent. For transactional notifications, this can be the external ID (extId), an identifier in your system previously associated with a specific user.

  • message.params (Optional):

    • Custom parameters for tailoring a notification to a specific user. In the case of transactional messages, the text can be customized for individual users. For instance, if you want to send a personalized message like "Hello John" or "Hello Mary," you can configure your message as "Hello @{name}" and include the "name" parameter in your transactional notification request. This allows dynamic content based on user-specific information.

In chunks (for different notifications or parameters):

In chunks with device token (for different notifications or parameters):

In chunks (for the same notification and parameters):

In chunks with device token (for the same notification and parameters):

Notification Definition

A transactional notification definition can be created either through the Netmera Panel or via a specific request.

Parameters

  • Title (Inside Message Block):

    • When located within the message block, this parameter provides the campaign name within the panel, aiding in organizational identification.

  • Title (Inside iOS and Android Blocks):

    • When placed inside the iOS and Android blocks, this parameter returns the title specifically for the push notification on the respective platforms. This allows customization of the notification title based on the user's device environment.

  • Categories: You may use the category id (shown on Settings > Message Categories on Netmera Panel) or the category name.

Personalized Message & Subtext

Parameters

  • title (Required):

    • Specifies the name of the campaign.

  • message (Required):

    • The default push notification message. If no personalized message is used, this message will be sent to users.

  • inbox (Optional):

    • A boolean value determining whether to display the push notification in the inbox.

  • platforms (Required):

    • Indicates the platforms capable of receiving this notification.

  • personalizedMessage (Optional):

    • If a user-specific message is to be sent, utilize the @{xxxx} placeholder. Placeholders can be profile attributes or sent via a transactional message call.

  • click (Optional):

    • Specifies the default push click action. This action can be overridden by a transactional message call.

  • ios (Optional):

    • Contains optional parameters specific to iOS.

  • android (Optional):

    • Holds optional parameters specific to Android.

  • hook (Optional):

    • Includes optional hook parameters. If no hook is to be attached, exclude the hook block from the request.

Parameters

Given: A push notification is created for users utilizing the "Create New Notification" service.

When: Label information is added to the message.

Then: The push notification is sent.

And: Confirmation is observed as the label field appears in the push report generated on the panel.

Sample Response:

Parameters

The notificationKey serves as the identifier for your message definition. This unique key is used when making a transactional message call, connecting the message to its predefined definition. Ensure to utilize this specific notificationKey to maintain coherence between your message definitions and transactional messages.

Button Sets

Carousel Push

Slider Push

Transactional Notifications with Features

Transactional with Deeplink

Add a deeplink to your transactional notification, allowing you to redirect users to a specific view or content upon clicking the notification.

Transactional with URL

Add a URL to your transactional notification, enabling the opening of a landing page in a default web view after users click on the notification. This allows you to direct users to specific web content or external pages related to the transactional notification.

Transactional with Rich Media

To send a transactional notification with rich media content, utilize the following request, allowing the inclusion of title, subtitle, and different types of media based on the platform:

  • Title and Subtitle:

    • Include title and subtitle in your transactional notification.

  • Rich Media:

    • For Android, include an image. For iOS, include an image, sound, or video.

Transactional with Sound & Vibration

When sending a transactional notification with sound and vibration, follow these steps:

  • Sound Definition:

    • Define sounds in the panel under Developers/Sounds menu.

  • Platform-specific Sound Setting:

    • Set sounds for each platform accordingly. This ensures that the appropriate sound is played based on the user's device platform.

Note: Ensure that the sounds are defined in the panel under Developers/Sounds before attempting to use them in your transactional notification. This allows for a customized and platform-specific audio experience for users.

Transactional with Custom Parameters

To customize your transactional notification further, consider adding custom parameters with the following request. These parameters can then be utilized on the device when the push notification is received.

Other parameters

Parameters

  • ttl (Optional):

    • Time to live value of the notification. If any target device does not receive the notification within the given period, it will not be received. Example usage: 15d means 15 days, 20h means 20 hours, and 30m means 30 minutes.

  • inbox (Optional):

    • A boolean value that determines whether to display the push notification in the inbox or not.

  • doNotNotify (Optional):

    • A boolean value that determines whether to show the push notification on the notification center or not.

Transactional to Last Device

You may utilize the last device field optionally when sending push notifications to target the last devices of the users.

  • "lastActiveDevice": true → Sending to Last Active Device

  • "lastActiveDevice": false → Sending to All Devices

Transactional with Profile Attributes

In the command, pa is a placeholder for the type of profile attribute you're targeting, and pb is the specific code for the surname attribute. Essentially, you're sending the notification with id number 1000 to users whose surname matches with "Smith." Instead of code "pb", you may use other profile attribute codes as specified in the Developers > Profile Attributes > Code section.

Adding Multiple Profile Attributes

In this command:

  • "pb": ["Smith", "Johnson"]: Indicates that the notification will be sent to users whose surname matches "Smith" or "Johnson". You can add more values within the array to target additional profile attribute values.

Logical Operators:

Conditions within the same attribute (e.g., "pb": ["Smith", "Johnson"]) are connected by OR. This means the notification will be sent to users whose surname matches either "Smith" or "Johnson".

Updating Button Set Names with Transactional Push

Integration Updates:

In the sendNotification and createNotificationDefinition APIs, the field called buttonNames can be used to facilitate the renaming of buttons. When providing new button names corresponding to the old ones, users will receive notifications with these new names. If the buttonNamesfield is not included in the request, notifications will be sent with the old button names.

Needs Service Extension Integration for iOS:

If you wish to use this feature with iOS devices you need to complete Service Extention Integration for iOS. You may see Media Push on how to complete this integration for Swift SDK and Media Push for former iOS SDK.

Sample request for createNotificationDefinition

Sample request for sendNotification

Create Web Transactional Push

To create a Web Transactional Push notification using the curl command, you can structure your command as follows:

Web Transactional Push

To send a Web Transactional Push notification using the curl command, you can structure your command as follows:

Web Transactional Push with Deeplink

To send a Web Transactional Push notification with Deeplink using the curl command, you can structure your command as follows:

@{parameters} must be valid for users:

When using parameters like @{extID} in deeplinks, it's important to ensure that these parameters correspond to actual user data. If these parameters don't exist for users, even if the users match the specified targets, the notification delivery won't be successful. In simpler terms, make sure the parameters you use in deeplinks are valid and available in the user data to avoid issues with sending notifications. You may see the documentation on Deep Linking.

Push Stats

By Notification Key

With the following request, you can reach the stats of a notification.

Parameters

  • notificationKey (Required):

    • This is the notification key associated with a particular message for which you want to retrieve statistics. It is a required parameter and plays a crucial role in identifying the specific message for which you seek statistical information.

Sample response:

By Date Range

With the following request, you can reach the stats of a notification.

Parameters

  • start (Required):

    • The start date, specified in milliseconds, is a required parameter. It determines the beginning of the time range for which you want to retrieve data.

  • end (Required):

    • The end date, also specified in milliseconds, is a required parameter. It marks the conclusion of the time range for which you want to obtain data.

Sample response:

Get Push Result

To retrieve users' push results (success or failure), use the following request. If start and end dates are not specified, the results for the last 2 weeks will be returned.

Parameters

  • start (Optional):

    • Start date in milliseconds. If provided, it sets the beginning of the time range for retrieving results.

  • end (Optional):

    • End date in milliseconds. If provided, it marks the conclusion of the time range for retrieving results.

  • notificationKey (Optional):

    • Notification ID on the panel. If specified, it filters results based on the given notification.

  • extId (Optional):

    • External ID for obtaining message results of a specific user. If provided, it narrows down the results to the specified user.

  • token (Optional):

    • Device token for acquiring message results of a specific device. If included, it restricts the results to the specified device.

Sample response:

Parameters

  • notificationKey (Required):

    • Notification key of a message to obtain users' responses. This is a required parameter that identifies the specific message for which you want to retrieve user responses.

  • max (Optional):

    • The default value is 10. This parameter determines the maximum number of result info to fetch per page. It is optional, and if not specified, the default value of 10 will be used.

  • Next Page Retrieval:

  • To fetch the next page of results, you need to send a request to the nextPage value. This mechanism enables the retrieval of additional information beyond the initial page.

SMS and Email Notification Key Details:

When you provide the notification key for SMS and email notifications made before, it returns the success and failure details for each individual email or SMS sent.

Example for Email:

Example for SMS:

Send Notification to Custom Target

To send a notification to a specific group of people, whether categorized by tags, segments, location, or profile attributes, follow these guidelines:

  • Target Specification:

    • You must define a specific target (tag, segment, location, or profile attribute) for the notification.

  • Note:

    • Leaving the target empty is not allowed. If you intend to send a notification to all users, set the sendToAll attribute to true. This attribute ensures the notification is broadcasted to all users.

Geofence

Geofences can be established via the Rest API.

Parameters

  • title (Required):

    • Geofence name at Dashboard.

  • latitude (Required):

    • Latitude of the center point.

  • longitude (Required):

    • Longitude of the center point.

  • radius (Required):

    • Radius value in kilometers from the center to search for users. The unit can be KM, Miles, or Meters. The default value is KM.

Email

Use the notification key created from the panel to work with email functionality.

Send Email with Attachment

You may add more than one attachment. However, the email size and the total size of attachments should not exceed 10 MB.

Supported file types:

"image/png", "video/x-msvideo", "video/mp4", "video/mpeg", "video/mpeg2", "video/x-mpeg", "image/gif", "image/jpeg", "image/x-png", "image/x-citrix-png", "image/x-citrix-jpeg", "text/plain", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel", "text/csv", "xlsx", "xls", "csv", "txt", "pdf", "jpg", "jpeg", "png", "gif", "mpeg", "mpeg-2", "mp4", "avi".

Please ensure that you adhere to the specified requirements and supported file types when using the sendEmailWithAttachment method.

Add or Update Emails

You can utilize the addEmail method to upload or update a list of emails to Netmera.

addEmail Method Reminders:

  • If the email already exists with the addEmail service (e.g., in a user with an ExtID or a user previously added with this service), a new user will not be created.

  • If a user is added using the addEmail service, a new user will only be created in the dashboard if no user with this email already exists. These users will not have an installation ID, so the installation ID will not be visible when searching by email or user ID in the People section.

  • Users created with the addEmail service can be viewed in the dashboard. However, if a new user is created from the SDK using the same email, the initially created user with addEmail will be deleted. The information from the SDK is considered master, and targeting is done on the SDK user.

  • You can use this service only to upload email lists. Upload can be done within the KB limit without a maximum limit.

Creating a Template for Sending Email

Follow the example provided below to create a template for sending an email to a user.

SMS

You can work with sms with the notification key you create from the panel.

Add or Update MSISDN (Phone Number)

The addMsisdn method is used to add users with the specified MSISDNs (phone numbers) to the Netmera platform.

Mandatory to include the country codes:

When using this service, it is mandatory to include the country code in the phone numbers, i.e., the phone numbers should be in the format of "+90xxxxxxxx".

AddMsisdn Method Reminders:

  • If the MSISDN already exists with the service (e.g., in a user with an ExtID or a user previously added with this service), a new user will not be created.

  • If a user is added using these services, a new user will only be created in the dashboard if no user with this information already exists. These users will not have an installation ID, so the installation ID will not be visible when searching by user ID in the People section.

  • Users created with these services can be viewed in the dashboard. However, if a new user is created from the SDK using the same MSISDN, the initially created user will be deleted. The information from the SDK is considered primary, and targeting is done on the SDK user.

  • You can use this service only to upload msisdn lists. Upload can be done within the KB limit without a maximum limit.

Creating a Template for Sending SMS to a User

Follow the example provided below to create a template for sending an SMS to a user.

PreviousSetupNextEvents

Last updated

Was this helpful?