This document describes how to integrate Push Notification APIs into your service with a REST API.

Registers push tokens saved on the devices of receiving user, also referred as 'device token', on the Kakao platform before using the Push notification function.

To use this API, you need the app's Admin key and push tokens issued from APNs or FCM. Notice that you must call this API only from the server to avoid security risk because this API requires your app's Admin key.

Use a unique number(long type) assigned to each user for uuid. device_id is another unique value to identify user's devices. You can use this value to send a push notification to a specific device of a receiving user if the user is using multiple devices.

If the request is successful, an integer is returned with the HTTP status code 200. The integer indicates how many days later the push token expires. Because the expiration time is not refreshed automatically, you must re-register the push token for the user and device before the push token expires.

curl -v -X POST "https://kapi.kakao.com/v2/push/register" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "uuid=1234" \
  -d "device_id=0f365b39-c33d-39be-bdfc-74aaf5534470" \
  -d "push_type=fcm" \
  --data-urlencode "push_token=APA91bEZ3fjwrKV2mxAFvZMC960zKBWBVffLErwZgFzsFnzzsxgi5lSQlq3zvzObZBe4OnbwkTZfMqV7_a6fF0AJNgUjt5Scpo2BTaHyLVlK54QmwIQBahUwJprKjj0YvF_rh8l7CTvl6TRxqlqO_NIwaoAcI0MssA"

HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json;charset=UTF-8

-1

Retrieves users' push tokens (device token) registered in the Kakao Push service.

When you request to retrieve push tokens, you must include either uuid or uuids in your request. If you want to retrieve the push tokens of a specific user, use uuid. To retrieve the push tokens of multiple users, use uuids. You must send a GET or POST request using the app's Admin key from the server.

Because the Kakao Push service supports multi-devices, a user may have multiple devices, and multiple device tokens may be registered for the user. If the request is successful, the push token information is returned as a JSON Array. Each push token includes information, such as a user's unique ID, a device's unique ID, the push token and its type, and the date and time when a push token has been created and updated.

curl -v -G GET "https://kapi.kakao.com/v2/push/tokens?uuid=1234" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"

curl -v -X POST "https://kapi.kakao.com/v2/push/tokens" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  --data-urlencode 'uuids=["1234", "5678"]'

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
    "uuid":"9876543211234",
    "device_id":"0f365b39-c33d-39be-bdfc-74aaf5534470",
    "push_type":"fcm",
    "push_token":"APA91bEZ3fjwrKV2mxAFvZMC960zKBWBVffLErwZgFzsFnzzsxgi5lSQlq3zvzObZBe4OnbwkTZfMqV7_a6fF0AJNgUjt5Scpo2BTaHyLVlK54QmwIQBahUwJprKjj0YvF_rh8l7CTvl6TRxqlqO_NIwaoAcI0MssA",
    "created_at":"2014-07-29T06:24:12Z",
    "updated_at":"2014-07-29T06:24:12Z"
    }
]

Revokes a push token of a specific user or device.

You can call this API when a user wants to disable the push notification function or when a user logs out from a specific device. If a user has multiple devices, you can delete a specific device's push token by specifying the device ID.

If you pass uuid in your request, all push tokens registered for the user are deleted. To delete the user's specific device, include device_id along uuid in your request. You can also specify a push server type to delete by specifying push_type.

If the request is successful, an empty value is returned with the HTTP status code 200.

curl -v -X POST "https://kapi.kakao.com/v2/push/deregister" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "uuid=1234" \
  -d "device_id=0f365b39-c33d-39be-bdfc-74aaf5534470" \
  -d "push_type=fcm"

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8

Sends push notifications to all devices registered as the receiving user's unique ID (uuid).

When you request to send push notifications, add payload that cotains the content of the push notification through the push_message parameter to the request. For this parameter, define PushMsgJson in JSON format by including for_apns or for_fcm according to the push server type. If you send push notifications to both platforms, you must include both for_apns and for_fcm. Because the configuration is slightly different for each platform, refer to the parameter descriptions as below.

If the request is successful, an empty value is returned with the HTTP status code 200. Note that this success status code does not guarantee that the push notification has been successfully sent to the device. If the APNs and FCM servers are unstable, push notifications may not be sent properly.

If failed, the failure information is passed to the return_url you specified in the request. The failure information includes uuid that the push notification is not delivered to, push token information and time of failure. In the case of FCM, a new push token value to refresh a push token may be returned as well.

APNs only allows a push notification with a data length of 4 KB or less, excluding topic, push_alert, return_url, and push_token. For iOS 7 or less, up to 256 bytes are allowed. For VoIP notification, the maximum size is 5 KB.

If the payload size exceeds 4 KB and the message is a string type, cut off the last part of a message, and add ".." to the end of the message content.

To downsize or customize a message, you can store a format for a specific push notification message in the app in advance and pass only the keys and parameters according to the specified format in your request. Refer to Creating the Remote Notification Payload.

You can use the Localized Formatted String function as follows:

1. Define a format in JSON format in your app.
2. Set loc-key to COMMENT_ALERT_FORMAT, and pass the values to be actually used in the message when requesting to send a push notification.

{
  "message": {
    "loc-key": "COMMENT_ALERT_FORMAT",
    "loc-args": ["John", "2"]
  }
}

When you have defined a format like this,

%@ users including %@ left comments.

The actual push notification is sent as follows.

2 friends including John left comments.

curl -v -X POST "https://kapi.kakao.com/v2/push/send" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d 'uuids=["1234", "5678"]' \
  --data-urlencode 'push_message={
  "for_apns":{
    "badge":3,
    "sound":"sound_file",
    "push_alert":true,
    "message":"2 friends including John left comments..",
    "custom_field":{
      "article_id":"111",
      "comment_id":"222"
    }
  },
  "for_fcm":{
    "collapse": "articleId123",
    "delay_while_idle":false,
    "custom_field": {
      "article_id": 111,
      "comment_id": 222,
      "comment_preview": "How have you been? ...(omitted)"
    }
  }
}'

{
  "for_apns": {
    "badge": 3,
    "sound": "sound_file",
    "push_alert": true,
    "content-available": 1,
    "category": "INVITE_CATEGORY",
    "message": "2 friends including John left comments..",
    "custom_field": {
      "article_id": "111",
      "comment_id": "222"
    }
  },
  "for_fcm": {
    "collapse": "articleId123",
    "delay_while_idle": false,
    "time_to_live": 17200,
    "dry_run": false,
    "priority": "high",
    "custom_field": {
      "article_id": 111,
      "comment_id": 222,
      "comment_preview": "How have you been? ...(omitted)"
    }
  }
}

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8

POST /fcm_push_fail HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

userId=123&pushToken=abcdefg&date=1396582208000

POST /fcm_push_fail HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

userId=123&pushToken=abcdefg&date=1396582208000&newPushToken=AAbbccddee

• Reference for REST API