V1
Kumulos has a RESTful API that allows you to send or schedule push notifications, report on open rates / conversions and manage channels from any other backend system.
Install IDs¶
When sending notifications to specific users the Kumulos Push API uses installIds, these are unique identifiers within your app used by all the Kumulos services to cluster requests by the originating device. They are not used to authenticate your app, or a specific user of the app.
When it is initialized for the first time the Kumulos SDK will automatically generate a unique identifier for the device your App is installed on and will use this identifier for every subsequent interaction with our services.
If you want are using your own backend solution you will need to manage your own lookup to pair an installId with whatever identifier your app models devices or users with, an example of this interaction is shown in the diagram below.
Checking Push Registrations¶
When you run your app on a simulator or install your app on a device, you can check that the install has successfully registered for push notifications by selecting the app and clicking the Installs
tab to see the ten most recent installs of your app. Click on any install and then click on Push
tab.
Authentication¶
The Kumulos Push API authenticates other back-end services via HTTP Basic Auth using your app's API Key as the username and your Server Key as the password, both of these are available from the App Dashboard in your Agency Console.
Sending Notifications¶
POST https://push.kumulos.com/notifications
¶
Payload¶
The request payload must be provided as a JSON object, with the following fields and validation rules met.
{
broadcast: Boolean, when true the message will be sent to all registered devices
installIds: Array of installIds to send the notification to
userIds: Array of user identifiers to send the notification to
userMeta: Object keyed by user identifier of meta-data for each user
segmentId: Integer id of the segment to target
segmentUuid: Unique identifier of the segment to target
channelIds: Array of integer ids of the channel(s) to target
channelUuids: Array of unique identifier(s) of the channel(s) to target
excludeInstallIds: Install Ids to be excluded from the results of a channel or segment target
title: String, required
message: String, required
isBackground: Boolean, when true the message will be sent for processing in the background (content-available flag in iOS)
url: String, set a url for the message to open in the device browser
data: Optional object of additional key / values to be passed in the notification payload for your app to consume
ios: {
hasBadge: Boolean
badgeType: String, either "incrementBy" or "setTo"
badgeCount: Positive or Negative integer. Set to 0 to clear badge.
}
android: {
highPriority: Boolean, sets priority flag to wake up Android devices
}
scheduled: Boolean
schedule: {
sendAt: DateTime of format "Y-m-d H:i", required if scheduled is true
strategy: String, either "local" or "utc", required if scheduled is true
pastTimes: String, either "ignore" or "nextDay", required if scheduled is true,
}
collapseId: String, sets the apns-collapse-id and the collapse_key options for APNS/FCM respectively.
soundConfig: {
iosSound: String, sound file to play instead of the default device notification sound. Pass 'none' to disable vibration and sound for the notification.
}
reportingMeta: Object of arbitrary meta-data about this notification
}
At least one of broadcast, installIds, userIds, segmentId / Uuid or channel Id / Uuid must be provided to send a notification.
Sample cURL¶
curl -X POST
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
-d '{
"broadcast": true,
"title": "Hello World",
"message": "from Kumulos Push"
}' "https://push.kumulos.com/notifications"
Sample PHP¶
<?php
$postData = json_encode(array(
"broadcast" => true,
"title" => "Test Broadcast",
"message" => "Test from PHP")
);
$curl = curl_init();
curl_setopt_array( $curl, [
CURLOPT_URL => "https://push.kumulos.com/notifications",
CURLOPT_HTTPHEADER => array (
'content-type: application/json',
'accept: application/json',
'content-length: ' . strlen($postData),
),
CURLOPT_USERPWD => 'API_KEY:SERVER_KEY',
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $postData,
CURLOPT_RETURNTRANSFER => true
] );
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
}
else {
echo $response;
}
?>
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
422 Unprocessable Entity¶
Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.
The response body will return a JSON object describing what keys were not present or had invalid values.
201 Created¶
Your request was accepted and processed.
The response body will contain a JSON object describing the notification object that was created as a result.
{
"appId":1,
"source":1,
"status":1,
"filters": { "broadcast":true },
"title":"Hello World",
"message":"from Kumulos Push",
"data":null,
"updatedAt":"2017-01-01T00:00:00+0000",
"createdAt":"2017-01-01T00:00:00+0000",
"id":1
}
Checking open rates¶
You can then use the ID of the notification created to get the installs or users that have opened the notification. This will allow you to track who or which install has opened what message and when. Very useful if you are measuring the effectiveness of your push campaigns.
Retrieving the installs that opened the notification¶
GET https://push.kumulos.com/notifications/{id}/install-opens
¶
Sample cURL¶
curl -X GET
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
"https://push.kumulos.com/notifications/1/install-opens"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
200 OK¶
Your request was accepted and processed.
The response body will contain an array of JSON objects showing the install IDs that opened the notification along with the time that the open was recorded.
[
{"installId":"abcdefgh","openedAt":"2017-01-01 00:00:00"},
{"installId":"ijklmnop","openedAt":"2017-01-01 00:00:00"}
]
Retrieving the users that opened the notification¶
GET https://push.kumulos.com/notifications/{id}/user-opens
¶
Sample cURL¶
curl -X GET
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
"https://push.kumulos.com/notifications/1/user-opens"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
200 OK¶
Your request was accepted and processed.
The response body will contain an array of JSON objects showing the install IDs that opened the notification along with the time that the open was recorded.
[
{"userId":"user-abcdefgh","openedAt":"2017-01-01 00:00:00"},
{"userId":"user-ijklmnop","openedAt":"2017-01-01 00:00:00"}
]
Using Meta-Data & User-Targeted Push¶
The combination of the userIds
, userMeta
, and reportingMeta
fields give you a flexible way to target & report on push notifications.
User ID Targeting¶
If you use the User Association feature to identify your users to Kumulos from device SDKs, you can make use of the userIds
targeting option. For example, if you identify your users by a 'membership number', you can associate that number with each installation when a user logs in.
Then once associated, you can send push notifications to the users identified by their membership number instead of the Kumulos install ID.
Reporting Meta-Data¶
When sending a notification, you may wish to associate meaningful meta-data with the notification. This meta-data will be reflected in the data field of any push events generated as a result of the notification and the user's interaction with the notification.
For example, if you wanted to send a campaign identifier, you could add the following to the send notification request:
{
...
"reportingMeta": {
"campaign": "Summer Promotion"
}
}
User Meta¶
User meta-data extends the concept of reporting meta-data to the user level when targeting pushes based on user identifiers.
For example, if sending to users, you can include meta-data specific to each user which will be reflected in any push events related to that user's notification & interactions with the message.
For example, if for each member you wanted to pass their current sequence number in a drip-feed content flow:
{
...
"userIds": ["member-id-1", "member-id-2"],
"userMeta": {
"member-id-1": { "messageSequenceNumber": 1 },
"member-id-2": { "messageSequenceNumber": 3 }
}
}
Creating a channel¶
POST https://push.kumulos.com/channels
¶
Sample cURL¶
curl -X POST
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
-d '{
"uuid": "channel-uuid",
"name": "friendly name"
"showInPortal": true
"meta": {
"additional": "data"
}
}' "https://push.kumulos.com/channels"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
422 Unprocessable Entity¶
Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.
The response body will return a JSON object describing what keys were not present or had invalid values.
201 Created¶
Your request was accepted and processed.
The response body will contain a JSON object describing the channel that was created as a result.
{
"appId":1,
"uuid":"channel-uuid",
"name":"Channel Name",
"showInPortal":true,
"meta": {
"additional":"data"
},
"updatedAt":"2017-02-16 14:43:03",
"createdAt":"2017-02-16 14:43:03",
"id":1
}
Updating a channel¶
PUT /channels/{id}
¶
Sample cURL¶
curl -X PUT
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
-d '{
"uuid": "channel-uuid",
"name": "friendly name"
"showInPortal": true
"meta": {
"additional": "data"
}
}' "https://push.kumulos.com/channels/{id}"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
422 Unprocessable Entity¶
Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.
The response body will return a JSON object describing what keys were not present or had invalid values.
200 Success¶
Your request was accepted and processed.
The response body will contain a JSON object describing the channel in its updated state.
{
"appId":1,
"uuid":"channel-uuid",
"name":"Channel Name",
"showInPortal":true,
"meta": {
"additional":"data"
},
"updatedAt":"2017-02-16 14:43:03",
"createdAt":"2017-02-16 14:43:03",
"id":1
}
Deleting a channel¶
DELETE /channels/{id}
¶
curl -X DELETE
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
"https://push.kumulos.com/channels/{id}"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
204 No Content¶
Your request was accepted and processed.
Subscribing installs to a channel¶
POST /channels/{id}/subscriptions
¶
Sample cURL¶
curl -X POST
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
-d '{
"installIds": ["uuid-1", "uuid-2"]
}' "https://push.kumulos.com/channels/{id}/subscriptions"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
422 Unprocessable Entity¶
Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.
The response body will return a JSON object describing what keys were not present or had invalid values.
404 Not Found¶
Your request has a non-existent install id.
204 No Content¶
Your request was accepted and processed.
Subscribing users to a channel¶
POST /channels/{id}/subscriptions
¶
Sample cURL¶
curl -X POST
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
-d '{
"userIds": ['user-1', 'user-2']
}' "https://push.kumulos.com/channels/{id}/subscriptions"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
422 Unprocessable Entity¶
Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.
The response body will return a JSON object describing what keys were not present or had invalid values.
404 Not Found¶
Your request has a non-existent user id.
204 No Content¶
Your request was accepted and processed.
Unsubscribing installs from a channel¶
DELETE /channels/{id}/subscriptions
¶
Sample cURL¶
curl -X DELETE
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
-d '{
"installIds": ["uuid-1", "uuid-2"]
}' "https://push.kumulos.com/channels/{id}/subscriptions"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
422 Unprocessable Entity¶
Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.
The response body will return a JSON object describing what keys were not present or had invalid values.
404 Not Found¶
Your request has a non-existent install id.
204 No Content¶
Your request was accepted and processed.
Unsubscribing users from a channel¶
DELETE /channels/{id}/subscriptions
¶
Sample cURL¶
curl -X DELETE
-H "Content-Type: application/json"
-H "Accept: application/json"
-u API_KEY:SERVER_KEY
-d '{
"userIds": ['user-1', 'user-2']
}' "https://push.kumulos.com/channels/{id}/subscriptions"
Responses¶
401 Unauthorized¶
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.
422 Unprocessable Entity¶
Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.
The response body will return a JSON object describing what keys were not present or had invalid values.
404 Not Found¶
Your request has a non-existent user id.
204 No Content¶
Your request was accepted and processed.
Calling from KScript¶
If you have multiple apps on Kumulos and you want an event in one app to trigger a push notification to an install of another app, you can do this using the HTTP client in a Kscript method.
var username = 'API Key of your other Kumulos app';
var password = 'Server Key of your other Kumulos app';
var auth = base64_encode( username + ':' + password );
var client = K.http.createClient('https://push.kumulos.com');
var headers =
{
'Authorization': 'Basic ' + auth,
'Content-Type': 'application/json',
'Accept': 'application/json'
};
var params =
{
'broadcast': true,
'title' : 'Hello',
'message': 'World'
};
var response = client.post('notifications', K.JSON.stringify(params), headers);
if (response.isError()) {
K.log(res.getBody());
}
If you have companion apps with different push notification certificates and API methods but you want two apps to share the same a backend database tables (for example: to access the Install IDs of the other app), please contact technical support who can arrange this.