Notification API

Summary

Method Url Description
PUT /api/1/device Registers a device with Plamo. The device must be registered to receive notifications.
GET /api/1/device/{deviceToken}/topics Shows the current topic subscriptions.
POST /api/1/device/{deviceToken}/topics Add topics to the list of topic subscriptions.
PUT /api/1/device/{deviceToken}/topics Replace all existing topic subscriptions with a new list op topic subscriptions.
DELETE /api/1/device/{deviceToken}/topics Deletes all topic subscriptions.
DELETE /api/1/device/{deviceToken}/topics/{topic} Deletes a single topic subscription from the list of topics.
POST /api/1/notification Send a push notification.


PUT /api/1/device

URL: https://www.plamo.nl/api/1/device

Registers a device with Plamo. The device must be registered to receive notifications.

HTTP headers

x-plamo-application-key
required
The application key as shown in the Plamo console for the application.
x-plamo-application-version
required
The application version key as shown in the Plamo console for the application.

Request body

device
required
The device JSON element.
deviceName
required
The name of the device.

Example value: samsung GT-I9100 or iPad of John.
deviceToken
required
The device token. The token is returned from Apple or Google during the notification registration.

Example value: APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB9FrM8WPVFRwIMsRviLj7ykCHq Tbi4sPcPsdo64TxLQtghT6zys8_fFmll_UCtqWQzttXChLtk-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw.
deviceUid
required
A unique id of the device.

Example value: 1336834675776.
deviceModel
required
The model of the device.

Example value: GT-I9100 or iPhone
deviceVersion
required
The version of the os on the device.

Example value: 4.0.3 or 5.1.
osType
required
The type of OS used on the device

Allowed values: IOS, ANDROID or OTHER.
pushBadge
required
Capable of receiving push Badge notifications.

Allowed values: ENABLED or DISABLED.
pushAlert
required
Capable of receiving push alert notifications.

Allowed values: ENABLED or DISABLED
Android devices: use ENABLED.
pushSound
required
Capable of receiving push alert notifications.

Allowed values: ENABLED or DISABLED
Android devices: use ENABLED.
topics
optional
A list of topics the device must be subscribed to. Notifications can be send to all devices subscribed to a specific topic.

Example:

Register a device.

{"device":{"deviceName":"samsung GT-I9100","deviceToken":"APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw","deviceUid":1336834675776,"deviceModel":"GT-I9100","deviceVersion":"4.0.3","osType":"ANDROID","pushBadge":"DISABLED","pushAlert":"ENABLED","pushSound":"DISABLED","topics":["Top news","Economic news","Sport news"]}}
curl -X PUT
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
-d "{'device':{'deviceName':'samsung GT-I9100', 'deviceToken':'APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB9FrM8WPVFRwIMsRviLj 6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw', 'deviceUid':1336839174260, 'deviceModel':'GT-I9100', 'deviceVersion':'4.0.3', 'osType':'ANDROID', 'pushBadge':'DISABLED', 'pushAlert':'ENABLED', 'pushSound':'DISABLED',"topics":["Top news","Economic news","Sport news"]}}" https://www.plamo.nl/api/1/device

GET /api/1/device/{deviceToken}/topics

URL: https://www.plamo.nl/api/1/device/{deviceToken}/topics

Shows the current topic subscriptions.

HTTP headers

x-plamo-application-key
required
The application key as shown in the Plamo console for the application.
x-plamo-application-version
required
The application version key as shown in the Plamo console for the application.

Request parameters

deviceToken
required
The deviceToken used during the registration of the device with Plamo.

Example:

Get list of subscribed topics.

curl -X GET
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
https://www.plamo.nl/api/1/device/APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw/topics

Example output:


{"topics":["Top News", "Financial News", "Sports"]}

POST /api/1/device/{deviceToken}/topics

URL: https://www.plamo.nl/api/1/device/{deviceToken}/topics

Add topics to the list of topic subscriptions.

HTTP headers

x-plamo-application-key
required
The application key as shown in the Plamo console for the application.
x-plamo-application-version
required
The application version key as shown in the Plamo console for the application.

Request parameters

deviceToken
required
The deviceToken used during the registration of the device with Plamo.

Request body

topics
required
A list of string based topic names.

Example:

Add to the list of subscribed topics.

{"topics":["Top News", "Financial News", "Sports"]}
curl -X POST
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
-d "{'topics':['Top News', 'Financial News', 'Sports']}" https://www.plamo.nl/api/1/device/APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw/topics

PUT /api/1/device/{deviceToken}/topics

URL: https://www.plamo.nl/api/1/device/{deviceToken}/topics

Replace all existing topic subscriptions with a new list op topic subscriptions.

HTTP headers

x-plamo-application-key
required
The application key as shown in the Plamo console for the application.
x-plamo-application-version
required
The application version key as shown in the Plamo console for the application.

Request parameters

deviceToken
required
The deviceToken used during the registration of the device with Plamo.

Example:

Overwrite the list of subscribed topics.

{"topics":["Top News", "Financial News", "Sports"]}
curl -X PUT
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
-d "{'topics':['Top News', 'Financial News', 'Sports']}" https://www.plamo.nl/api/1/device/APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw/topics

