PUSH API v2 가이드


기본 정보

API URL

https://sens.apigw.ntruss.com/push/v2

SENS Push API v2 Swagger 바로가기

API Header

항목 Mandatory 설명
Content-Type Mandatory 요청 Body Content Type을 application/json으로 지정 (POST)
x-ncp-apigw-timestamp Mandatory 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타낸 것이다.
API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
x-ncp-iam-access-key Mandatory 포탈 또는 Sub Account에서 발급받은 Access Key ID
x-ncp-apigw-signature-v2 Mandatory 위 예제의 Body를 Access Key Id와 맵핑되는 SecretKey로 암호화한 서명
HMAC 암호화 알고리즘은 HmacSHA256 사용

 

디바이스

디바이스 토큰 등록

디바이스 토큰을 등록하고, 사용자에 바인딩합니다. Swagger 바로가기

요청 URL

POST https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/users

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디

Headers

API Header 바로가기

요청 Body

{
    "userId":"string",
    "country":"string",
    "language":"string",
    "timezone":"integer",
    "channelName":"string",
    "deviceType":"(GCM|APNS)",
    "deviceToken":"string",
    "isNotificationAgreement":"boolean",
    "isAdAgreement":"boolean",
    "isNightAdAgreement":"boolean"
}
항목 Mandatory Type 설명 비고
userId Madantory String 사용자 아이디 사용자를 식별하는 아이디. 최대 128자
country Optional String 국가코드 디바이스 국가 설정 (기본: KR)
* ISO-3166-1 alpha-2
* 대문자만 가능
language Optional String 언어코드 디바이스 언어 설정 (기본: ko)
* ISO-639-1
* 소문자만 가능
timezone Optional Integer 타임존 Number of seconds away from UTC (기본: 32400)
* Example: 28800 (UTC+8)
channelName Optional String 등록할 채널명 등록된 채널명을 입력하면, 채널에 추가
deviceType Mandatory String 디바이스 타입 GCM - Android
APNS - iOS
deviceToken Mandatory String 디바이스 토큰
isNotificationAgreement Mandatory Boolean 푸시 알림 메시지 수신여부 false 시 모든 메시지 미수신
isAdAgreement Mandatory Boolean 광고성 메시지 수신여부 false 시 광고성 메시지 미수신
(messageType: AD)
isNightAdAgreement Mandatory Boolean 야간 광고성 메시지 수신여부 false 시 야간 광고성 메시지 미수신
(messageType: AD)
(야간 - 오후 9시 ~ 익일 오전 8시)

응답 Body

없음

응답 Status

