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.
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.
First send a push notification to your users using the provided sample code:
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Push Notification Title","platforms": ["ANDROID"],"text":"This is the push notification text!" },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Once the notification is sent, save the NotificationKey shown in the response.
"NotificationKey: 1000"
To modify the notification, add "refID": "NotificationKeyValue" inside "customJson": {. This change allows for different notification scenarios.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Push Notification Title","platforms": ["ANDROID"],"text":"This is the push notification text!","customJson": {"refID":"1000" } },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Android Live Push Update with Sound
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Push Notification Title","platforms": ["ANDROID"],"text":"This is the push notification text!","android": {"sound":"default" },"customJson": {"refID":"notification_id" } },"target": {"sendToAll":true }}'
Send Notifications / Basic
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.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"New Product Launch","platforms": ["IOS","ANDROID"],"text":"Exciting news! Our latest product is now available.","ios": {"title":"Check it Out!" },"android": {"title":"Discover Now!" } },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
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.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"New Product Launch","platforms": ["IOS","ANDROID"],"text":"Exciting news! Our latest product is now available.","ios": {"title":"Check it Out!" },"android": {"title":"Discover Now!" } },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Send Bulk / Carousel Push
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"platforms": ["ANDROID","IOS"],"text":"Explore our Products","message":"Check out our latest offerings!","title":"Product Showcase","click": {"url":"https://www.example.com/products" },"ios": {"title":"Discover on iOS","carousel": [ {"title":"Featured Product","content":"Explore our flagship item.","itemImageUrl":"https://example.com/images/product1.jpg","clickAction": {"action":"DEEP_LINK","url":"https://www.example.com/products/featured","deeplinkType":"URL","deepLinkUrl":"https://example.com/deeplink/featured" } }, {"title":"New Arrival","content":"Check out the latest addition to our collection.","itemImageUrl":"https://example.com/images/newarrival.jpg" } ] },"android": {"title":"Discover on Android","carousel": [ {"title":"Special Offer","content":"Do not miss out on our exclusive discount.","itemImageUrl":"https://example.com/images/specialoffer.jpg" }, {"title":"Top Picks","content":"Explore our curated selection of top products.","itemImageUrl":"https://example.com/images/toppicks.jpg","clickAction": {"action":"DEEP_LINK","url":"https://www.example.com/products/toppicks","deeplinkType":"URL","deepLinkUrl":"https://example.com/deeplink/toppicks" } } ] }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
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.
Send Bulk with Multilanguage
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"New Update Available","platforms": ["IOS","ANDROID"],"text":"Explore exciting features in the latest update!","customJson": {"key1":"value1" },"click": {"deeplink":"https://www.netmera.com" } },"languages": {"English": {"title":"New Features","text":"Discover what is new in this update.","click": {"deeplink":"https://www.netmera.com" } },"Turkish": {"title":"Yeni Özellikler","text":"Bu güncellemede neler yeni öğrenin.","click": {"deeplink":"https://www.netmera.com" } } },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Web Push / Send Bulk Notification
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Important Update",// If platforms contains Chrome or Firefox then iconUrl must exist"platforms": ["CHROME","MACOS","FIREFOX"],"text":"Please review the latest changes.","wpChromeImage":"<image-url>","interactionRequired":true,"click": {"url":"https://www.netmera.com" },"iconUrl":"<icon-url>" },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
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.
Web Push / Send Bulk with 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.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"New Features Announcement","platforms": ["CHROME"],"text":"Exciting updates just for you!","iconUrl":"https://netmera.com/img/cropped_logo.png","buttonSet": { "id":1,// id: $buttonSetId"Yes":"https://netmera.com/yes-feedback",// $buttonSetName: $actionurl"No":"https://netmera.com/no-feedback"// $buttonSetName: $actionurl } },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Mobile Push / Send Bulk with 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.
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.
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):
A transactional notification definition can be created either through the Netmera Panel or via a specific request.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"title":"New Campaign","message":"Exciting updates await you!","personalizedMessage":"Explore now: @{message}","inbox":false,"platforms": ["IOS","ANDROID"],"click": {"deeplink":"https://www.google.com" },"ios": {"mediaUrl":"ios_media_url_here","title":"New Feature Alert","subtitle":"Discover what is new","sound":"ios_sound","thumbnailUrl":"<ios-thumbnail-url>" },"android": {"mediaUrl":"android_media_url_here","title":"New Feature Alert","subtitle":"Discover what is new","sound":"android_sound","vibration":true,"bigText":"Explore the latest features","thumbnailUrl":"<android-thumbnail-url>" },"hook": {"name":"hook_name","params": {"key1":"val1","key2":"val2" } }}' \https://restapi.netmera.com/rest/3.0/createNotificationDefinition
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.
Transactional Notification Definition with Personalized Message & Subtext
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:
{"notificationKey":96}
notificationKey
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.
Transactional Notification Definition with Button Sets
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"title":"Important Survey","message":"We would love to hear your feedback!","inbox":false,"platforms": ["IOS","ANDROID"],"click": {"deeplink":"https://www.netmera.com" },"buttonSet": {"id":1,"Yes":"https://netmera.com/yes-feedback","No":"https://netmera.com/no-feedback" }}' \https://restapi.netmera.com/rest/3.0/createNotificationDefinition
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"platforms": ["ANDROID","IOS" ],"text":"Exciting announcement! New features are now available.","message":"Check out the latest updates.","title":"New Features Alert","click": {"deeplink":"https://www.netmera.com" },"ios": {"title":"Discover on iOS","slider": [ {"itemImageUrl":"https://example.com/ios-image1.png","clickAction": {"url":"https://www.netmera.com" } }, {"itemImageUrl":"https://example.com/ios-image2.png" } ] },"android": {"title":"Explore on Android","slider": [ {"itemImageUrl":"https://example.com/android-image1.png","clickAction": {"url":"https://www.netmera.com" } }, {"itemImageUrl":"https://example.com/android-image2.png" } ] } }}' \https://restapi.netmera.com/rest/3.0/createNotificationDefinition
Push Stats
Get Push Stats By Notification Key
With the following request, you can reach the stats of a notification.
curl -X GET \-H "X-netmera-api-key: your_rest_api_key" \-G \--data-urlencode notificationKey=234 \'https://restapi.netmera.com/rest/3.0/getPushStats'
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.
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.
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:
{"nextPage":"https://restapi.netmera.com/rest/3.0/getPushResult?offset=hJbolUuHucJ9dd&max=10","list": [ {"platform":"IOS","status":"FAILED","errorCode":"8","installationId":"C2Ii2ztdEaok0","errorMsg":"INVALID_TOKEN","timeStamp":1557819194426,"msgTitle":"Awesome Title","msgText":"How is it going, Jon?" }, {"platform":"ANDROID","status":"SUCCESS","installationId":"U7IwgcM8phSmv","extId":"B4A92950-B0FD-43E6-B312-C3EE088890BD","timeStamp":1557819194426,"msgTitle":"Awesome Title","msgText":"How is it going, Jon?" }// ... Additional entries ]}
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.
curl -X GET \-H "X-netmera-api-key: your_rest_api_key" \'https://restapi.netmera.com/rest/3.0/getPushResult?offset=hJbolUuHucJ9dd&max=10'
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:
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"target": {"email":"target_email@example.com" },"platforms": ["EMAIL" ],"title":"Your Account is Created", "message": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"><html><head></head><body esd-custom-display-conditions=\"[]\"><p class=\"esd-text\">HELLO<br>SPACE<br></p></body></html>",
"from":"info@netmera.com","senderName":"Netmera","subject":"Your Account is Created"}' \https://restapi.netmera.com/rest/3.0/sendEmailAndSms
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.
Send Notification to Tag
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Sports Update","platforms": ["IOS","ANDROID"],"text":"Get the latest sports news and updates!" },"target": {"tag":"Sport" }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Send Notification to Multiple Tags
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Updates for You","platforms": ["IOS","ANDROID"],"text":"Check out the latest updates tailored for your interests!" },"target": {"tag": ["Sport","Casual"] }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Users with any of the given tags will receive notification.
This is similar to:
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Personalized Updates","platforms": ["IOS","ANDROID"],"text":"Stay tuned for personalized updates tailored just for you!" },"target": {"tag": {"$or": ["Sport","Casual"]} }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
If you use $and instead of $or, users with all of the given tags will receive notification.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Exclusive Sports & Casual Updates","platforms": ["IOS","ANDROID"],"text":"Explore the latest updates in sports and casual topics just for you!" },"target": {"tag": {"$and": ["Sport","Casual"]} }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Submitting notifications using the "or" logic of the attribute value in transactional pushes.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Special Announcement","platforms": ["ANDROID"],"text":"Check out our latest special announcement just for you!" },"target": {"profile": {"$or": {"att1": ["val1","val2","val3"],"att2": ["val4"] },"name": {"$exists":true } } }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
If you use $not, users who don't have any of the given tags will receive notification.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"General Updates","platforms": ["IOS","ANDROID"],"text":"Explore the latest updates and news tailored for you!" },"target": {"tag": {"$not": ["Sport","Casual"]} }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Send Notification to Segment
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Exclusive Offer","platforms": ["IOS","ANDROID"],"text":"As a valued frequent user, enjoy an exclusive offer just for you!" },"target": {"segment":"frequent_users" }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Send Notification to Multiple Segments
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Special Announcement","platforms": ["IOS","ANDROID"],"text":"Exciting news for you! Check it out now." },"target": {"segment": ["frequent_users","churn"] }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Users with any of the given segments will receive notification.
If you use $and instead of $or, users with all of the given segments will receive notification
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Important Update","platforms": ["IOS","ANDROID"],"text":"Please be aware of this critical update." },"target": {"segment": {"$and": ["frequent_users","churn"]} }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
If you use $not, users who don't have any of the given segments will receive notification.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Latest News","platforms": ["IOS","ANDROID"],"text":"Stay updated with the latest news and announcements." },"target": {"segment": {"$not": ["frequent_users","churn"]} }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
Send Notification by Profile Attribute
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Special Offer","platforms": ["IOS","ANDROID"],"text":"Hello John! Check out our exclusive special offer just for you." },"target": {"profile": {"language": ["English","Turkish"],"name":"John" } }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
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.
Send Personalized Notification using Profile Attributes
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Special Offer","platforms": ["IOS","ANDROID"],"text":"Hello, [Name] [Surname]! Check out our exclusive special offer.","personalizedMessage":"@{name}, @{surname}" },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
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!!".
Send Notification to Specific Location
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Special Offer in Your Area","platforms": ["IOS","ANDROID"],"text":"Hello! Discover exclusive deals near you.", },"target": {"location": {"latitude":42.892,"longitude":21.355,"radius":50 } }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
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.
Send Notification 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.
curl -X POST \-H "X-netmera-api-key: your_rest_api_key" \-H "Content-Type: application/json" \-d '{"message": {"title":"Special Announcement","platforms": ["IOS","ANDROID"],"text":"Exciting news! Check out the latest updates.","categories":"announcements" },"target": {"sendToAll":true }}' \https://restapi.netmera.com/rest/3.0/sendBulkNotification
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.
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.
Send Notification 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.
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.
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.
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.
To schedule a notification for a future date, use the following "schedule" configuration in your request. This allows you to specifythe date and time when the message should be delivered in the future.
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.
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.
Silent Notification
Silent notifications are messages that are delivered to the user's device but are not displayed to the user. These notifications operate in the background and are useful for triggering actions or updates without causing any user-facing interruption.
When implementing silent notifications, ensure that the content and purpose align with backend processes or updates that don't require direct user interaction or visibility. This approach allows for seamless communication between the server and the application without disturbing the user experience.
Creating a transactional notification for Silent Notification
curl -X POST \
-H "X-netmera-api-key: your_rest_api_key" \
-H "Content-Type: application/json" \
-d '{
"title":"New Update Available",
"message":"Check out the latest features and improvements!",
"personalizedMessage":"Hello, @{username}, we have something special for you!",
"platforms":[
"IOS",
"ANDROID"
]
}' \
https://restapi.netmera.com/rest/3.0/createNotificationDefinition
Tip for Sending Silent Notifications:
While setting the title and message for notifications is not mandatory in the API, it is recommended. Including these details is advantageous as they will be displayed on the Netmera Control Panel, providing better visibility and organization.
Additionally, when working with personalized messages and placeholders (e.g., mockAttr), it's important to keep them consistent. This is especially true when sending silent notifications, where the placeholder becomes crucial for effective communication between your server and the Netmera platform. Consistency in placeholders ensures accurate and meaningful data transfer during silent notification handling.
Sample Response:
{
"notificationKey": 35
}
Tip:
Remember to keep track of the notificationKey from the response, as you'll need it for subsequent actions, especially when sending silent notifications.
Sending Silent Notification
To send the silent notification created in the previous step, you can use the following steps:
The key obtained from the previous step when creating the initial notification. This is crucial for linking the silent notification to the original notification.
target.optOut (Optional):
When set to true, you can target opt-out users. The default value is false. Use this option carefully and in accordance with privacy and consent considerations.
message.params (Required):
The placeholder entered in the previous step (e.g., mockAttr). Set this to an empty string as specified. This ensures that the silent notification aligns with the placeholder used during the initial notification creation.
Transactional Notification
Send Transactional Notification with Deeplink
Add a deeplink to your transactional notification, allowing you to redirect users to a specific view or content upon clicking the notification.
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.
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.
Send Transactional Notification 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.
Send Transactional Notification 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.
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.
Send Transactional Notification 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
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.
Web Transactional Push
To send a Web Transactional Push notification using the curl command, you can structure your command as follows:
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 Create New Deeplink.
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.
curl -X POST \
-H "X-netmera-api-key: your_rest_api_key" \
-H "Content-Type: application/json" \
-d '{
"target": {
"email": "target_email"
},
"platforms": [
"EMAIL"
],
"title": "AccountCreationNotification",
"message": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"><html><head></head><body esd-custom-display-conditions=\"[]\"><p class=\"esd-text\">Hello,<br>This is a test email.</p></body></html>",
"from": "info@netmera.com",
"senderName": "Netmera",
"subject": "Account Creation Notification"
}' \
https://restapi.netmera.com/rest/3.0/sendEmailAndSms
SMS
You can work with sms with the notification key you create from the panel.
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".
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.
curl -X POST \
-H "X-netmera-api-key: your_rest_api_key" \
-H "Content-Type: application/json" \
-d '{
"target": {
"msisdn": "target_msisdn"
},
"platforms": [
"SMS"
],
"title": "SMS Title",
"message": "Hello, this is your SMS message.",
"smsHeader": "NETMERA"
}' \
https://restapi.netmera.com/rest/3.0/sendEmailAndSms
