Sending a Push Notification

Sending a push message to an application-scope topic

If you are an application administrator (developer), you can send push messages on the developer portal or with REST API.

Sending on the developer portal

You can send push messages using the developer portal's UI.

See Sending a Push to User Notification to learn how the application developer can push messages.

Sending via the REST API

You need to have the app administrator token to send push messages to an application scope topic via REST API. See here to learn how to get the app administrator token.

Here is the sample curl execution.

curl -v -X POST \
  -H "Authorization: Bearer {APP_ADMIN_TOKEN}" \
  -H "Content-Type: application/vnd.kii.SendPushMessageRequest+json" \
  -H "Accept: application/vnd.kii.SendPushMessageResponse+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/topics/{TOPIC_NAME}/push/messages" \
  -d '{
    "data": {
      "MsgBody": "Hi all!",
      "Urgent": false
    },
    "sendToDevelopment": true,
    "sendToProduction": true,
    "gcm": {
      "enabled": true
    },
    "apns": {
      "enabled": true,
      "alert": {
        "body": "Hello"
      }
    },
    "mqtt": {
      "enabled": true
    }
  }'

When sending a push message, specify if you want to send the message to the development and production environments with the sendToDevelopment and sendToProduction fields, respectively. Also, set the enabled fields of the gcm, apns, and mqtt fields to control to which push environments you want to send the message.

Fields Specific to Each Push Notification Network

You can set parameters specific to each push notification network such as FCM and APNs.

Specify parameters specific to each push notification network under the network name parameter such as gcm and apns in the above curl command. See REST API Overview for parameters available for each push notification network.

The following sample code sets the content-available parameter in order to send a silent notification through APNs.

-d '{
  ......
  "apns": {
    "enabled": true,
    "contentAvailable": true
  },
  ......
}'

The following sample code sets the mutable-content parameter to send a rich notification through APNs. This sample code additionally sets the title, subtitle, body, and category.

-d '{
  ......
  "apns": {
    "enabled": true,
    "alert": {
      "title": "New message",
      "subtitle": "Message from Alice",
      "body": "It's been a while..."
    },
    "mutableContent": true,
    "category": "MESSAGE_CATEGORY"
  },
  ......
}'

Sending a push message to a group-scope or user-scope topic

Sending a message

Any group member can send a push message to a group-scope topic.

Let's explore how to do this in the following curl execution sample:

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.SendPushMessageRequest+json" \
  -H "Accept: application/vnd.kii.SendPushMessageResponse+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/{TOPIC_NAME}/push/messages" \
  -d '{
    "data" : {
      "MsgBody" : "Hi all!",
      "Urgent" : false
    },
    "sendToDevelopment" : true,
    "sendToProduction" : true,
    "gcm" : {
      "enabled" : true
    },
    "apns" : {
      "enabled" : true
    },
    "mqtt" : {
      "enabled" : true
    }
  }'

Like the application scope case, set sendToDevelopment, sendToProduction, gcm, apns, and mqtt fields to control the destination of the message.

For a user-scope topic, only the user who owns the topic can send a push message to it.

The following is a curl execution sample.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.SendPushMessageRequest+json" \
  -H "Accept: application/vnd.kii.SendPushMessageResponse+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/topics/{TOPIC_NAME}/push/messages" \
  -d '{
    "data" : {
      "Item" : "Do something",
      "Done" : 0
    },
    "sendToDevelopment": true,
    "sendToProduction": true,
    "gcm" : {
      "enabled" : true
    },
    "apns" : {
      "enabled" : true
    },
    "mqtt" : {
      "enabled" : true
    }
  }'

For both cases, you can see that the actual message contents are stored in "data" field.

There are some predefined fields for tweaking your push messages (e.g. putting some additional info in the messages, controlling the message destination) and for setting field values specific to each push notification network. For the details, refer to the REST API reference.

Kii Cloud will return the following response:

• Returns a 201 response if the request is successfully accepted.
• Returns a 404 response with the error code TOPIC_NOT_FOUND if the specified topic does not exist.

Note: The FCM service allows you to use the payload up to 4 KB (4096 bytes) while the APNs payload is limited to 2 KB (2048 bytes). Do not put too many contents in the push messages, especially when you are sending the messages to iOS devices. You can also suppress the default keys that are automatically included in the notification message so as to save the APNs payload. Read the REST API reference for more information.