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

푸시 알림

REST API

이 문서는 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 값 변경

푸시 토큰 등록하기

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

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

허용 IP 주소 설정

푸시 알림 발송에 보다 안전을 기하려면 카카오 API를 호출하는 IP를 제한할 수 있습니다. [내 애플리케이션] > [허용 IP 주소]에서 사용할 IP를 등록합니다. 자세한 정보는 보안: 허용 IP 주소를 참고합니다.

uuid는 서비스에서 각 사용자에게 발급한 고유 숫자 값을 사용합니다. device_id는 푸시 알림을 받을 각 기기를 등록하기 위한 값입니다. 같은 사용자가 여러 대의 기기를 사용하는 경우, 푸시 토큰을 기기별로 등록해 푸시 알림을 보낼 수 있도록 하는 용도입니다.

푸시 토큰 등록 성공시, HTTP 상태 코드 200 응답과 함께 푸시 토큰이 며칠 뒤 만료되는지를 나타내는 숫자 값을 받습니다. 이 기간은 자동으로 갱신되지 않으므로, 기간 이내에 해당 사용자 및 기기에 대한 푸시 토큰을 재등록해야 합니다.

Request
URL
POST /v2/push/register HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Parameter
Name Type Description Required
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
Response
Key
Name Type Description
NONE Integer 푸시 토큰 만료 예정 기간, -1인 경우 무제한
Sample
Request
curl -v -X POST "https://kapi.kakao.com/v2/push/register" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK {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

30

푸시 토큰 보기

카카오 푸시 서비스에 등록된 사용자의 푸시 토큰 정보를 조회하는 API입니다.

푸시 토큰 보기 요청 시, uuid 또는 uuids 중 하나는 반드시 포함해야 합니다. uuid는 특정 사용자 한 명의 푸시 토큰을, uuids는 최대 100명의 사용자 푸시 토큰을 조회할 때 각각 사용합니다. 메소드는 GET 또는 POST를 사용하며, 앱 어드민 키를 사용해 서버에서 요청해야 합니다.

요청 성공 시 응답은 JSON Array로 푸시 토큰 정보를 받습니다. 카카오 푸시 알림 기능은 멀티 디바이스를 지원하므로, 각 사용자 앞으로 여러 개의 푸시 토큰이 등록돼 있을 수 있습니다. 각 푸시 토큰 정보는 uuid, device_id, 푸시 토큰 종류와 값, 생성 및 업데이트 일시를 포함합니다.

Request
URL
GET/POST /v2/push/tokens HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Parameter
Name Type Description Required
uuid String 사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능 O*
uuids String[] 사용자 고유 ID 목록, ID 100개 이하 O*

한 사용자의 푸시 토큰 정보를 요청하려면 uuid를 필수 파라미터로 전달, 여러 사용자의 푸시 토큰 정보를 요청하려면 uuids를 필수 파라미터로 전달

Response
Key
Name Type Description
user_id String Deprecated, uuid를 사용하도록 변경
사용자 고유 ID, 1~((2^63)-1) 범위의 정수만 사용 가능
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

푸시 토큰 보기 요청의 파라미터 중 'user_id'는 다른 푸시 API와 동일한 이름을 가지도록 'uuid'로 변경되었습니다. 'user_id'는 일정 유예기간 경과 후 제거 예정입니다(deprecated).

Sample
Request: uuid로 요청
curl -v -X GET "https://kapi.kakao.com/v2/push/tokens" 
  -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
  -d "uuid=1234"
Request: uuids로 요청
curl -v -X POST "https://kapi.kakao.com/v2/push/tokens" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK {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"
    }
]

푸시 토큰 삭제하기

특정 사용자의 푸시 토큰을 삭제하는 API입니다. 사용자가 로그아웃하거나 푸시 알림을 끄는 경우, 더 이상 푸시 알림이 보내지지 않도록 하기 위해 이 API를 사용합니다. 사용자가 특정 기기에서만 로그아웃하거나 푸시 알림을 끈 경우, 특정 기기의 푸시 토큰만 지정하여 삭제할 수 있습니다.

요청 시 파라미터로 uuid만 전달하면 해당 사용자의 푸시 토큰을 삭제합니다. 사용자의 푸시 토큰 중 특정 기기의 푸시 토큰만 삭제하려면 device_id 파라미터를 추가 전달합니다. push_type 파라미터로 사용자의 푸시 토큰 중 특정 서버 타입의 푸시 토큰만 삭제 요청할 수도 있습니다.

토큰 삭제 요청이 성공하면 HTTP 상태 코드 200 응답을 받으며 응답 바디(Body)는 없습니다.

