Requirements for this tutorial:


- Basic knowledge of APIs
- Live app in the store so you can test this feature
- Link to the API


We are going to send a push notification to a specific category that we have made with the API



With the Push API you can send messages to the users who are registered in your app and have accepted push messages for the AppMachine app they have installed.
The Push API consists of these 2 sections, we will explain the first one in greater detail.


1. PushNotification
2. User


We will begin with the PushNotification Section and in Part 2 we will explain the User Section of the API.
In this section we have several endpoints that you can call. All of them need parameters in order to execute.


You always have to send these two things in the headers of your API call.


  • AM-AppKey
  • AM-ClientKey 


The keys are different for every app. The keys are being used for authentication. You can find the keys in your app when you go to:
- Developer Menu option in the left vertical menu (see "1" below)
- Developer Access (see "2" below)


1. 


2. 


3. 



In some calls you can specify optional parameters.


The API Calls


Let's take a look at all of the calls you can make in this section.


GET /v1/pushnotification
Will get a list of all the push notifications that are either scheduled for delivery or have been delivered to the users of your app.
POST /v1/pushnotification
Create a new push notification and schedule the notification for delivery.
DELETE /v1/pushnotification/{id}
Will delete a push notification matching the specified ID.
GET /v1/pushnotification/categories
Will get a list of all the available push notification categories for your app.
POST /v1/pushnotification/categories
Will create a new notifcation category that can be used to send notifications to specific user groups.
DELETE /v1/pushnotification/categories/{categoryId}
Will delete the notification category matching the specified ID.
PUT /v1/pushnotification/categories/{categoryId}
Will change the notification category matching the specified categoryId.



The most important one here is.
POST /v1/pushnotification.


With this call you can send a push notification to all the users of your app or send a push to a category to which your users have subscribed. For the sake of this tutorial, let's assume we have these three categories which we'll use for clothing.


  • Woman
  • Men
  • Kids


What we will do:
- Create these categories with the Push API
- Change the name of the category
- Send a pushmessage to one of the categories


Let's begin:


Checking for Categories


First we need to make sure these categories don't already exist so we will do this call first
GET /v1/pushnotification/categories



The response of the API call should give us back all the push message categories we have made in the app with an "ID" and the "name" of the category.



We need to fill in our AM-AppKey and AM-ClientKey



After that we can try it out and it will give us hopefully something back.
The Error messages are explained above the "try it out" button so there is no need to explain those here.



It looks like we don't have any categories yet so we can perform a POST call and make some.


Making the categories
For making the categories we are gonna execute the POST call (find it below the GET call we just performed)



The response of the API call is the same as the GET. We will get back the id and the name of the category we just created.



Again we need to fill in our AM-AppKey and AM-ClientKey



This time we also need to specify a little piece of JSON as an argument. If you click on it this will be pasted in the alterArguments field. This will be sent in the body of our request.



Alter the "string" part that is behind the "categoryName": to the name that you want. In this case it will be "Woman".



You can press the Try it out button and see if the category was correctly POSTED. In our case it was successful.



So now we've made a category. To make more categories you can scroll up a little bit and leave everything as it is expect change the JSON portion that we just replaced "string" with "woman". Change "woman" to "Men" and press the Try it out button again.


This will execute the API call again and will make another category. The same is for "kids," of course.




Just to be sure we can check if we've made the three categories we can do our previous GET call again (or just refresh you app and see on your phone, of course: Info ("i") button > Settings > Subscriptions )



If you haven't deleted the parameters we can just scroll a little bit to the top and just press "Try it out" to see if we were successful in creating all categories.



Looks like we were successful.


Sending a PushNotification


So what we've done so far:


  • Checking if our app already had categories
  • Created three categories ("Woman" / "Men" / "Kids" )
  • Checked again in the app if we created these categories successfully 


Now it's finally time to send a push message to one of the categories.


Please note!: App users need to subscribe to a category before they can receive a push message from that category. Consider informing your customers of the new category with a push message to all users a few days before sending your first push message for this category.

Let's say we want to give our customers 75% sale on Men clothing because you are such a giving person.


The call to send the message is of course the POST PushNotifcation call



The response is:



Parameters explained


message = The message you want to send.
deliveryDateTime = Will post your message at a specific time, if unchanged it will send immediately right after you execute the call.
isEnabledIOS = Message will be sent to all iOS devices. Set to false if you want to exclude devices.
isEnabledAndroid = Message will be sent to all Android devices. Set to false if you want to exclude devices.
isEnabledWindowsPhone = Message will be sent to all Windows Phone devices. Set to false if you want to exclude devices.
categoryId = In this case we want to specify this to our "Men" category id, if unchanged the message will be sent to all categories.
badge = Set to "1" to show the badgeIcon in iOS, or "0" to not show a badge.
userId = Send the message to a specific user (we will save this for Part 2 of our tutorial).


We want to send this only to the Men category so we will need the "categoryId".
If you scroll back to our GET categories call we can see in the result that we can get the ID of our categories.


Copy this and Paste this id in the POST Pushnotification call in the categoryId field



Our message looks like this



We've set the message / categoryId / badge parameters. The rest we left default. To test it out be sure to subscribe to the category you want to test.


The result looks like this on my phone


 



You can see the push notification has been delivered and the app icon gets a "1" badge.


This concludes Part 1 of our tutorial. Go to Part 2 of the tutorial.


Side notes


  • If the categoryID is wrong the push notification will be sent to all categories.
  • You cannot add "Open Block" to the Push Notification API at this time.
  • You cannot send GEO based Push Notification.