HTTP Status Desc
201 Created (등록 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

디바이스 토큰 조회

등록된 디바이스/사용자를 조회합니다. Swagger 바로가기

요청 URL

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
userId Mandatory String 사용자 아이디 디바이스 토큰 등록 시 바인딩한 사용자 아이디

Headers

API Header 바로가기

요청 Body

없음

응답 Body

{
    "userId":"string",
    "country":"string",
    "language":"string",
    "timezone":"integer",
    "channelName":"string",
    "notificationAgreement":"boolean",
    "adAgreement":"boolean",
    "nightAdAgreement":"boolean",
    "notificationAgreementTime":"datetime",
    "adAgreementTime":"datetime",
    "nightAdAgreementTime":"datetime",
    "createTime":"datetime",
    "updateTime":"datetime",
    "devices":[
        {
            "deviceType":"(GCM|APNS)",
            "deviceToken":"string"
        }
    ]
}
항목 Mandatory Type 설명 비고
userId Madantory String 사용자 아이디
country Madantory String 국가코드 디바이스 국가 설정 (기본: KR)
* ISO-3166-1 alpha-2
* 대문자만 가능
language Madantory String 언어코드 디바이스 언어 설정 (기본: ko)
* ISO-639-1
* 소문자만 가능
timezone Madantory Integer 타임존 Number of seconds away from UTC (기본: 32400)
* Example: 28800 (UTC+8)
channelName Optional String 등록된 채널명
notificationAgreement Mandatory Boolean 푸시 알림 메시지 수신여부 false 시 모든 메시지 미수신
adAgreement Mandatory Boolean 광고성 메시지 수신여부 false 시 광고성 메시지 미수신
(messageType: AD)
nightAdAgreement Mandatory Boolean 야간 광고성 메시지 수신여부 false 시 야간 광고성 메시지 미수신
(messageType: ADA)
(야간 - 오후 9시 ~ 익일 오전 8시)
notificationAgreementTime Mandatory DateTime 푸시 알림 메시지 수신동의 시간 가장 최근 수신동의한 시간
adAgreementTime Mandatory DateTime 광고성 메시지 수신동의 시간 가장 최근 수신동의한 시간
nightAdAgreementTime Mandatory DateTime 야간 광고성 메시지 수신동의 시간 가장 최근 수신동의한 시간
createTime Mandatory DateTime 토큰 등록 시간
updateTime Mandatory DateTime 토큰 수정 시간
devices.deviceType Mandatory String 디바이스 타입 GCM - Android
APNS - iOS
devices.deviceToken Mandatory String 디바이스 토큰

응답 Status

HTTP Status Desc
200 OK (조회 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

디바이스 토큰 삭제

사용자(userId)에 바인딩된 디바이스를 모두 삭제합니다. 사용자도 함께 삭제됩니다. Swagger 바로가기

요청 URL

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
userId Mandatory String 사용자 아이디 디바이스 토큰 등록 시 바인딩한 사용자 아이디

Headers

API Header 바로가기

요청 Body

없음

응답 Body

없음

응답 Status

HTTP Status Desc
204 No Content (삭제 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

 

채널

채널 생성

채널을 생성합니다. Swagger 바로가기

요청 URL

POST https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
channelName Mandatory String 채널명 생성할 채널명

Headers

API Header 바로가기

요청 Body

{
    "channelName":"string",
    "channelDesc":"string"
}
항목 Mandatory Type 설명 비고
channelName Mandatory String 채널명 생성할 채널명
channelDesc Optional String 채널 설명 생성할 채널 설명

응답 Body

없음

응답 Status

HTTP Status Desc
201 Created (추가 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict (채널명 중복)
500 Internal Server Error

채널에 사용자 추가

채널에 사용자를 추가합니다. Swagger 바로가기

요청 URL

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels/{channelName}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
channelName Mandatory String 채널명 사용자를 추가할 채널명
userId Mandatory String 사용자 아이디 디바이스 토큰 등록 시 바인딩한 사용자 아이디

Headers

API Header 바로가기

요청 Body

없음

응답 Body

없음

응답 Status

HTTP Status Desc
201 Created (추가 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

채널에 사용자 삭제

채널에서 사용자를 삭제합니다. Swagger 바로가기

요청 URL

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels/{channelName}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
channelName Mandatory String 채널명 사용자를 삭제할 채널명
userId Mandatory String 사용자 아이디 디바이스 토큰 등록 시 바인딩한 사용자 아이디

Headers

API Header 바로가기

요청 Body

없음

응답 Body

없음

응답 Status

HTTP Status Desc
204 No Content (삭제 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

 

메시지

메시지 발송

메시지를 발송합니다. Swagger 바로가기

요청 URL

POST https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/messages

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디

Headers

API Header 바로가기

요청 Body

{
    "messageType":"(AD | NOTIF)",
    "target":{
        "type":"(ALL | CHANNEL | USER)",
        "deviceType":"(GCM | APNS)",
        "to":[
            "string",
            "string"
        ],
        "country": [
            "string",
            "string"
        ]
    },
    "message":{
        "default":{
            "content":"string",
            "custom":{
                "customKey1":"customValue1",
                "customKey2":"customValue2"
            },
            "option":{

            },
            "i18n":{
                "default":{
                    "content":"string"
                },
                "[language]":{
                    "content":"string"
                }
            }
        },
        "gcm":{
            "content":"string",
            "custom":{
                "customKey1":"customValue1",
                "customKey2":"customValue2"
            },
            "option":{

            },
            "i18n":{
                "default":{
                    "content":"string"
                },
                "[language]":{
                    "content":"string"
                }
            }
        },
        "apns":{
            "content":"string",
            "custom":{
                "customKey1":"customValue1",
                "customKey2":"customValue2"
            },
            "option":{

            },
            "i18n":{
                "default":{
                    "content":"string"
                },
                "[language]":{
                    "content":"string"
                }
            }
        }
    },
    "reserveTime": "yyyy-MM-dd HH:mm",
    "reserveTimeZone": "string",
    "scheduleCode": "string"
}
항목 Mandatory Type 설명 비고
messageType Optional String 메시지 타입 NOTIF - 알림 메시지
AD - 광고성 메시지
(default: NOTIF)
target.type Mandatory String 수신대상 타입 ALL - 서비스에 등록된 모든 디바이스
CHANNEL - 채널에 등록된 모든 디바이스
USER - 사용자에 바인딩된 모든 디바이스
target.deviceType Optional String 수신대상 디바이스 타입 GCM - Android
APNS - iOS
(null 일 경우 모든 디바이스)
target.to Optional Array of String 수신대상 식별자 ALL - 입력 필요 없음
CHANNEL - 채널명
USER - 사용자아이디
target.country Optional Array of String 수신대상 국가코드 수신대상 디바이스 국가코드
* ISO-3166-1 alpha-2
* 대문자만 가능
message Mandatory Object 발송 공통메시지 메시지 규격은 아래 공통메시지 규격 참고
message.i18n Optional Object 디바이스 언어별 다국어 메시지 처리를 위한 객체 메시지 규격은 아래 다국어 메시지 규격 참고
reserveTime Optional String 예약 일시 메시지 발송 예약 일시 (yyyy-MM-dd HH:mm)
reserveTimeZone Optional String 예약 일시 타임존 예약 일시 타임존 (기본: Asia/Seoul)
* 지원 타임존 목록
* TZ database name 값 사용
scheduleCode Optional String 스케줄 코드 등록하려는 스케줄 코드

* Android 디바이스 메시지 발송에 GCM/FCM을 모두 지원하며, 네이버 클라우드 플랫폼 SENS에서는 Type을 GCM으로 사용합니다.

공통메시지

  • 메시지 발송 requestBody의 message 항목이 공통 메시지를 위한 규격이다.
  • message.default.XXX, message.gcm.XXX, message.apns.XXX로 구분이 가능하며, message.default는 필수로 작성해야한다.
  • default만 작성 시 모든 Push Type에 동일한 메시지가 발송되며, gcm, apns 작성시 각 Push Type별로 메시지 분리가 가능하다.
  • 적용 우선순위는 gcm = apns > default 이다.
  • message에 아래 표대로 메시지를 작성하면, 각 Push Type에 맞게 메시지가 생성되어 발송된다.
message 하위 항목 Mandatory Type GCM APNS
content Optional String data.content alert or alert.body
custom Optional Object data.KEY로 지정 aps와 동일한 레벨의 KEY로 지정
option Optional Object 아래 Push Type 별 사용 가능한 option 참조
i18n Optional Object

다국어 메시지

  • 디바이스에 설정된 language에 따라 다국어 메시지를 처리하기 위한 규격이다.
  • message.default.XXX, message.[language].XXX로 구분 가능하며, language는 ISO-639-1 표준을 따르며, 소문자만 사용 가능하다.
  • language는 디바이스 등록시 설정된 언어코드 기준이다.
  • 적용 우선순위는 message.content보다 우선한다.
i18n 하위 항목 Mandatory Type GCM APNS
content Mandatory String data.content alert or alert.body

Push Type 별 사용 가능한 option

응답 Body

{
    "requestId":"string",
    "requestTime":"string",
    "statusCode":"string",
    "statusName":"string"
}
항목 Mandatory Type 설명 비고
requestId Mandatory String 요청 아이디
requestTime Mandatory DateTime 요청 시간
statusCode Mandatory String 요청 상태 코드 아래 Response Code 참조
statusName Mandatory String 요청 상태명 success - 성공
reserved - 예약중
scheduled - 스케줄중
fail - 실패

응답 Status

HTTP Status Desc
202 Accepted (발송 요청 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

메시지 발송 결과 조회

메시지 발송 결과를 조회합니다. Swagger 바로가기

요청 URL

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/messages/{requestId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
requestId Mandatory String 메시지 발송요청 아이디 메시지 발송시 반환되는 요청 식별자

Headers

API Header 바로가기

요청 Body

없음

응답 Body

{
    "requestId":"string",
    "requestTime":"string",
    "statusCode":"string",
    "statusName":"string",
    "messageStatusCode":"string",
    "messageStatusName":"string",
    "completeTime":"string",
    "targetCount":"integer",
    "sentCount":"integer",
    "messageType":"string",
    "target":{
        ...
    },
    "message":{
        ...
    }
}
항목 Mandatory Type 설명 비고
requestId Mandatory String 요청 아이디
requestTime Mandatory DateTime 요청 시간
statusCode Mandatory String 요청 상태 코드 202 - 성공
그외 - 실패
statusName Mandatory String 요청 상태명 success - 성공
fail - 실패
messageStatusCode Mandatory String 발송 상태 코드 200 - 성공
그외 - 실패
messageStatusName Mandatory String 발송 상태명 success - 성공
processing - 처리중
fail - 실패
completeTime Mandatory DateTime 발송 완료 시간
targetCount Mandatory Integer 요청 대상 디바이스 갯수
sentCount Mandatory Integer 발송 성공 디바이스 갯수
messageType Mandatory String 메시지 타입 NOTIF - 알림 메시지
AD - 광고성 메시지
target Mandatory Object 요청 target 정보
message Mandatory Object 요청 message 정보

응답 Status

HTTP Status Desc
200 OK (조회 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

 

예약 메시지

예약 메시지 상태 조회

메시지 발송 예약 상태를 조회합니다.

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/reservations/{reserveId}/reserve-status

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
reserveId Mandatory String 예약 메시지 아이디 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)

Headers

API Header 바로가기

요청 Body

없음

응답 Body

{
  "reserveId": "string",
  "reserveTimeZone": "string",
  "reserveTime": "string",
  "reserveStatus": "string"
}
항목 Mandatory Type 설명 비고
reserveId Mandatory String 예약 메시지 아이디 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)
reserveTime Mandatory String 예약 일시 메시지 발송 예약 일시 (yyyy-MM-dd HH:mm)
reserveTimeZone Mandatory String 예약 일시 타임존 예약 일시 타임존 (기본: Asia/Seoul)
* 지원 타임존 목록
* TZ database name 값 사용
reserveStatus Mandatory String 예약 상태 READY - 발송 대기
PROCESSING - 발송 요청중
CANCELED - 발송 취소
FAIL - 발송 요청 실패
DONE - 발송 요청 성공
STALE - 발송 요청 실패 (시간 초과)

예약 메시지 취소

메시지 발송 예약을 취소합니다.

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/reservations/{reserveId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
reserveId Mandatory String 예약 메시지 아이디 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)

Headers

API Header 바로가기

요청 Body

없음

응답 Body

없음

응답 Status

HTTP Status Desc
204 No Content (삭제 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

 

스케줄 메시지

스케줄 메시지 취소

메시지 발송 스케줄을 취소합니다.

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/schedules/{scheduleCode}/messages/{messageId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

항목 Mandatory Type 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
scheduleCode Mandatory String 스케줄 코드 스케줄 등록시 사용한 코드
messageId Mandatory String 예약 메시지 아이디 스케줄 발송 요청 조회 시 반환되는 메시지 식별자(requestId)

Headers

API Header 바로가기

요청 Body

없음

응답 Body

없음

응답 Status

HTTP Status Desc
204 No Content (삭제 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error