Request
URL
POST /v2/push/deregister HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Parameter
Name Type Description Required
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
Sample
Request
curl -v -X POST "https://kapi.kakao.com/v2/push/deregister" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK {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

푸시 알림 보내기

푸시 알림을 보내는 API입니다. 수신할 사용자의 uuid로 등록된 모든 기기에 푸시 알림이 보내집니다.

요청 시 푸시 알림의 내용은 push_message 파라미터로 전달합니다. 파라미터 구성은 PushMsgJson에 정의하며 APNs만 요청 시 for_apns, FCM만 요청 시 for_fcm 내용을 각각 포함합니다. 둘 다 알림을 보낼 때는 for_apnsfor_fcm 모두 포함해야 합니다. 플랫폼별로 다소 구성이 다르니 파라미터 정보를 참고합니다.

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

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

전송 가능 용량(APNs)

APNs의 경우, APNs 서버에서 수신한 데이터 기준으로 푸시 알림 한 건의 전체 길이(위 파람에서 topic, push_alert, return_url, push_token 제외한 파람 길이)가 4KB를 넘을 수 없습니다(iOS7까지는 256bytes). VoIP 알림의 경우, 최대 5KB를 지원합니다.

4KB가 넘고 messageString 타입인 경우, message 내용의 끝을 자르고 ".."를 붙여 전송합니다. 메시지 경량화를 위해 특정 푸시 알림 메시지 포맷을 미리 앱에 저장하고 포맷의 키와 파라미터만 넘기는 방법도 제공합니다. (참고: Creating the Remote Notification Payload)

Localized Formatted String 기능은 다음과 같이 사용 가능하며, 앱에 알림 포맷을 지정하고 COMMENT_ALERT_FORMAT을 이용해 푸시 알림 보내기 요청 시 실제 사용돼야 할 값을 전달합니다.

{
  "message":{
    "loc-key" : "COMMENT_ALERT_FORMAT",
    "loc-args" : ["홍길동", "2"]
  }
}
%@님 외 %@명이 댓글을 달았습니다.

실제 푸시 알림은 다음과 같이 전달됩니다.

홍길동님 외 2명이 댓글을 달았습니다.
Request
URL
POST /v2/push/send HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Parameter
Name Type Description Required
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
Name Type Description Sample Required
topic String VoIP(Voice over Internet Protocol)를 사용할 경우에 설정 "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 or Json APNs 기준 alert에 해당, 알림센터에 표시할 내용 "내가 쓴 글에 댓글이 달렸습니다." X
custom_field Dictionary 메시지 외 앱에 부가적인 정보를 전달하고자 할 때 사용 {"article_id" : 111} X
return_url String 푸시 알림 전송 실패 피드백(feedback) 처리가 필요할 때 사용
"BadDeviceToken", "Unregistered", "DeviceTokenNotForTopic" 등 실패 발생
https://example.com/
fcm_push_fail
X
push_token String 바이패스(bypass)를 사용할 경우 자체 관리하는 푸시 토큰 "AAABBBCCCDDD" X
apns_env String 푸시를 보낼 APNs 서버 설정 ("sandbox", "production"(기본값)) "sandbox" X
PushMsgJson: for_fcm
Name Type Description Sample Required
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 푸시 알림 전송 실패 피드백(feedback) 처리가 필요할 때 사용 https://example.com/
fcm_push_fail
X
push_token String 바이패스(bypass)를 사용할 경우 자체 관리하는 푸시 토큰 "AAABBBCCCDDD" X
Response
Key: APNs 푸시 전송 실패
Name Type Description
userId String 푸시 전송에 실패한 푸시 토큰의 uuid(user_id)
pushToken String 푸시 전송에 실패한 푸시 토큰
date Long 전송 실패 시간, 정수로 된 유닉스 타임스탬프(Unix timestamp), 밀리초(millisecond) 단위
Key: FCM 푸시 알림 실패
Name Type Description
userId String 푸시 전송에 실패한 푸시 토큰의 uuid(user_id)
pushToken String 푸시 전송에 실패한 푸시 토큰
date Long 전송 실패 시간, 정수로 된 유닉스 시간(Unix timestamp), 밀리초(millisecond) 단위
newPushToken String 바이패스(bypass) 사용 시 조건부 응답 값, 새로운 푸시 토큰
서비스에서 푸시 토큰을 자체적으로 관리할 경우, 해당 uuid(user_id)의 푸시 토큰을 갱신하기 위한 용도
Sample
Request
curl -v -X POST "https://kapi.kakao.com/v2/push/send" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK {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": "나의 댓글을 받아랏!...(생략)"
    }
  }
}
Response: 푸시 전송 요청 성공
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
Response: 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: 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

더보기