Push Messages

Location /api/apps/{appID}/users/{accountType}:{address}/topics/{topicID}/push/messages
This resource represents the push messages sent to the current topic.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

POST

/api/apps/{appID}/users/{accountType}:{address}/topics/{topicID}/push/messages

Description

Send a push message to the current topic.

A 400 status error with code INVALID_INPUT_DATA will be returned in the following scenarios:

  • None of "fcm", "gcm", "apns", "jpush" and "mqtt" fields is provided in the request.
  • None of "fcm.enabled", "gcm.enabled" or "apns.enabled" fields is provided in the request.
  • "gcm.dryRun" and "apns.enabled" are both set to true.
  • "data" contains nested JSONs or arrays.
  • "fcm.data" or "gcm.data" contains values different from String.
  • "apns.enabled" is true and "apns.data" contains nested JSONs or arrays.
  • "gcm.enabled" is set to true and "data" or "gcm.data" contains a key that starts with the prefix "google." or is one of these values:
    • from
    • registration_ids
    • collapse_key
    • data
    • delay_while_idle
    • time_to_live
    • restricted_package_name
    • dry_run
  • "fcm.enabled" is set to true and "data" or "fcm.data" contains a key that starts with the prefixes "google." or "gcm." or is one of these values:
    • from
    • message_type
    • collapse_key
    • priority
    • ttl
    • restricted_package_name
    • notification
    • fcm_options
    • direct_boot_ok
  • "fcm.enabled" is true and the payload for Android-FCM exceeds 4096 bytes.
  • "gcm.enabled" is true and the payload for Android-GCM exceeds 4096 bytes.
  • "apns.enabled" is true and the payload for iOS-APNS exceeds 2048 bytes.

If both GCM and FCM specific fields are enabled, the FCM push notification will be prioritized.


FCM-specific fields:

Field Type Description
enabled Boolean. Required. If true, it will send the message to the FCM installations of the subscribed users.
data JSON Object with only one-level of nesting, and only strings in values. Dictionary with the data that will be sent only to Android-FCM devices.
notification JSON Object with the following format:
Name Type Description
title String Notification title
body String Notification body
image String The url of the image
Notification template.
android JSON Object with the following format:
Name Type Description
collapseKey String Identifier for group of messages
priority Enum
  • NORMAL
  • HIGH
 Message priority
ttl String How long the message is kept in FCM storage when device is offline
restrictedPackageName String Package name of the app
directBootOk Boolean If true, the message will be delivered to the app while the device is in direct boot mode
notification
Name Type
title String
body String
icon String
color String
sound String
tag String
clickAction String
bodyLocArgs String[]
titleLocKey String
titleLocArgs String[]
channelID String
ticker String
sticky Boolean
eventTime String (Timestamp format)
localOnly Boolean
notificationPriority Enum:
  • PRIORITY_UNSPECIFIED
  • PRIORITY_MIN
  • PRIORITY_LOW
  • PRIORITY_DEFAULT
  • PRIORITY_HIGH
  • PRIORITY_MAX
defaultSound Boolean
defaultVibrateTimings Boolean
defaultLightSettings Boolean
vibrateTimings String[] (Duration format)
visibility Enum:
  • VISIBILITY_UNSPECIFIED
  • PRIVATE
  • PUBLIC
  • SECRET
notificationCount Integer
lightSettings JsonObject
{
    "color": {
        "red": number,
        "green": number,
        "blue": number,
        "alpha": number
    },
    "lightOnDuration": String (Duration format),
    "lightOffDuration": String (Duration format)
}
image String
Notification for Android devices
Android specific options for messages.

GCM-specific fields:

Field Type Description
enabled Boolean. Required. If true, it will send the message to the GCM installations of the subscribed users.
data JSON Object with only one-level of nesting, and only strings in values. Dictionary with the data that will be sent only to Android-GCM devices.
notification Notification payload. We supports title, body, icon, sound, tag, color and clickAction fields in notification. Other fields are not supported yet.
collapseKey String. Not required. If provided, it will be used as the GCM notification collapse_key
delayWhileIdle Boolean. Not required. If provided, it will be used as the GCM notification delay_while_idle
timeToLive Integer. Not required. If provided, it will be used as the GCM notification time_to_live
restrictedPackageName String. Not required. If provided, it will be used as the GCM restricted_package_name
dryRun Boolean. Not required. If true, the only system that can be enabled is “GCM” - no other system will be accepted. If provided, it will be used as the GCM dry_run

iOS-APNS specific fields:

