Push Notification

REST API

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

Requirements

You can register, retrieve, or revoke push tokens using the Android and iOS SDKs. However, to send push notifications, you must use a REST API.
You must register your Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM) authentication information on the app management page in advance. To see how to get and register authentication information, refer to Prerequisites.
You must receive a push token from APNs or FCM beforehand by referring to documentation that APNs and FCM provides.

Push notification API upgrade from v1 to v2

Effective date: December 2, 2020
Changes: As Google Cloud Messaging(GCM) has been replaced by Firebase Cloud Messaging (FCM), the value of push_type has been changed.

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
-	Admin key Activate push notification	-	-

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.

If the same user has multiple devices, register a push token for each device to send push notifications to each one.

Allowed IP Address

To send push notifications securely, you can restrict the IP addresses that call the Kakao APIs. Register the IP addresses in [App] > [Admin key] > [Allowed IP address] on the app management page. For more information, refer to Allowed IP address.

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 revoke 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 (unit: days). If the token is unlimited, `-1` is returned. The period is not renewed automatically, so re-register the token before it expires.

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
-	Admin key Activate push notification	-	-

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

Conditions for use

Either uuid or uuids is required
- uuid: Retrieves push tokens for one user
- uuids: Retrieves push tokens for up to 100 users
Because multiple devices are supported, a user can have multiple registered push tokens

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 `uuid`s. Up to 100 `uuid`s 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.

Parameter name change

user_id, one of the request parameters for the Retrieve push token API, has been replaced with uuid to have the same name as the parameter of other Push APIs. user_id will be deprecated after a certain period of time.

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
-	Admin key Activate push notification	-	-

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.

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. If `device_id` and `push_type` are omitted, revokes all push tokens for the user.	O
device_id	`String`	Device's unique ID to identify a user's multiple devices. Used to revoke 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 of the token to revoke. `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
-	Admin key Activate push notification	-	-

Sends push notifications.

Delivery and failure handling

Push notifications are sent to all devices registered under each recipient's uuid.

However, a successful API response does not guarantee delivery to the device. A push notification might not be delivered depending on the APNs or FCM server status.

If delivery fails, feedback is sent to the return_url passed in the request. For FCM, the feedback may include a new push token for renewal.

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:

Define a format in JSON format in your app.
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 user's unique ID(`uuid`). Up to 100 `uuid`s are allowed.	O
push_message	`PushMsgJson`	Parameters to configure a message. Include APNs payload under `for_apns` and FCM payload under `for_fcm`. To use both services, include both keys. 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

Bypass parameter

If you want to manage push tokens in the service server on your own, not registering them on the Kakao platform, use the bypass parameter. You must make a request to send a notification by passing the push token as the value of push_message. If any push token information is not passed, the request fails.

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).	`"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 an APNs push notification fails

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 (unit: milliseconds).

Body: If an FCM push notification fails

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 (unit: 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

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

REST API

Register push token

Basic information

Request

Header

Body

Response

Body

Sample

Request

Response

Retrieve push token

Basic information

Conditions for use

Request

Header

Query parameter

Response

Body

Sample

Request: Using uuid

Request: Using uuids

Response

Delete push token

Basic information

Request

Header

Body

Sample

Request

Response

Send push notifications

Basic information

Delivery and failure handling

APNs payload size limit

Utilize format in app bundle

Request

Header

Body

PushMsgJson: for_apns

PushMsgJson: for_fcm

Response

Body: If an APNs push notification fails

Body: If an FCM push notification fails

Sample

Request

PushMsgJson

Response: Succeess

Response: Fail to send a push notification through APNs

Response: Fail to send a push notification through FCM

See more

Was this helpful?

REST API

Register push token

Retrieve push token

Delete push token

Send push notifications

See more