페이지 이동경로
  • 문서>
  • 푸시 알림>
  • REST API

푸시 알림

REST API

이 문서는 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 서비스 앱 어드민 키
권한 사전 설정 카카오 로그인 동의항목
- 푸시 알림 활성화 - -

푸시 알림을 받을 사용자의 푸시 토큰(디바이스 토큰)을 카카오 푸시 서비스에 등록하는 API입니다.

앱 어드민 키(Admin Key)와 APNs, FCM으로부터 발급 받은 푸시 토큰이 필요합니다. 어드민 키를 사용하는 API이므로 보안 위험을 피하기 위해 반드시 서버에서 호출해야 합니다.

허용 IP 주소 설정

푸시 알림 발송에 보다 안전을 기하려면 카카오 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)를 구분하는 ID
uuid 내에서 유일한 값이어야 함
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를 사용하도록 변경

예제

요청: 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" \
  -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_apnsfor_fcm 모두 포함해야 합니다.

요청 성공 시 응답의 HTTP 상태 코드는 200이고, 응답 본문은 없습니다. 단, 요청 성공 응답은 푸시가 기기에 전송되었음을 보장하지 않습니다. APNs, FCM의 서버 상태가 좋지 않을 경우 푸시 알림이 전송되지 않을 수 있습니다.

푸시 알림 보내기에 실패했을 경우, 요청 시 전달한 return_url로 실패 내역의 피드백(Feedback)을 받을 수 있습니다. 실패 피드백은 uuid, device_id, 푸시 토큰, 실패 시각을 포함합니다. FCM의 경우, 푸시 토큰 갱신을 위한 새 푸시 토큰 값을 포함하는 경우가 있습니다.

APNs 전송 가능 용량

APNs는 푸시 알림 한 건당 4KB 이하, iOS 7 이하인 경우 256bytes 이하여야 전송 가능합니다. 전송 가능 용량 제한은 수신 데이터 기준이며 topic, push_alert, return_url, push_token를 제외한 파라미터에 적용됩니다. VoIP(Voice over Internet Protocol) 알림의 경우, 최대 5KB까지 지원합니다. 전송하려는 데이터의 용량이 4KB 이상이고 messageString 타입인 경우, message 값의 뒷부분을 자르고 ".."를 붙여 전송합니다.

APNs 앱 번들의 메시지 세트 활용 방법

메시지 경량화 및 사용자 맞춤형 콘텐츠 활용을 위해 특정 푸시 알림 메시지 세트(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

바이패스(Bypass, 우회로)는 카카오 플랫폼에 푸시 토큰을 등록하지 않고, 서비스 서버에서 자체적으로 푸시 토큰을 관리하는 경우에 사용하는 파라미터입니다. 푸시 토큰 정보가 없으면 알림 보내기 요청이 실패하므로, 푸시 메시지를 구성하는 파라미터인 push_message 값에 푸시 토큰을 전달하는 방식으로 요청해야 합니다.

PushMsgJson: for_apns
이름 타입 설명 예제 필수
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
PushMsgJson: for_fcm
이름 타입 설명 예제 필수
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

응답

본문: APNs 푸시 전송 실패 시
이름 타입 설명
userId String 푸시 전송에 실패한 푸시 토큰의 uuid(user_id)
pushToken String 푸시 전송에 실패한 푸시 토큰
date Long 전송 실패 시간, 정수로 된 유닉스 타임스탬프(Unix timestamp), 밀리초(millisecond) 단위
본문: FCM 푸시 알림 실패 시
이름 타입 설명
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": "나의 댓글을 받아랏!...(생략)"
    }
  }
}'
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 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
응답: APNs 푸시 전송 실패 피드백
POST /fcm_push_fail HTTP/1.1
Host: example.com
Content-type: application/x-www-form-urlencoded

userId=123&pushToken=abcdefg&date=1396582208000
응답: 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

더 보기