REST API

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

You can test the features described in this document in [Tools] > [REST API Test].

REST API Test Tooloutlink

Register push token

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v2/push/register	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Activate push notification	-	-

This API enables you to register 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.

Request

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
uuid	String	A user's unique ID. Only integers in the range of 1 to ((2^63)-1) are allowed.	O
device_id	String	Device's unique ID to identify a user's multiple devices. Used to register or delete a specific device's push token if a user has multiple devices. For APNs, you can use the push token received from APNs because each iOS device has different push tokens. For FCM, you need an algorithm to generate a device's unique ID.	O
push_type	String	Push server type. apns or fcm.	O
push_token	String	Push token issued from APNs (64 characters) or FCM.	O

Response

Body

Name	Type	Description
NONE	Integer	Validity period until the push token expires. If the token is unlimited, -1 is returned.

Sample

Request

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"

Response

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

-1

Retrieve push token

Basic information

Method	URL	Authorization
GET/POST	https://kapi.kakao.com/v2/push/tokens	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Activate push notification	-	-

This API enables you to retrieve 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.

Request

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
uuid	String	A user's unique ID. Only integers in the range of 1 to ((2^63)-1) are allowed.	O*
uuids	String[]	List of uuids. Up to 100 uuids are allowed.	O*

To retrieve the push tokens of a specific user, pass 'uuid' as a required parameter. To retrieve push tokens of multiple users, pass 'uuids' as a required parameter.

Response

Body

Name	Type	Description
uuid	String	A user's unique ID. Only integers in the range of 1 to ((2^63)-1) are allowed. NOTE: user_id has been deprecated and replaced with uuid.
device_id	String	Device's unique ID to identify a user's multiple devices.
push_type	String	Push server type. apns or fcm.
push_token	String	Push token issued from APNs (64 characters) or FCM.
created_at	Datetime	The time when the push token was registered.
updated_at	Datetime	The time when the push token was updated.

Sample

Request: Using uuid

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

Request: Using uuids

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"]'

Response

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"
    }
]

Delete push token

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v2/push/deregister	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Activate push notification	-	-

This API enables you to delete 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.

Request

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
uuid	Long	A user's unique ID. Only integers in the range of 1 to ((2^63)-1) are allowed.	O
device_id	String	Device's unique ID to identify a user's multiple devices. Used to delete a specific device's push token if a user has multiple devices. For APNs, you can use the push token received from APNs because each iOS device has different push tokens. For FCM, you need an algorithm to generate a device's unique ID.	X
push_type	String	Push server type. apns or fcm.	X

Sample

Request

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"

Response

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

Send push notifications

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v2/push/send	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Activate push notification	-	-

This API enables you to send 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 payload size limit

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.

Utilize format in app bundle

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.

Request

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
uuids	String[]	List of uuids. Up to 100 uuids are allowed.	O
push_message	PushMsgJson	Parameters to configure a message. If you do not have any parameter to pass, send empty brackets({}). Refer to PushMsgJson below.	O
bypass	Boolean	Whether to bypass when using the push notification function. Used when managing push tokens manually in the service server, instead of registering the token on the Kakao platform. (Default: false) If set to true, you must include payload in PushMsgJson.	X

PushMsgJson: for_apns

Name	Type	Description	Sample	Required
topic	String	Used when using VoIP (Voice over Internet Protocol).	"voip"	X
mutable-content	Integer	Set mutable-content parameters for APNs.	1	X
expiration	Integer	Time to retry to send a push notification in seconds when a push notification is not available to receive.	86400	X
collapse	String	Push message separator. If multiple push notifications have the same value, only the last notification is sent to the user's device.	"we345"	X
badge	Integer	Number of badges to be displayed in the app on iOS device.	123	X
sound	String	Notification sound when receiving push notifications.	"default"	X
push_alert	Boolean	Used when you want to have the device volume muted, send a push notification that does not appear in the notification center, or change the number of badges without sound or notification.	false	X
content-available	Integer	Indicates that new content is available.	1	X
category	String	Set an action to be shown in the notification center.	INVITE_CATEGORY	X
message	String or Json	The content to be displayed in Notification Center as an alert.	"2 friends including John left comments."	X
custom_field	Dictionary	Used when you want to pass additional information to the app along with a message.	{"article_id" : 111}	X
return_url	String	Used when you need to handle errors, such as "BadDeviceToken", "Unregistered", and "DeviceTokenNotForTopic" that occur when routing push notification.	https://example.com/ fcm_push_fail	X
push_token	String	Push token to be managed manually in the service server, not registering the token on the Kakao platform.	"AAABBBCCCDDD"	X
apns_env	String	APNs server to send a push notification to. sandbox or production. (Default: production)	"sandbox"	X
thread-id	String	App identifier to group notifications by relevance.	"Group01"	X
apns-push-type	String	Contents of payload. Required in watchOS 6 or higher.	"alert"	X
apns-priority	Integer	Notification priorities. (Default: 10)	5	X
target-content-id	String	Identifier used to target a window to bring to the front when opening a notification.	"Target01"	X
interruption-level	String	Importance and delivery timing of notifications.	"time-sensitive"	X
relevance-score	Double	Relevance score from 0 to 1. Used to sort app's notifications in a system.	0.34	X

PushMsgJson: for_fcm

Name	Type	Description	Sample	Required
collapse	String	Push message separator. If multiple push notifications have the same value, only the last notification is sent to the user's device.	"wi10ck48"	X
time_to_live	Integer	Period to store unsent messages in FCM storage in seconds.	17200	X
dry_run	Boolean	Used for testing. Not sent to the actual device.	true or false	X
priority	String	If set to high, a push notification is sent to a user's device even in the Doze mode. (Default: normal)	high or normal	X
custom_field	Json	Used when you want to pass additional information to the app along with a message. Unlike APNs, the total length of the custom_field per push notification is limited to 4 KB.	{"article_id" : 111 }	X
notification	Json	Key-value pairs of predefined notification payload displayed to the user. Refer to Table 2a, 2b or 2c under Notification payload support in Firebase Cloud Messaging HTTP protocol.	{"body":"great match!", "title":"Portugal vs. Denmark", "icon":"myicon"}	X
return_url	String	Used when you need to handle errors that occur when routing push notification.	https://example.com/ fcm_push_fail	X
push_token	String	Push token to be managed manually in the service server, not registering the token on the Kakao platform.	"AAABBBCCCDDD"	X

Response

Body: If fail to send a push notification through APNs

Name	Type	Description
userId	String	uuid (OLD: user_id) that owns the push token failed to send a push notification.
pushToken	String	Push token failed to send a push notification.
date	Long	Time when sending a push notification failed. In Unix timestamp format in milliseconds.

Body: If fail to send a push notification through FCM

Name	Type	Description
userId	String	uuid (OLD: user_id) that owns the push token failed to send a push notification.
pushToken	String	Push token failed to send a push notification.
date	Long	Time when sending a push notification failed. In Unix timestamp format in milliseconds.
newPushToken	String	Only returned when bypassing. A new push token used to refresh the push token stored under the designated uuid (user_id) when managing push tokens manually in the service server.

Sample

Request

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)"
    }
  }
}'

PushMsgJson

{
  "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)"
    }
  }
}

Response: Succeess

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

Response: Fail to send a push notification through APNs

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

userId=123&pushToken=abcdefg&date=1396582208000

Response: Fail to send a push notification through FCM

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

See more

• Reference for REST API