Field Type Description
enabled Boolean. Required. If true, it will send the message to the APNS installations of the subscribed users.
data JSON Object with only one-level of nesting, and only strings, integers, booleans or doubles in the values. Dictionary with the data that will be sent only to iOS-APNS devices.
alert JSON Object with the format:
Field Type
title String. Not required.
subtitle String. Not required.
body String. Not required.
actionLocKey String. Not required.
locKey String. Not required.
locArgs JSON Array of values. Not required.
launchImage String. Not required.
All the information related to the alert that will be shown when the notification is received while the app is turned off. See details in APNS documentation.
sound String. Not required. If provided, it will be used as the “sound” to be sent with the notification. See details in APNS documentation.
badge Number. Not required. If provided, it will be used as the “badge” to be sent with the notification. See details in APNS documentation.
contentAvailable Boolean. Not required. If provided and has "true" value, the value "1" will be set in the field "content-available" in the notification; otherwise the field will not be sent. See details in APNS documentation.
category String. Not required. If provided, it will be used as the “category” to be sent with the notification. See details in APNS documentation.
mutableContent Boolean. Not required. If provided and has "true" value, the value "1" will be set to the field "mutable-content" in the notification; otherwise the field will not be sent. See details in APNS documentation.

JPUSH specific fields:

Field Type Description
enabled Boolean. Required. If true, it will send the message to the JPUSH installations of the subscribed users.
data JSON Object with only one-level of nesting, and only strings in values. Dictionary with the data that will be sent only to JPUSH devices.

MQTT specific fields:

Field Type Description
enabled Boolean. Required. If true, it will send the message to the MQTT installations of the subscribed users.
data JSON Object with only one-level of nesting, and only strings in values. Dictionary with the data that will be sent only to MQTT devices.
dryRun Boolean. Not required, Used for testing. If provided with "true" value, the message will not be sent to the device. Default is "false".
retain Boolean. Not required. >Retain message. (currently always false)
qos Integer. Not required. Quality of service for the message (default will be 0 - fire and forget)

Security

The administrator can execute this action. For other users, the permission to execute this action depends on the ACL of the topic.

Content-Type application/vnd.kii.SendPushMessageRequest+json

