페이지 이동경로
  • Docs>
  • Push Notification>
  • REST API

Push Notification

REST API

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

Note

- You can register, retrieve, or delete 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 in [My Application] 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.

IMPORTANT: 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.

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

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.

Allowed IP Address

To enhance security when sending push notifications, you can limit IPs to call the Kakao APIs from by registering the allowed Server IP Address in [My Application] > [Allowed IP Address]. For more information, refer to Security: Allowed IP address.

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" \
  -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.
user_id

'user_id', one of the request parameters for the Retrieving 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" \
  -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" \
  -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.

To downsize 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
Bypass

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: 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" \
  -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