DELETE /api/1/device/{deviceToken}/topics

URL: https://www.plamo.nl/api/1/device/{deviceToken}/topics

Deletes all topic subscriptions.

HTTP headers

x-plamo-application-key
required
The application key as shown in the Plamo console for the application.
x-plamo-application-version
required
The application version key as shown in the Plamo console for the application.

Request parameters

deviceToken
required
The deviceToken used during the registration of the device with Plamo.

Example:

Delete the list of subscribed topics.

curl -X DELETE
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
https://www.plamo.nl/api/1/device/APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw/topics

DELETE /api/1/device/{deviceToken}/topics/{topic}

URL: https://www.plamo.nl/api/1/device/{deviceToken}/topics/{topic}

Deletes a single topic subscription from the list of topics.

HTTP headers

x-plamo-application-key
required
The application key as shown in the Plamo console for the application.
x-plamo-application-version
required
The application version key as shown in the Plamo console for the application.

Request parameters

deviceToken
required
The deviceToken used during the registration of the device with Plamo.
topic
required
The topic to be deleted from the topic subscription list.

Example:

Delete the Top News topic from the list of subscribed topics.

curl -X DELETE
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
https://www.plamo.nl/api/1/device/APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw/topics/Top%20News

POST /api/1/notification

URL: https://www.plamo.nl/api/1/notification

Send a push notification.

HTTP headers

x-plamo-application-key
required
The application key as shown in the Plamo console for the application.
x-plamo-application-version
required
The application version key as shown in the Plamo console for the application.

Request body

maxNotificationsPerMinute
optional
The maximum number of notifications to send per minute.
deliveryDateTime
optional
The date and time the notifications must be send. The value must be formatted in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.MMMZ). Example: "2012-07-04T10:15:21.484+02:00"
destination
optional
The destination selection. The selection of the devices to send the notification to is based on the following logic:
All devices with <applicationVersion> AND <topic> AND <osType> AND <deviceToken> are selected.
When no criteria are specific all devices are selected.
applicationVersionKey
optional
The version key of the application to send the notification to.
Format version key: <osType>_<versionName>.

Example value: ANDROID_1.0.1
topic
optional
The topic to send to notification to.
Devices can subscribe to a topic. All devices subscribed to a topic will receive notifications sent the topic.

Example value: 'Top news'. All devices subscribed to 'Top news' wil receive the notification.
osType
optional
The osType of the device to receive the notification. By using the osType criteria a notification can be limited to one specific OS.

Allowed values value: IOS or ANDROID
deviceToken
optional
A device token. The token is returned from Apple or Google during the notification registration.

Use this criteria to select one specific device.

Example value: APA91bEapT6eWrcCA1ILPNsuoYz_mRmazB9FrM8WPVFRwIMsRviLj7ykCHq Tbi4sPcPsdo64TxLQtghT6zys8_fFmll_UCtqWQzttXChLtk-6A3W8CXhh1YWEqElMDqVuZ2yeP76sFQVw
data
required
The data element contains the data to be sent as the notification message.

All text data is allowed. The maximum size for iOS messages is 237 characters. Messages using the alert, badge or sound elements below are limited to 247 characters.
The maximum size of messages sent to Android devices is 1024 characters.
alert
optional
(iOS only) If this property is included, iOS displays a standard alert.
badge
optional
(iOS only) The number to display as the badge of the application icon. If this property is absent, the badge is not changed. To remove the badge, set the value of this property to 0.
sound
optional
(iOS only) The name of a sound file in the application bundle. The sound in this file is played as an alert. If the sound file doesn't exist or default is specified as the value, the default alert sound is played. The audio must be in one of the audio data formats that are compatible with system sounds; see "Preparing Custom Alert Sounds" for details.

Example 1:

Send a notification to all iOS devices with App version 1.0 subscribe to the topic 'Top News'.

{"destination":{"topic":"Top News","applicationVersionKey":"IOS_1.0"},"data":{"alert":"Major earthquake!"}}
curl -X POST
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
-d "{'destination':{'topic':'Top News','applicationVersionKey':'ANDROID_1.0'},'data':{'alert':'Major earthquake!'}}" https://www.plamo.nl/api/1/notification

Example 2:

Send a notification to all Android devices.

{"destination":{"osType":"ANDROID"},"data":"Major earthquake!"}
curl -X POST
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
-d "{"destination":{"osType":"ANDROID"},"data":"Major earthquake!"}" https://www.plamo.nl/api/1/notification

Example 3:

Send a notification to all devices.

{"deliveryDateTime": "2012-07-04T10:15:21.484+02:00", "maxNotificationsPerMinute": 100000, "data": {"changedSymbols" : ["MSFT", "AAPL", "GOOG"]}}
curl -X POST
-H "x-plamo-application-key: ba654fc0-2d41-4727-a09e-70c1d6234f34"
-H "x-plamo-application-version: IOS_1.1"
-H "Content-Type: application/json"
-d "{"data": {"changedSymbols" : ["MSFT", "AAPL", "GOOG"]}}" https://www.plamo.nl/api/1/notification

Company

Platform

Copyright © 2012, 2013 Plamo B.V. - Mobile backend as a service. All Rights Reserved.