REST API

이 문서는 REST API를 사용한 푸시 알림 구현 방법을 안내합니다.

이 문서에 포함된 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.

REST API 테스트 도구outlink

푸시 토큰 등록하기

기본 정보

메서드	URL	인증 방식
POST	https://kapi.kakao.com/v2/push/register	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
-	푸시 알림 활성화	-	-

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

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

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;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	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
-	푸시 알림 활성화	-	-

카카오 푸시 서비스에 등록된 사용자의 푸시 토큰 정보를 조회하는 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;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입니다. 사용자가 로그아웃하거나 푸시 알림을 끄는 경우, 더 이상 푸시 알림이 보내지지 않도록 하기 위해 이 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;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 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 전송 가능 용량

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

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;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 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

더 보기

REST API 레퍼런스REST API 테스트 도구outlink