All the data to send the message.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Params
Name Required? Type Description
data JSONObject Dictionary with the data that will be sent to all the push systems enabled in this request.
sendToDevelopment boolean If true this message will be sent to the devices that have the property "development" to "true" in their installations. Default is true.
sendToProduction boolean If true this message will be sent to the devices that have the property "development" to "false" or null in their installations. Default is true.
pushMessageType string Value that will optionally indicate what is the type of the message. Event-generated push messages contain it.
sendSender boolean If true, send the “sender” field (userID of the user that triggered the notification). Default is true.
sendWhen boolean If true, send the “when” field (when the push message was sent). Default is false.
sendOrigin boolean If true, send the “origin” field (indicates if the message is the result of an event or sent explicitly by someone. Default is false.
sendAppID boolean If true, the appID field will also be sent. Default is false.
sendObjectScope boolean If true, send the “objectScope”-related fields that contain the topic that is the source of this notification. Default is true.
sendTopicID boolean If true, send the “topicID” field that contains the topicID that is the source of this notification. Default is true.
sendSourceURI boolean If true, send the "sourceURI" field containing the URI that identifies the source of this notification. Default is true.
sendSenderURI boolean If true, send the "senderURI" field containing the URI that indentifies the sender of this notification. Default is true.
fcm FCMType FCM-specific fields.
enabled boolean If true, it will send the message to the FCM installations of the subscribed users.
data JSONObject Dictionary with the data that will be sent only to Android-FCM devices.
token|topic|condition string Notification target. Just one at the same time.
notification JSONObject Notification template.
android JSONObject Android specific options for messages.
directBootOk boolean If true, the message will be delivered to the app while the device is in direct boot mode
gcm GCMType GCM-specific fields.
enabled boolean if true, it will send the message to the GCM installations of the subscribed users.
data JSONObject Dictionary with the data that will be sent only to Android-GCM devices.
notification JSONObject Notification payload that will be sent only to Android-GCM devices.
collapseKey string If provided, it will be used as the GCM notification collapse_key
delayWhileIdle boolean If provided, it will be used as the GCM notification delay_while_idle
timeToLive int If provided, it will be used as the GCM notification time_to_live
restrictedPackageName string If provided, it will be used as the GCM restricted_package_name
dryRun boolean If provided, it will be used as the GCM dry_run
apns APNSType iOS-APNS specific fields.
enabled boolean if true, it will send the message to the APNS installations of the subscribed users.
data JSONObject Dictionary with the data that will be sent only to iOS-APNS devices.
alert JSONObjectAPNSType All the information related to the alert that will be shown when the notification is received with the app turned off. See details in APNS documentation.
badge float If provided, it will be used as the “badge” to be sent with the notification. See details in APNS documentation.
sound string If provided, it will be used as the “sound” to be sent with the notification. See details in APNS documentation.
contentAvailable boolean If provided and has "true" value, it will be set "1" to the field "content-available" in the notification, otherwise that field will not be sent. See details in APNS documentation.
category string If provided, it will be used as the “category” to be sent with the notification. See details in APNS documentation.
mutableContent boolean If provided and has "true" value, it will be set "1" to the field "mutable-content" in the notification, otherwise that field will not be sent. See details in APNS documentation.
jpush JPUSHType JPUSH specific fields.
enabled boolean if true, it will send the message to the JPUSH installations of the subscribed users.
data JSONObject Dictionary with the data that will be sent only to JPUSH devices.
mqtt MQTTType MQTT specific fields.
enabled boolean if true, it will send the message to the MQTT installations of the subscribed users.
data JSONObject Dictionary with the data that will be sent only to MQTT devices.
dryRun boolean Used for testing, if provided with "true" value the message will not be sent to the device. Default is "false".
retain boolean Retain message. (currently always false)
qos int Quality of service for the message (default will be 0 - fire and forget)
Sample Request 
{
  "data": "[JSONObject]",
  "sendToDevelopment": "[boolean]",
  "sendToProduction": "[boolean]",
  "pushMessageType": "[string]",
  "sendSender": "[boolean]",
  "sendWhen": "[boolean]",
  "sendOrigin": "[boolean]",
  "sendAppID": "[boolean]",
  "sendObjectScope": "[boolean]",
  "sendTopicID": "[boolean]",
  "sendSourceURI": "[boolean]",
  "sendSenderURI": "[boolean]",
  "fcm": "[FCMType]",
  "gcm": "[GCMType]",
  "apns": "[APNSType]",
  "jpush": "[JPUSHType]",
  "mqtt": "[MQTTType]"
}
Responses
200

Content-Type application/vnd.kii.SendPushMessageResponse+json

The message will be sent in an asynchronous fashion.
Contents
Name Type Description
pushMessageID string The ID of the sent message
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
404

Content-Type application/vnd.kii.TopicNotFoundException+json

The topic was not found.
Contents
Name Type Description
errorCode string Error code "TOPIC_NOT_FOUND".
message string The error message.
topicID string The ID of the topic that is not found
objectScope ObjectScope The scope of the topic
appID string The ID of the application.
userID string The ID of the user. Only provided for a user-scope bucket.
groupID string The ID of the group. Only provided for a group-scope bucket.
thingID string The ID of the thing. Only provided for a thing-scope bucket.
type string One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING".
400

Content-Type application/vnd.kii.ValidationException+json

Happens in the following scenarios:
  • "gcm" or "apns" fields are not provided in the request.
  • "gcm.enabled" or "apns.enabled" fields are not provided in the request.
  • "gcm.dryRun" is true and at least one of "apns.enabled", "jpush.enabled" or "mqtt.enabled" is also true.
  • "mqtt.dryRun" is true and at least one of "apns.enabled", "jpush.enabled" or "gcm.enabled" is also true.
  • "data" contains nested JSONs or arrays.
  • "gcm.enabled" is true and "gcm.data" contains values different from String.
  • "apns.enabled" is true and "apns.data" contains nested JSONs or arrays.
  • "jpush.enabled" is true and "jpush.data" contains nested JSONs or arrays.
  • "mqtt.enabled" is true and "mqtt.data" contains nested JSONs or arrays.
  • "gcm.enabled" is set to true and "data" or "gcm.data" contain a key that starts with the prefix "google." or is one of these values:
    • from
    • registration_ids
    • collapse_key
    • data
    • delay_while_idle
    • time_to_live
    • restricted_package_name
    • dry_run
  • "fcm.enabled" is set to true and "data" or "fcm.data" contains a key that starts with the prefixes "google." or "gcm." or is one of these values:
    • from
    • message_type
    • collapse_key
    • priority
    • ttl
    • restricted_package_name
    • notification
    • fcm_options
    • direct_boot_ok
  • "apns.enabled" is set to true and "data" or "apns.data" contains a key with value "aps"
  • "mqtt.enabled" is set to true and "data" or "mqtt.data" contain a key that starts with the prefix "kii." or is one of these values:
    • from
    • installationIds
    • data
    • retain
    • dry_run
  • "gcm.enabled" is true and the payload for Android-GCM exceeds 4096 bytes.
  • "apns.enabled" is true and the payload for iOS-APNS exceeds 2048 bytes.
  • "jpush.enabled" is true and the payload for JPUSH exceeds 986 bytes.
  • "mqtt.enabled" is true and the payload for MQTT exceeds 4096 bytes.
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to send a message to the current topic.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).