사이드 메뉴
시작하기
로그인
커뮤니케이션
광고
푸시 알림
REST API
이 문서는 REST API를 사용한 푸시 알림 구현 방법을 안내합니다.
요구 사항
- Android와 iOS SDK로 푸시 토큰 등록, 보기, 폐기는 지원하지만, 푸시 알림을 보내는 기능은 REST API로만 지원합니다.
- Apple Push Notification service(APNs), Firebase Cloud Messaging(FCM) 인증 정보를 내 앱 정보에 미리 등록해두어야 합니다.
- 인증 정보 발급 및 등록 방법은 설정하기를 참고합니다.
API 버전 변경
푸시 알림 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 | 서비스 앱 어드민 키 |
푸시 알림을 받을 사용자의 푸시 토큰(디바이스 토큰)을 카카오 푸시 서비스에 등록합니다.
같은 사용자가 여러 대의 기기를 사용하는 경우, 푸시 토큰을 기기별로 등록해 각 기기로 푸시 알림을 전송할 수 있습니다.
호출 허용 IP 주소 설정
카카오 API를 호출하는 IP를 제한해서 안전하게 푸시 알림을 발송할 수 있습니다. 앱 관리 페이지의 [앱] > [어드민 키] > [호출 허용 IP 주소]에서 사용할 IP를 등록합니다. 자세한 정보는 호출 허용 IP 주소를 참고합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| 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인 경우 무제한 자동 갱신되지 않으므로 기간 내 재등록 필요 | O |
요청
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
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET/POST | https://kapi.kakao.com/v2/push/tokens | 서비스 앱 어드민 키 |
카카오 푸시 서비스에 등록된 사용자의 푸시 토큰 정보를 반환합니다.
uuid또는uuids중 하나 필수uuid: 특정 사용자 한 명의 푸시 토큰 조회uuids: 최대 100명의 사용자 푸시 토큰 조회
- 멀티 디바이스 지원으로 사용자별 여러 푸시 토큰 등록 가능
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| uuid | String | 사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능 | O* |
| uuids | String[] | 사용자 고유 아이디(uuid) 목록, ID 100개 이하 | O* |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| uuid | String | 사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능 | O |
| device_id | String | 동일 사용자의 기기(Device)를 구분하는 ID | X |
| push_type | String | 푸시 서버 타입, apns 혹은 fcm | O |
| push_token | String | APNs(64자), FCM으로부터 발급받은 푸시 토큰 | O |
| created_at | Datetime | 푸시 토큰을 처음 등록한 시각 | O |
| updated_at | Datetime | 푸시 토큰을 업데이트한 시각 | O |
요청: uuid로 요청
curl -v -G GET "https://kapi.kakao.com/v2/push/tokens" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "uuid=1234"
요청: 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"]'
응답
// 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를 사용합니다. 사용자가 특정 기기에서만 로그아웃하거나 푸시 알림을 끈 경우, 특정 기기의 푸시 토큰만 지정하여 폐기할 수 있습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| uuid | Long | 사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능device_id, push_type 미지정 시 해당 사용자의 모든 푸시 토큰 폐기 | 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;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 OKContent-Length: 0Content-Type: application/json;charset=UTF-8
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | https://kapi.kakao.com/v2/push/send | 서비스 앱 어드민 키 |
푸시 알림을 전송합니다.
수신할 사용자의 uuid로 등록된 모든 기기로 푸시 알림이 발송됩니다.
단, 요청 성공 응답은 푸시가 기기에 전송되었음을 보장하지 않습니다. APNs, FCM의 서버 상태에 따라 푸시 알림이 전송되지 않을 수 있습니다.
푸시 알림 발송에 실패한 경우, 요청 시 전달한 return_url로 실패 내역의 피드백(Feedback)을 받을 수 있습니다. 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 | 메시지를 구성하는 파라미터 APNs는 for_apns, FCM은 for_fcm 하위에 각 서비스 규격에 따른 전송 항목 포함두 서비스를 모두 사용하려면 for_apns, for_fcm 모두 포함전달할 내용이 없다면 비어 있는 대괄호( {})라도 보내야 함아래 PushMsgJson 구성 참고 | O |
| bypass | Boolean | 토큰 관리를 자체적으로 할 경우, 바이패스(bypass)용으로 푸시 알림을 사용할지의 여부 기본 값 falsebypass 사용 시 푸시 토큰을 push_message 내용인 PushMsgJson에 포함해야 함 | X |
bypass 파라미터
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) 상태에서도 푸시를 받을 수 있도록 할지 설정 | 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) | X |
| pushToken | String | 푸시 전송에 실패한 푸시 토큰 | X |
| date | Long | 전송 실패 시간, 유닉스 타임스탬프 형식(단위: 밀리초) | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| userId | String | 푸시 전송에 실패한 푸시 토큰의 uuid(user_id) | X |
| pushToken | String | 푸시 전송에 실패한 푸시 토큰 | X |
| date | Long | 전송 실패 시간, 유닉스 타임스탬프 형식(단위: 밀리초) | X |
| newPushToken | String | 바이패스(bypass) 사용 시 조건부 응답 값, 새로운 푸시 토큰 서비스에서 푸시 토큰을 자체적으로 관리할 경우, 해당 uuid(user_id)의 푸시 토큰을 갱신하기 위한 용도 | X |
요청
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}" \--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": "나의 댓글을 받아랏!...(생략)"}}}'
PushMsgJson
{"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 OKContent-Length: 0Content-Type: application/json;charset=UTF-8
응답: APNs 푸시 전송 실패 피드백
POST /fcm_push_fail HTTP/1.1Host: example.comContent-Type: application/x-www-form-urlencodeduserId=123&pushToken=abcdefg&date=1396582208000
응답: FCM 푸시 전송 실패 피드백
POST /fcm_push_fail HTTP/1.1Host: example.comContent-Type: application/x-www-form-urlencodeduserId=123&pushToken=abcdefg&date=1396582208000&newPushToken=AAbbccddee