이 문서는 REST API를 사용한 푸시 알림 구현 방법을 안내합니다.
이 문서에 포함된 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.
푸시 토큰 등록, 보기, 삭제는 Android와 iOS SDK도 지원하지만, 푸시 알림을 보내는 기능은 REST API로만 지원합니다. 또한 Apple Push Notification service(APNs), Firebase Cloud Messaging(FCM) 인증 정보를 내 애플리케이션(이하 앱) 정보에 미리 등록해두어야 합니다. 인증 정보 발급 및 등록 방법은 설정하기를 참고합니다.
푸시 알림 API의 버전이 v1에서 v2로 업그레이드됩니다.
- 적용 일자: 2020년 12월 2일 - 변경 사항: Google Cloud Messaging(GCM)가 Firebase Cloud Messaging(FCM)으로 대체됨에 따라 push_type 값 변경
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/push/register |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
- | 푸시 알림 활성화 | - | - |
푸시 알림을 받을 사용자의 푸시 토큰(디바이스 토큰)을 카카오 푸시 서비스에 등록하는 API입니다.
앱 어드민 키(Admin Key)와 APNs, FCM으로부터 발급 받은 푸시 토큰이 필요합니다. 어드민 키를 사용하는 API이므로 보안 위험을 피하기 위해 반드시 서버에서 호출해야 합니다.
푸시 알림 발송에 보다 안전을 기하려면 카카오 API를 호출하는 IP를 제한할 수 있습니다. [내 애플리케이션] > [허용 IP 주소]에서 사용할 IP를 등록합니다. 자세한 정보는 보안: 허용 IP 주소를 참고합니다.
uuid
는 서비스에서 각 사용자에게 발급한 고유 숫자 값을 사용합니다. device_id
는 푸시 알림을 받을 각 기기를 등록하기 위한 값입니다. 같은 사용자가 여러 대의 기기를 사용하는 경우, 푸시 토큰을 기기별로 등록해 푸시 알림을 보낼 수 있도록 하는 용도입니다.
푸시 토큰 등록 성공시, HTTP 상태 코드 200 응답과 함께 푸시 토큰이 며칠 뒤 만료되는지를 나타내는 숫자 값을 받습니다. 이 기간은 자동으로 갱신되지 않으므로, 기간 이내에 해당 사용자 및 기기에 대한 푸시 토큰을 재등록해야 합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
uuid | String |
사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능 | O |
device_id | String |
동일 사용자의 기기(Device)를 구분하는 IDuuid 내에서 유일한 값이어야 함APNs의 경우, 기기마다 푸시 토큰이 다르기 때문에 APNs로부터 받은 토큰을 그대로 사용해도 무방 FCM은 기기 고유 ID를 생성하는 알고리즘 필요 |
O |
push_type | String |
푸시 서버 타입, apns 혹은 fcm | O |
push_token | String |
APNs(64자), FCM으로부터 발급받은 푸시 토큰 | O |
이름 | 타입 | 설명 |
---|---|---|
NONE | Integer |
푸시 토큰 만료 예정 기간, -1인 경우 무제한 |
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"
HTTP/1.1 200 OK
Content-Length: 2
Content-type: application/json;charset=UTF-8
-1
메서드 | URL | 인증 방식 |
---|---|---|
GET/POST |
https://kapi.kakao.com/v2/push/tokens |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
- | 푸시 알림 활성화 | - | - |
카카오 푸시 서비스에 등록된 사용자의 푸시 토큰 정보를 조회하는 API입니다.
푸시 토큰 보기 요청 시, uuid
또는 uuids
중 하나는 반드시 포함해야 합니다. uuid
는 특정 사용자 한 명의 푸시 토큰을, uuids
는 최대 100명의 사용자 푸시 토큰을 조회할 때 각각 사용합니다. 메소드는 GET
또는 POST
를 사용하며, 앱 어드민 키를 사용해 서버에서 요청해야 합니다.
요청 성공 시 응답은 JSON Array
로 푸시 토큰 정보를 받습니다. 카카오 푸시 알림 기능은 멀티 디바이스를 지원하므로, 각 사용자 앞으로 여러 개의 푸시 토큰이 등록돼 있을 수 있습니다. 각 푸시 토큰 정보는 uuid
, device_id
, 푸시 토큰 종류와 값, 생성 및 업데이트 일시를 포함합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
uuid | String |
사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능 | O* |
uuids | String[] |
사용자 고유 ID 목록, ID 100개 이하 | O* |
한 사용자의 푸시 토큰 정보를 요청하려면 uuid를 필수 파라미터로 전달, 여러 사용자의 푸시 토큰 정보를 요청하려면 uuids를 필수 파라미터로 전달
이름 | 타입 | 설명 |
---|---|---|
uuid | String |
사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능 |
device_id | String |
동일 사용자의 기기(Device)를 구분하는 ID |
push_type | String |
푸시 서버 타입, apns 혹은 fcm |
push_token | String |
APNs(64자), FCM으로부터 발급 받은 푸시 토큰 |
created_at | Datetime |
푸시 토큰을 처음 등록한 시각 |
updated_at | Datetime |
푸시 토큰을 업데이트한 시각 |
* user_id: Deprecated, 사용자 고유 ID(String), uuid를 사용하도록 변경
curl -v -G GET "https://kapi.kakao.com/v2/push/tokens"
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "uuid=1234"
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"]'
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"
}
]
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/push/deregister |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
- | 푸시 알림 활성화 | - | - |
특정 사용자의 푸시 토큰을 삭제하는 API입니다. 사용자가 로그아웃하거나 푸시 알림을 끄는 경우, 더 이상 푸시 알림이 보내지지 않도록 하기 위해 이 API를 사용합니다. 사용자가 특정 기기에서만 로그아웃하거나 푸시 알림을 끈 경우, 특정 기기의 푸시 토큰만 지정하여 삭제할 수 있습니다.
요청 시 파라미터로 uuid
만 전달하면 해당 사용자의 푸시 토큰을 삭제합니다. 사용자의 푸시 토큰 중 특정 기기의 푸시 토큰만 삭제하려면 device_id
파라미터를 추가 전달합니다. push_type
파라미터로 사용자의 푸시 토큰 중 특정 서버 타입의 푸시 토큰만 삭제 요청할 수도 있습니다.
토큰 삭제 요청이 성공하면 HTTP 상태 코드 200 응답을 받으며 응답 본문은 없습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
uuid | Long |
사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능 | O |
device_id | String |
동일 사용자의 기기(Device)를 구분하는 ID uuid 내에서 유일한 값이어야 함 사용자의 특정 기기를 선택해 푸시 토큰을 지울 때 사용 APNs의 경우, 기기마다 푸시 토큰이 다르기 때문에 APNs로부터 받은 토큰을 그대로 사용해도 무방 FCM은 기기 고유 ID를 생성하는 알고리즘 필요 |
X |
push_type | String |
푸시 서버 타입, "apns" 혹은 "fcm" | X |
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"
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/push/send |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
- | 푸시 알림 활성화 | - | - |
푸시 알림을 보내는 API입니다. 수신할 사용자의 uuid
로 등록된 모든 기기에 푸시 알림이 보내집니다.
보낼 푸시 알림의 내용은 push_message
파라미터로 전달합니다. push_message
하위에 APNs용 for_apns
, FCM용 for_fcm
키로 각 푸시 알림 서비스 규격에 따른 전송 항목을 포함합니다. APNs과 FCM 모두 사용하려면 for_apns
과 for_fcm
모두 포함해야 합니다.
요청 성공 시 응답의 HTTP 상태 코드는 200이고, 응답 본문은 없습니다. 단, 요청 성공 응답은 푸시가 기기에 전송되었음을 보장하지 않습니다. APNs, FCM의 서버 상태가 좋지 않을 경우 푸시 알림이 전송되지 않을 수 있습니다.
푸시 알림 보내기에 실패했을 경우, 요청 시 전달한 return_url
로 실패 내역의 피드백(Feedback)을 받을 수 있습니다. 실패 피드백은 uuid
, device_id
, 푸시 토큰, 실패 시각을 포함합니다. FCM의 경우, 푸시 토큰 갱신을 위한 새 푸시 토큰 값을 포함하는 경우가 있습니다.
APNs는 푸시 알림 한 건당 4KB 이하, iOS 7 이하인 경우 256bytes 이하여야 전송 가능합니다. 전송 가능 용량 제한은 수신 데이터 기준이며 topic
, push_alert
, return_url
, push_token
를 제외한 파라미터에 적용됩니다. VoIP(Voice over Internet Protocol) 알림의 경우, 최대 5KB까지 지원합니다. 전송하려는 데이터의 용량이 4KB 이상이고 message
가 String
타입인 경우, message
값의 뒷부분을 자르고 ".."를 붙여 전송합니다.
메시지 경량화 및 사용자 맞춤형 콘텐츠 활용을 위해 특정 푸시 알림 메시지 세트(Set)를 앱 번들(App Bundle)에 저장하고, 푸시 알림 보내기 요청 시 사용할 메시지 세트와 대입할 값을 전달하는 방식도 지원합니다.(참고: Creating the Remote Notification Payload)
예를 들면 아래와 같은 메시지 세트를 앱 번들에 저장해 사용할 수 있습니다.
"COMMENT_ALERT_FORMAT" = "%@님 외 %@명이 댓글을 달았습니다.";
해당 메시지 세트를 사용하려면 푸시 알림 보내기 요청 시 다음과 같이 message
하위에 메시지 포맷에 정의된 키는 loc-key
, 대입할 값은 loc-args
에 각각 전달합니다.
{
"message":{
"loc-key" : "COMMENT_ALERT_FORMAT",
"loc-args" : ["홍길동", "2"]
}
}
실제 푸시 알림은 다음과 같이 전달됩니다.
홍길동님 외 2명이 댓글을 달았습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
uuids | String[] |
사용자 고유 ID 목록, ID 100개 이하 | O |
push_message | PushMsgJson |
메시지를 구성하는 파라미터 전달할 내용이 없다면 비어 있는 대괄호({})라도 보내야 함 아래 PushMsgJson 구성 참고 |
O |
bypass | Boolean |
토큰 관리를 자체적으로 할 경우, 바이패스(bypass)용으로 푸시 알림을 사용할지의 여부 기본 값 false bypass 사용 시 푸시 토큰을 push_message 내용인 PushMsgJson 에 포함해야 함 |
X |
바이패스(Bypass, 우회로)는 카카오 플랫폼에 푸시 토큰을 등록하지 않고, 서비스 서버에서 자체적으로 푸시 토큰을 관리하는 경우에 사용하는 파라미터입니다. 푸시 토큰 정보가 없으면 알림 보내기 요청이 실패하므로, 푸시 메시지를 구성하는 파라미터인 push_message 값에 푸시 토큰을 전달하는 방식으로 요청해야 합니다.
이름 | 타입 | 설명 | 예제 | 필수 |
---|---|---|---|---|
topic | String |
VoIP 알림 사용 시 voip 값 전달 |
"voip" | X |
mutable-content | Integer |
APNs의 mutable-content 파라미터 설정 |
1 | X |
expiration | Integer |
푸시 수신이 불가능할 경우 재시도할 시간(단위: 초) | 86400 | X |
collapse | String |
푸시 메시지 구분자, 같은 collapse 를 가진 푸시가 여러 개 쌓여있다면 하나의 푸시로 기기에 전송 |
"we345" | X |
badge | Integer |
iOS 기기의 앱에 표시될 배지 카운트 | 123 | X |
sound | String |
푸시 수신 시 알람 소리 | "default" | X |
push_alert | Boolean |
음소거, 알림센터에 뜨지 않는 푸시 전송 소리나 알림 없이 badge 수를 바꾸고 싶을 때 사용 |
false | X |
content-available | Integer |
새로운 콘텐츠를 사용할 수 있음을 나타냄 | 1 | X |
category | String |
알림 센터에 보여줄 액션 설정 | INVITE_CATEGORY | X |
message | String|JSON |
APNs 기준 alert 에 해당, 알림 센터에 표시할 내용참고: APNs 앱 번들의 메시지 세트 활용 방법 |
"내가 쓴 글에 댓글이 달렸습니다." | X |
custom_field | Dictionary |
메시지 외 앱에 부가적인 정보를 전달하고자 할 때 사용 | {"article_id" : 111} | X |
return_url | String |
푸시 알림 전송 실패 피드백 처리가 필요할 때 사용 "BadDeviceToken", "Unregistered", "DeviceTokenNotForTopic" 등 실패 발생 시 사용됨 |
https://example.com/ fcm_push_fail |
X |
push_token | String |
바이패스 사용 시 자체 관리하는 푸시 토큰 | "AAABBBCCCDDD" | X |
apns_env | String |
푸시를 보낼 APNs 서버 설정sandbox , production 중 하나(기본값: production ) |
"sandbox" | X |
thread-id | String |
관련 알림을 그룹화하기 위한 앱별 식별자 | "Group01" | X |
apns-push-type | String |
페이로드의 내용, watchOS 6 이상인 경우 필수 | "alert" | X |
apns-priority | Integer | 알림의 우선 순위, 생략 시 기본값 적용(기본값: 10 ) |
5 | X |
target-content-id | String |
알림을 열 때 앞으로 가져올 창을 지정하는 식별자 | "Target01" | X |
interruption-level | String |
알림의 중요도와 전달 시기 | "time-sensitive" | X |
relevance-score | Double |
시스템에서 앱의 알림을 정렬하는 데 사용하는 관련성 점수 0에서 1 사이의 숫자 값 |
0.34 | X |
이름 | 타입 | 설명 | 예제 | 필수 |
---|---|---|---|---|
collapse | String |
푸시 메시지 구분자, 같은 값을 가진 푸시 알림이 여러 개일 때 마지막 하나만 사용자 기기로 전송 | "wi10ck48" | X |
time_to_live | Integer |
FCM에 저장될 미전송 메시지 보관주기, 초 단위 | 17200 | X |
dry_run | Boolean |
테스트용, 실제 단말에 전송되지 않음 | true 또는 false | X |
priority | String |
단말이 도즈 모드(Doze mode) 상태에서도 푸시를 받을 수 있도록 할지 설정 (기본값: normal ) |
high 또는 normal | X |
custom_field | Json |
앱에 메시지 외 부가 정보를 전달할 때 사용 참고: APNs와 달리 푸시 알림 한 건당 custom_field 전체 길이 4KB로 제한 |
{"article_id" : 111 } | X |
notification | Json |
사용자에게 표시되는 사전 정의된 알림 페이로드(Payload)의 키-값 쌍 사전 정의된 키의 '표 2a/2b/2c' 참고 |
{"body":"great match!", "title":"Portugal vs. Denmark", "icon":"myicon"} |
X |
return_url | String |
푸시 알림 전송 실패 피드백 처리가 필요할 때 사용 | https://example.com/ fcm_push_fail |
X |
push_token | String |
바이패스 사용 시 자체 관리하는 푸시 토큰 | "AAABBBCCCDDD" | X |
이름 | 타입 | 설명 |
---|---|---|
userId | String |
푸시 전송에 실패한 푸시 토큰의 uuid(user_id) |
pushToken | String |
푸시 전송에 실패한 푸시 토큰 |
date | Long |
전송 실패 시간, 정수로 된 유닉스 타임스탬프(Unix timestamp), 밀리초(millisecond) 단위 |
이름 | 타입 | 설명 |
---|---|---|
userId | String |
푸시 전송에 실패한 푸시 토큰의 uuid(user_id) |
pushToken | String |
푸시 전송에 실패한 푸시 토큰 |
date | Long |
전송 실패 시간, 정수로 된 유닉스 시간(Unix timestamp), 밀리초(millisecond) 단위 |
newPushToken | String |
바이패스(bypass) 사용 시 조건부 응답 값, 새로운 푸시 토큰 서비스에서 푸시 토큰을 자체적으로 관리할 경우, 해당 uuid(user_id)의 푸시 토큰을 갱신하기 위한 용도 |
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}" \
--data-urlencode 'uuids=["1234", "5678"]' \
--data-urlencode 'push_message={
"for_apns":{
"badge":3,
"sound":"sound_file",
"push_alert":true,
"message":"홍길동님 외 2명이 댓글을 달았습니다.",
"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": "나의 댓글을 받아랏!...(생략)"
}
}
}'
{
"for_apns":{
"badge": 3,
"sound": "sound_file",
"push_alert": true,
"content-available":1,
"category":"INVITE_CATEGORY",
"message": "홍길동님 외 2명이 댓글을 달았습니다.",
"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": "나의 댓글을 받아랏!...(생략)"
}
}
}
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