브랜드 메시지 API

Prev Next

기본 정보

API URL

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

SENS 브랜드메시지 API 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 사용

NAVER CLOUD PLATFORM 인증키 및 Signature 생성 가이드 바로가기

메시지 발송 기본 정보

기본 정보

  • SMS Failover는 아직 지원하지 않습니다. (26년 1Q 내 지원 예정)
  • 예약 발송은 아직 지원하지 않습니다. (26년 1Q 내 지원 예정)

요청 URL

POST https://sens.apigw.ntruss.com/brandmessage/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

메시지 발송(자유형), 메시지 발송(기본형) 가이드 참조

응답 Body

{
    "requestId":"string",
    "requestTime":"string",
    "statusCode":"string",
    "statusName":"string",
    "messages":[
        {
            "messageId":"string",
            "countryCode":"string",
            "to":"string",
            "requestStatusCode":"string",
            "requestStatusName":"string",
            "requestStatusDesc":"string",
            "useSmsFailover":"boolean"
        }
    ]
}
항목 Mandatory Type 설명 비고
requestId Mandatory String 발송 요청 아이디
requestTime Mandatory DateTime 발송 요청 시간 yyyy-MM-dd'T'HH:mm:ss.SSS
statusCode Mandatory String 요청 상태 코드 202 - 성공
그외 - 실패
* HTTP Status 규격을 따름
statusName Mandatory String 요청 상태명 success - 성공
processing - 처리중
reserved - 예약중
fail - 실패
messages.messageId Mandatory String 메시지 아이디
messages.countryCode Optional String 수신자 국가번호 default: 82
messages.to Mandatory String 수신자번호
messages.requestStatusCode Mandatory String 발송요청 상태 코드 A000 - 성공
그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
messages.requestStatusName Mandatory String 발송요청 상태명 success - 성공
fail - 실패
messages.requestStatusDesc Mandatory String 발송요청 상태 내용
messages.useSmsFailover Mandatory Boolean SMS Failover 사용 여부

응답 Status

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

메시지 발송 (자유형)

  • 타겟팅 코드를 지정해 메시지 대상의 타입을 지정할 수 있습니다.
    • M: 고객사의 광고성 정보 수신동의 유저(카카오톡 수신 동의)
    • N: 고객사의 광고성 정보 수신동의 유저(카카오톡 수신 동의) - 채널 친구
    • I: 고객사의 발송 요청 대상 ∩ 채널 친구
  • 브랜드메시지 사용 신청이 완료된 채널에 한해 타겟팅 코드 M, N 발송을 사용할 수 있습니다.
  • 타겟팅 코드 M, N 발송 시, 채널에 지정된 080 무료수신거부번호를 사용합니다.
  • AC 버튼을 사용할 수 없습니다.
  • 야간 발송 제한이 적용됩니다. (20:50 ~ 익일 08:00)

텍스트형(TEXT) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 텍스트형(TEXT)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].content Mandatory String 최대 1,300자
줄바꿈 최대 99개
messages[].buttons Optional List of Object 버튼 정보 쿠폰 사용 시 최대 4개, 그 외 최대 5개
messages[].buttons[].type Mandatory String 버튼 Type
messages[].buttons[].name Mandatory String 버튼명 최대 14자
messages[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].coupon Optional Object 쿠폰 정보
messages[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional

이미지형(IMAGE) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "image":{
                "imageId":"string",
                "imageLink":"string"
            },
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 이미지형(IMAGE)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].content Mandatory String 최대 1,300자
줄바꿈 최대 99개
messages[].buttons Optional List of Object 버튼 정보 쿠폰 사용 시 최대 4개, 그 외 최대 5개
messages[].buttons[].type Mandatory String 버튼 Type
messages[].buttons[].name Mandatory String 버튼명 최대 14자
messages[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].image Optional Object 이미지 이미지 업로드 참조
messages[].image.imageId Mandatory String 이미지 아이디
messages[].image.imageLink Mandatory String 이미지 링크
messages[].coupon Optional Object 쿠폰 정보
messages[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional

와이드 이미지형(WIDE_IMAGE) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "image":{
                "imageId":"string",
                "imageLink":"string"
            },
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 와이드이미지형(WIDE_IMAGE)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].content Mandatory String 최대 1,300자
줄바꿈 최대 99개
messages[].buttons Optional List of Object 버튼 정보 최대 2개
messages[].buttons[].type Mandatory String 버튼 Type
messages[].buttons[].name Mandatory String 버튼명 최대 8자
messages[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].image Optional Object 이미지 이미지 업로드 참조
messages[].image.imageId Mandatory String 이미지 아이디
messages[].image.imageLink Mandatory String 이미지 링크
messages[].coupon Optional Object 쿠폰 정보
messages[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional

와이드 아이템 리스트형(WIDE_ITEM_LIST) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "headerContent":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "item":[
                {
                    "title":"string",
                    "imageId":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                }
            ],
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 와이드 아이템 리스트형(WIDE_ITEM_LIST)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].headerContent Mandatory String 헤더 최대 20자
messages[].buttons Optional List of Object 버튼 정보 최대 2개
messages[].buttons[].type Mandatory String 버튼 Type
messages[].buttons[].name Mandatory String 버튼명 최대 8자
messages[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].coupon Optional Object 쿠폰 정보
messages[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].item Mandatory Object
messages[].item.list Mandatory List of Object 와이드 리스트 최소 3개, 최대 4개
messages[].item.list[].title Mandatory String 아이템 제목 1번째 아이템
- Optional
- 최대 25자
- 줄바꿈 최대 1개
2~4번째 아이템
- 최대 30자
- 줄바꿈 최대 1개
messages[].item.list[].imageId Mandatory String 이미지 아이디 1번째 아이템
- 메인 와이드 아이템 리스트 이미지
2~4번째 아이템
- 서브 와이드 아이템 리스트 이미지
messages[].item.list[].linkMobile Mandatory String 모바일 웹 링크 최대 1,000자
messages[].item.list[].linPc Optional String PC 웹 링크 최대 1,000자
messages[].item.list[].schemeAndroid Optional String Android 앱 링크 최대 1,000자
messages[].item.list[].schemeIos Optional String iOS 앱 링크 최대 1,000자

커머스형(COMMERCE) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "additionalContent":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "image":{
                "imageId":"string",
                "imageLink":"string"
            },
            "commerce": {
                "title":"string",
                "regularPrice":"integer",
                "discountPrice":"integer",
                "discountRate":"integer",
                "discountFixed":"integer"
            },
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 커머스형(COMMERCE)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].additionalContent Optional String 부가 내용 최대 34자
줄바꿈 최대 1개
messages[].buttons Mandatory List of Object 버튼 정보 최소 1개, 최대 2개
messages[].buttons[].type Mandatory String 버튼 Type
messages[].buttons[].name Mandatory String 버튼명 최대 8자
messages[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].image Optional Object 이미지 이미지 업로드 참조
messages[].image.imageId Mandatory String 이미지 아이디
messages[].image.imageLink Mandatory String 이미지 링크
messages[].coupon Optional Object 쿠폰 정보
messages[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].commerce Mandatory Object 커머스 정보
messages[].commerce.title Mandatory String 상품 제목 최대 30자
messages[].commerce.regularPrice Mandatory Integer 상품 정상 가격 0 ~ 99,999,999
messages[].commerce.discountPrice Optional Integer 상품 할인 가격 0 ~ 99,999,999
messages[].commerce.discountRate Optional Integer 상품 할인율 0 ~ 100
할인 가격 사용시, 정액 할인 가격 or 상품 할인율 중 하나는 Mandatory
messages[].commerce.discountFixed Optional Integer 상품 정액 할인 가격 0 ~ 999,999
할인 가격 사용시, 정액 할인 가격 or 상품 할인율 중 하나는 Mandatory

캐러셀 커머스형(CAROUSEL_COMMERCE) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "carousel": {
                "head": {
                    "headerContent":"string",
                    "content":"string",
                    "imageId":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                },
                "list": [
                    {
                        "additionalContent":"string",
                        "image":{
                            "imageId":"string",
                            "imageLink":"string"
                        },
                        "buttons":[
                            {
                                "type":"string",
                                "name":"string",
                                "linkMobile":"string",
                                "linkPc":"string",
                                "schemeAndroid":"string",
                                "schemeIos":"string",
                                "bizFormId":"string"
                            }
                        ],
                        "coupon": {
                            "title":"string",
                            "description":"string",
                            "linkMobile":"string",
                            "linkPc":"string",
                            "schemeAndroid":"string",
                            "schemeIos":"string"
                        },
                        "commerce": {
                            "title":"string",
                            "regularPrice":"integer",
                            "discountPrice":"integer",
                            "discountRate":"integer",
                            "discountFixed":"integer"
                        }
                    }
                ],
                "tail": {
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                }
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 캐러셀 커머스형(CAROUSEL_COMMERCE)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].carousel Mandatory Object 캐러셀 정보
messages[].carousel.head Optional Object 캐러셀 인트로 정보
messages[].carousel.head.headerContent Mandatory String 헤더 최대 20자
messages[].carousel.head.content Mandatory String 내용 최대 50자
messages[].carousel.head.imageId Mandatory String 이미지 아이디 CAROUSEL_COMMERCE 타입 이미지만 사용 가능
캐러셀 리스트 이미지와 비율이 동일해야함
messages[].carousel.head.linkMobile Optional String 모바일 웹 링크 최대 1,000자
schemeAndroid 또는 schemeIos 사용시, Mandatory
messages[].carousel.head.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].carousel.head.schemeAndroid Optional String Android 앱 링크 최대 1,000자
messages[].carousel.head.schemeIos Optional String iOS 앱 링크 최대 1,000자
messages[].carousel.list Mandatory List of Object 캐러셀 리스트 캐러셀 인트로(head)를 사용할 경우 최소 1개, 최대 5개
그 외에는 최소 2개, 최대 6개
messages[].carousel.list[].additionalContent Mandatory String 캐러셀 리스트 아이템 부가 내용 최대 34자
messages[].carousel.list[].image Mandatory Object 캐러셀 리스트 아이템 이미지 정보 이미지 업로드 참조
messages[].carousel.list[].image.imageId Mandatory String 이미지 아이디
messages[].carousel.list[].image.imageLink Mandatory String 이미지 링크 최대 1,000자
messages[].carousel.list[].buttons Mandatory List of Object 버튼 정보 최소 1개, 최대 2개
messages[].carousel.list[].buttons[].type Mandatory String 버튼 Type
messages[].carousel.list[].buttons[].name Mandatory String 버튼명 최대 8자
messages[].carousel.list[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].carousel.list[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].carousel.list[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].carousel.list[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].carousel.list[].buttons[].bizFormId Optional String
messages[].carousel.list[].coupon Optional Object 쿠폰 정보
messages[].carousel.list[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].carousel.list[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].carousel.list[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].carousel.list[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].carousel.list[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].carousel.list[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].carousel.list[].commerce Mandatory Object 커머스 정보
messages[].carousel.list[].commerce.title Mandatory String 상품 제목 최대 30자
messages[].carousel.list[].commerce.regularPrice Mandatory Integer 상품 정상 가격 0 ~ 99,999,999
messages[].carousel.list[].commerce.discountPrice Optional Integer 상품 할인 가격 0 ~ 99,999,999
messages[].carousel.list[].commerce.discountRate Optional Integer 상품 할인율 0 ~ 100
할인 가격 사용시, 정액 할인 가격 or 상품 할인율 중 하나는 Mandatory
messages[].carousel.list[].commerce.discountFixed Optional Integer 상품 정액 할인 가격 0 ~ 999,999
할인 가격 사용시, 정액 할인 가격 or 상품 할인율 중 하나는 Mandatory
messages[].carousel.tail Optional Object 캐러셀 더보기 정보
messages[].carousel.tail.linkMobile Mandatory String 모바일 웹 링크 최대 1,000자
messages[].carousel.tail.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].carousel.tail.schemeAndroid Optional String Android 앱 링크 최대 1,000자
messages[].carousel.tail.schemeIos Optional String iOS 앱 링크 최대 1,000자

캐러셀 피드형(CAROUSEL_FEED) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "carousel": {
                "list": [
                    {
                        "headerContent":"string",
                        "message":"string",
                        "image":{
                            "imageId":"string",
                            "imageLink":"string"
                        },
                        "buttons":[
                            {
                                "type":"string",
                                "name":"string",
                                "linkMobile":"string",
                                "linkPc":"string",
                                "schemeAndroid":"string",
                                "schemeIos":"string",
                                "bizFormId":"string"
                            }
                        ],
                        "coupon": {
                            "title":"string",
                            "description":"string",
                            "linkMobile":"string",
                            "linkPc":"string",
                            "schemeAndroid":"string",
                            "schemeIos":"string"
                        }
                    }
                ],
                "tail": {
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                }
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 캐러셀피드형(CAROUSEL_FEED)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].carousel Mandatory Object 캐러셀 정보
messages[].carousel.list Mandatory List of Object 캐러셀 리스트 최소 2개, 최대 6개
messages[].carousel.list[].headerContent Mandatory String 캐러셀 리스트 아이템 제목 최대 20자
messages[].carousel.list[].message Mandatory String 캐러셀 리스트 아이템 메시지 최대 180자
messages[].carousel.list[].image Mandatory Object 캐러셀 리스트 아이템 이미지 정보 이미지 업로드 참조
messages[].carousel.list[].image.imageId Mandatory String 이미지 아이디
messages[].carousel.list[].image.imageLink Mandatory String 이미지 링크 최대 1,000자
messages[].carousel.list[].buttons Mandatory List of Object 버튼 정보 최대 1개, 최대 2개
messages[].carousel.list[].buttons[].type Mandatory String 버튼 Type
messages[].carousel.list[].buttons[].name Mandatory String 버튼명 최대 8자
messages[].carousel.list[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].carousel.list[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].carousel.list[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].carousel.list[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].carousel.list[].buttons[].bizFormId Optional String
messages[].carousel.list[].coupon Optional Object 쿠폰 정보
messages[].carousel.list[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].carousel.list[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].carousel.list[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].carousel.list[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].carousel.list[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].carousel.list[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].carousel.tail Optional Object 캐러셀 더보기 정보
messages[].carousel.tail.linkMobile Mandatory String 모바일 웹 링크 최대 1,000자
messages[].carousel.tail.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].carousel.tail.schemeAndroid Optional String Android 앱 링크 최대 1,000자
messages[].carousel.tail.schemeIos Optional String iOS 앱 링크 최대 1,000자

프리미엄 동영상형(PREMIUM_VIDEO) 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "headerContent":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            },
            "video": {
                "thumbnailId":"string",
                "videoUrl":"string"
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 프리미엄 동영상형(PREMIUM_VIDEO)
isAdult Optional Boolean 대상 연령 성인: true
전체: false (default)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].content Optional String 최대 1,300자
줄바꿈 최대 99개
messages[].headerContent Optional String 헤더 최대 20자
messages[].buttons Optional List of Object 버튼 정보 최대 1개
messages[].buttons[].type Mandatory String 버튼 Type
messages[].buttons[].name Mandatory String 버튼명 최대 8자
messages[].buttons[].linkMobile Optional String 모바일 웹 링크 WL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].linkPc Optional String PC 웹 링크 WL 타입일 경우, Optional이
최대 1,000자
messages[].buttons[].schemeAndroid Optional String Android 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].buttons[].schemeIos Optional String iOS 앱 링크 AL 타입일 경우, Mandatory
최대 1,000자
messages[].coupon Optional Object 쿠폰 정보
messages[].coupon.title Mandatory String 쿠폰 제목 5가지 형식만 사용 가능
- 이하숫자원할인쿠폰{1 ~ 100 숫자}% 할인 쿠폰
- 배송비 할인 쿠폰
- 자이내무료쿠폰{7자 이내} UP 쿠폰
messages[].coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
messages[].coupon.linkMobile Optional String 모바일 웹 링크 최대 1,000자
linkMobile 필드를 사용할 경우 나머지 필드는 Optional
messages[].coupon.linkPc Optional String PC 웹 링크 최대 1,000자
messages[].coupon.schemeAndroid Optional String Android 앱 링크 최대 1,000자
schemeAndroid 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].coupon.schemeIos Optional String iOS 앱 링크 최대 1,000자
schemeIos 필드에 채널 쿠폰 URL(형식: alimtalk=coupon://)을 사용할 경우 나머지 필드는 Optional
messages[].video Mandatory Object 동영상 정보
messages[].video.thumbnailId Mandatory String 동영상 썸네일용 이미지 아이디 최대 500자
messages[].video.videoUrl Mandatory String 카카오TV 동영상 URL 최대 500자
카카오TV에 업로드된 동영상만 사용 가능

버튼 정보

Type Name Mandatory 비고
WL 웹 링크 linkMobile http:// 또는 https://로 시작하는 URL
AL 앱 링크 linkMobile, schemeIos, schemeAndroid 중 2개
BF 비지니스 폼 bizFormId 버튼명(name)에 5가지 형식만 사용 가능
- 톡에서 설문하기
- 톡에서 응모하기
- 톡에서 예약하기
TEXT, IMAGE 템플릿의 경우 첫 번째, 그 외에는 마지막 버튼으로만 사용 가능
AC 버튼과 함께 사용하는 경우, AC 순서가 우선 (AC -> BF or BF -> AC)
최대 1개만 사용 가능
AC 채널 추가
BK 봇 키워드
MD 메시지 전달
BC 상담톡 전환 상담톡을 이용하는 채널만 사용 가능
BT 챗봇 전환 카카오 오픈 빌더의 챗봇을 사용하는 채널만 사용 가능

메시지 발송 (기본형)

  • 템플릿을 사용한 발송입니다.
  • 타겟팅 코드를 지정해 메시지 대상의 타입을 지정할 수 있습니다.
    • M: 고객사의 광고성 정보 수신동의 유저(카카오톡 수신 동의)
    • N: 고객사의 광고성 정보 수신동의 유저(카카오톡 수신 동의) - 채널 친구
    • I: 고객사의 발송 요청 대상 ∩ 채널 친구
  • 브랜드메시지 사용 신청이 완료된 채널에 한해 타겟팅 코드 M, N 발송을 사용할 수 있습니다.
  • 타겟팅 코드 M, N 발송 시, 채널에 지정된 080 무료수신거부번호를 사용합니다.
  • BC, BT 버튼을 사용할 수 없습니다.
  • 야간 발송 제한이 적용됩니다. (20:50 ~ 익일 08:00)

기본형 발송

요청 Body

{
    "plusFriendId":"string",
    "messageType":"string",
    "templateCode":"string",
    "targeting":"string",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "templateParameters": "object"
        }
    ]
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 텍스트형(TEXT)
이미지형(IMAGE)
와이드 이미지형(WIDE_IMAGE)
와이드 아이템 리스트형(WIDE_ITEM_LIST)
캐러셀 피드형(CAROUSEL_FEED)
캐러셀 커머스형(CAROUSEL_COMMERCE)
커머스형(COMMERCE)
프리미엄 동영상형(PREMIUM_VIDEO)
templateCode Mandatory String 템플릿 코드
targeting Optional String 타겟팅 타입 M
N
I (defaut)
messages Mandatory List of Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].to Mandatory String 수신자번호
messages[].templateParameters Optional Object 템플릿 파라미터 템플릿에 치환 변수 포함시, Mandatory

메시지 조회

발송 요청 조회

메시지 발송 요청을 조회합니다.

요청 URL

GET https://sens.apigw.ntruss.com/brandmessage/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 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디

Parameters

항목 Mandatory Type 설명 비고
requestId Mandatory String 요청 아이디 발송 요청 아이디
plusFriendId Mandatory String 카카오 채널 등록된 채널 명
messageType Optional String 메시지 타입 텍스트형(TEXT)
이미지형(IMAGE)
와이드 이미지형(WIDE_IMAGE)
와이드 아이템 리스트형(WIDE_ITEM_LIST)
캐러셀 피드형(CAROUSEL_FEED)
캐러셀 커머스형(CAROUSEL_COMMERCE)
커머스형(COMMERCE)
프리미엄 동영상형(PREMIUM_VIDEO)
templateCode Optional String 템플릿 코드
requestStartTime Mandatory String 조회 시간 시작 시각 yyyy-MM-dd'T'HH:mm:ss
requestEndTime Mandatory String 조회 시간 종료 시각 yyyy-MM-dd'T'HH:mm:ss
completeStartTime Mandatory String 발송 완료 시작 시간 yyyy-MM-dd'T'HH:mm:ss
completeEndTime Mandatory String 발송 완료 종료 시간 yyyy-MM-dd'T'HH:mm:ss
messageId Optional String 메시지 아이디
requestStatusName Optional String 요청 상태 success, fail
messageStatusName Optional String 요청 상태 success, processing, fail
to Optional String 메세지 수신 번호 붙임표 (-)를 제외한 번호
nextToken Optional String 다음 페이지 토큰 아래 참고 내용 참조
pageSize Optional Integer 페이지 크기 default: 20, max: 100
requestId를 포함한 조회시, default: 100
참고
  • 메시지 발송 이력은 최근 30일 이내의 이력만 조회할 수 있습니다.
  • requestId 또는 requestStartTime + requestEndTime 또는 completeStartTime + completeEndTime 중에 하나는 필수입니다.
  • requestStartTime + requestEndTime과 completeStartTime + completeEndTime은 동시에 사용할 수 없습니다.
  • requestStartTime ~ requestEndTime의 조회 범위는 최대 31일로 제한됩니다.
  • completeStartTime ~ completeEndTime의 조회 범위는 최대 24시간으로 제한됩니다.
  • 조회 조건에 requestId가 포함되어있지않은 경우, plusFriendId는 필수입니다.
  • nextToken
    • 이전 요청에서 nextToken 응답을 받은 경우에만 유효하며, 다음 페이지의 결과를 요청할 수 있음을 나타냅니다. 추가 결과가 있는 경우, 이전 응답의 nextToken 값을 이 Parameter에 설정하면 다음 페이지의 결과를 조회할 수 있습니다.

Headers

API Header 바로가기

요청 Body

없음

응답 Body

{
    "requestId": "string", 
    "statusCode": "string",
    "statusName": "string",
    "messages": [
        {
            "requestTime": "string",
            "messageId": "string",
            "messageType": "string",
            "targeting": "string",
            "countryCode": "string",
            "to": "string",
            "content": "string",
            "plusFriendId": "string",
            "completeTime": "string",
            "requestStatusCode": "string",
            "requestStatusName": "string",
            "requestStatusDesc": "string",
            "messageStatusCode": "string",
            "messageStatusName": "string",
            "messageStatusDesc": "string",
            "isAdult": "boolean",
            "useSmsFailover": "boolean"
        }
    ],
    "pageSize": "integer",
    "pageIndex": "integer",
    "itemCount": "integer",
    "hasMore": "boolean"
}
항목 Mandatory Type 설명 비고
requestId Optional String 발송 요청 아이디 requestId로 조회하는 경우에만 노출됨
statusCode Mandatory String 요청 상태 코드 202 - 성공
그외 - 실패
* HTTP Status 규격을 따름
statusName Mandatory String 요청 상태명 success - 성공
processing - 발송중
reserved - 예약중
fail - 실패
messages[].requestTime Mandatory DateTime 발송 요청 시간 yyyy-MM-dd'T'HH:mm:ss.SSS
messages[].messageId Mandatory String 메시지 아이디
messages[].countryCode Optional String 수신자 국가번호 default: 82
messages[].messageType Mandatory String 메시지 타입 텍스트형(TEXT)
이미지형(IMAGE)
와이드 이미지형(WIDE_IMAGE)
와이드 아이템 리스트형(WIDE_ITEM_LIST)
캐러셀 피드형(CAROUSEL_FEED)
캐러셀 커머스형(CAROUSEL_COMMERCE)
커머스형(COMMERCE)
프리미엄 동영상형(PREMIUM_VIDEO)
messages[].targeting Mandatory String 타겟팅 타입
messages[].to Mandatory String 수신자번호
messages[].content Mandatory String 메시지 내용
messages[].plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messages[].completeTime Optional DateTime 발송 리포트(처리 완료) 시간 yyyy-MM-dd'T'HH:mm:ss
messages[].requestStatusCode Mandatory String 발송요청 상태 코드 A000 - 성공
그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
messages[].requestStatusName Mandatory String 발송요청 상태명 success - 성공
fail - 실패
messages[].requestStatusDesc Mandatory String 발송요청 상태 내용
messages[].messageStatusCode Mandatory String 발송결과 상태 코드 0000 - 성공
그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
messages[].messageStatusName Mandatory String 발송결과 상태명 success - 성공
processing - 처리중
    * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태
    * messageCode, messageDesc가 조회되지 않음
fail - 실패
messages[].messageStatusDesc Mandatory String 발송결과 상태 내용
messages[].isAdult Mandatory Boolean 전체 연령 여부 성인: true
전체: false
messages[].useSmsFailover Mandatory Boolean SMS Failover 사용 여부
pageSize Mandatory Integer 페이지 사이즈
nextToken Optional String 다음 페이지 토큰
itemCount Mandatory Integer 조회한 페이지 내의 메시지 수
hasMore Mandatory Boolean 다음 페이지 존재 여부

응답 Status

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

발송 결과 조회

메시지 발송 결과를 조회합니다.

요청 URL

GET https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/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 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
messageId Mandatory String 메시지 아이디 메시지 발송시 반환되는 메시지 식별자

Headers

API Header 바로가기

요청 Body

없음

응답 Body

{
    "messageId":"string",
    "requestId":"string",
    "requestTime":"string",
    "completeTime":"string",
    "plusFriendId":"string",
    "messageType": "string",
    "targeting": "string",
    "countryCode":"string",
    "to":"string",
    "requestStatusCode":"string",
    "requestStatusName":"string",
    "requestStatusDesc":"string",
    "messageStatusCode":"string",
    "messageStatusName":"string",
    "messageStatusDesc":"string",
    "isAdult":"boolean",
    "useSmsFailover":"boolean",
    "content":"string",
	"headerContent":"string",
	"additionalContent":"string",
	"buttons":[
		{
			"type":"string",
			"name":"string",
			"linkMobile":"string",
			"linkPc":"string",
			"schemeIos":"string",
			"schemeAndroid":"string",
			"bizFormId":"string"
		}
	],
	"image":{
		"imageId":"string",
		"imageLink":"string"
	},
	"item":[
		{
			"title":"string",
			"imageId":"string",
			"linkMobile":"string",
			"linkPc":"string",
			"schemeAndroid":"string",
			"schemeIos":"string"
		}
	],
	"carousel": {
		"head": {
			"headerContent":"string",
			"content":"string",
			"imageId":"string",
			"linkMobile":"string",
			"linkPc":"string",
			"schemeAndroid":"string",
			"schemeIos":"string"
		},
		"list": [
			{
				"headerContent":"string",
				"message":"string",
				"additionalContent":"string",
				"image":{
					"imageId":"string",
					"imageLink":"string"
				},
				"buttons":[
					{
						"type":"string",
						"name":"string",
						"linkMobile":"string",
						"linkPc":"string",
						"schemeAndroid":"string",
						"schemeIos":"string",
						"bizFormId":"string"
					}
				],
				"coupon": {
					"title":"string",
					"description":"string",
					"linkMobile":"string",
					"linkPc":"string",
					"schemeAndroid":"string",
					"schemeIos":"string"
				},
				"commerce": {
					"title":"string",
					"regularPrice":"integer",
					"discountPrice":"integer",
					"discountRate":"integer",
					"discountFixed":"integer"
				}
			}
		],
		"tail": {
			"linkMobile":"string",
			"linkPc":"string",
			"schemeAndroid":"string",
			"schemeIos":"string"
		}
	},
	"commerce": {
		"title":"string",
		"regularPrice":"integer",
		"discountPrice":"integer",
		"discountRate":"integer",
		"discountFixed":"integer"
	},
	"coupon": {
		"title":"string",
		"description":"string",
		"linkMobile":"string",
		"linkPc":"string",
		"schemeAndroid":"string",
		"schemeIos":"string"
	},
	"video": {
		"thumbnailId":"string",
		"videoUrl":"string"
	},
	"useSmsFailover": "boolean"
}
항목 Mandatory Type 설명 비고
messageId Mandatory String 메시지 아이디
requestId Mandatory String 발송 요청 아이디
requestTime Mandatory DateTime 발송 요청 시간 yyyy-MM-dd'T'HH:mm:ss.SSS
completeTime Optional DateTime 발송 리포트(처리 완료) 시간 yyyy-MM-dd'T'HH:mm:ss
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messageType Mandatory String 메시지 타입 텍스트형(TEXT)
이미지형(IMAGE)
와이드 이미지형(WIDE_IMAGE)
와이드 아이템 리스트형(WIDE_ITEM_LIST)
캐러셀 피드형(CAROUSEL_FEED)
캐러셀 커머스형(CAROUSEL_COMMERCE)
커머스형(COMMERCE)
프리미엄 동영상형(PREMIUM_VIDEO)
targeting Mandatory String 타겟팅 코드 M, N, I
templateCode Mandatory String 템플릿 코드
countryCode Optional String 수신자 국가번호 default: 82
to Mandatory String 수신자번호
requestStatusCode Mandatory String 발송요청 상태 코드 A000 - 성공
그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
requestStatusName Mandatory String 발송요청 상태명 success - 성공
fail - 실패
requestStatusDesc Mandatory String 발송요청 상태 내용
messageStatusCode Mandatory String 발송결과 상태 코드 0000 - 성공
그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
messageStatusName Mandatory String 발송결과 상태명 success - 성공
processing - 처리중
    * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태
    * messageCode, messageDesc가 조회되지 않음
fail - 실패
messageStatusDesc Mandatory String 발송결과 상태 내용
isAdult Mandatory Boolean 전체 연령 여부
content Optional String
headerContent Optional String 헤더
additionalContent Optional String 부가 내용
buttons Optional List of Object 버튼 버튼 정보 참조
buttons[].type Mandatory String 버튼 Type
buttons[].name Mandatory String 버튼명
buttons[].linkMobile Optional String 모바일 웹 링크
buttons[].linkPc Optional String PC 웹 링크
buttons[].schemeAndroid Optional String Android 앱 링크
buttons[].schemeIos Optional String iOS 앱 링크
image Optional Object 이미지
image.imageId Mandatory String 이미지 아이디
image.imageLink Optional String 이미지 링크
coupon Optional Object 쿠폰 정보
coupon.title Mandatory String 쿠폰 제목
coupon.description Mandatory String 쿠폰 상세 설명 최대 18자
coupon.linkMobile Optional String 모바일 웹 링크
coupon.linkPc Optional String PC 웹 링크
coupon.schemeAndroid Optional String Android 앱 링크
coupon.schemeIos Optional String iOS 앱 링크
video Optional Object 동영상 정보
video.thumbnailId Mandatory String 동영상 썸네일용 이미지 아이디
video.videoUrl Mandatory String 카카오TV 동영상 URL
item Optional Object
item.list Mandatory List of Object 와이드 리스트
item.list[].title Optional String 아이템 제목
item.list[].imageId Mandatory String 이미지 아이디
item.list[].linkMobile Mandatory String 모바일 웹 링크
item.list[].linPc Optional String PC 웹 링크
item.list[].schemeAndroid Optional String Android 앱 링크
item.list[].schemeIos Optional String iOS 앱 링크
carousel Optional Object 캐러셀 정보
carousel.head Optional Object 캐러셀 인트로 정보
carousel.head.headerContent Mandatory String 헤더
carousel.head.content Mandatory String 내용
carousel.head.imageId Mandatory String 이미지 아이디
carousel.head.linkMobile Optional String 모바일 웹 링크
carousel.head.linkPc Optional String PC 웹 링크
carousel.head.schemeAndroid Optional String Android 앱 링크
carousel.head.schemeIos Optional String iOS 앱 링크
carousel.list Mandatory List of Object 캐러셀 리스트
carousel.list[].headerContent Optional String 캐러셀 리스트 아이템 제목
carousel.list[].message Mandatory String 캐러셀 리스트 아이템 메시지
carousel.list[].additionalContent Optional String 캐러셀 리스트 아이템 부가 내용
carousel.list[].image Mandatory Object 캐러셀 리스트 아이템 이미지 정보
carousel.list[].image.imageId Mandatory String 이미지 아이디
carousel.list[].image.imageLink Optional String 이미지 링크
carousel.list[].buttons Mandatory List of Object 버튼 정보
carousel.list[].buttons[].type Mandatory String 버튼 Type
carousel.list[].buttons[].name Mandatory String 버튼명
carousel.list[].buttons[].linkMobile Optional String 모바일 웹 링크
carousel.list[].buttons[].linkPc Optional String PC 웹 링크
carousel.list[].buttons[].schemeAndroid Optional String Android 앱 링크
carousel.list[].buttons[].schemeIos Optional String iOS 앱 링크
carousel.list[].buttons[].bizFormId Optional String
carousel.list[].coupon Optional Object 쿠폰 정보
carousel.list[].coupon.title Mandatory String 쿠폰 제목
carousel.list[].coupon.description Mandatory String 쿠폰 상세 설명
carousel.list[].coupon.linkMobile Optional String 모바일 웹 링크
carousel.list[].coupon.linkPc Optional String PC 웹 링크
carousel.list[].coupon.schemeAndroid Optional String Android 앱 링크
carousel.list[].coupon.schemeIos Optional String iOS 앱 링크
carousel.list[].commerce Optional Object 커머스 정보
carousel.list[].commerce.title Mandatory String 상품 제목
carousel.list[].commerce.regularPrice Mandatory Integer 상품 정상 가격
carousel.list[].commerce.discountPrice Optional Integer 상품 할인 가격
carousel.list[].commerce.discountRate Optional Integer 상품 할인율
carousel.list[].commerce.discountFixed Optional Integer 상품 정액 할인 가격
carousel.tail Optional Object 캐러셀 더보기 정보
carousel.tail.linkMobile Mandatory String 모바일 웹 링크
carousel.tail.linkPc Optional String PC 웹 링크
carousel.tail.schemeAndroid Optional String Android 앱 링크
carousel.tail.schemeIos Optional String iOS 앱 링크
commerce Optional Object 커머스 정보
commerce.title Mandatory String 상품 제목
commerce.regularPrice Mandatory Integer 상품 정상 가격
commerce.discountPrice Optional Integer 상품 할인 가격
commerce.discountRate Optional Integer 상품 할인율
commerce.discountFixed Optional Integer 상품 정액 할인 가격
useSmsFailover Mandatory Boolean SMS Failover 사용 여부

응답 Status

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

이미지

이미지 업로드

브랜드메시지 발송에 사용할 이미지를 업로드합니다.

요청 URL

POST https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images

Content-Type: multipart/form-data; boundary=a29b1180-70f5-42f7-afbe-0d68a15f2370
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 바로가기

요청 Parameter

항목 Mandatory Type 설명 비고
imageType Mandatory String 이미지 타입 정보 참조
imageFile Mandatory File 이미지 파일

응답 Body

{
    "imageId":"string",
    "imageType":"string",
    "imageName":"string",
    "imageUrl":"string",
    "createTime":"string"
}
항목 Mandatory Type 설명 비고
imageId Mandatory Strng 이미지 아이디
imageType Mandatory String 이미지 타입 정보 참조
imageName Mandatory String 이미지 파일 이름
imageUrl Mandatory String 이미지 URL
createTime Mandatory DateTime 이미지 업로드 시간

응답 Status

HTTP Status Desc
200 Ok (업로드 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

이미지 목록 조회

업로드된 이미지 목록을 조회합니다.

요청 URL

GET https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images

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 바로가기

Parameters

항목 Mandatory Type 설명 비고
pageIndex Optional Integer 페이지 인덱스 default: 0
pageSize Optional Integer 페이지 사이즈 default: 20 (1 ~ 100 사이의 숫자만 입력 가능)

요청 Body

없음

응답 Body

{
  "items": [
    {
      "imageId":"string",
      "imageType":"string",
      "imageName":"string",
      "imageUrl":"string",
      "createTime":"string"
    }
  ],
  "pageIndex": "integer",
  "pageSize": "integer",
  "itemCount": "integer",
  "hasPrevious": "boolean",
  "hasNext": "boolean",
  "totalCount": "integer"
}
항목 Mandatory Type 설명 비고
items Mandatory List of Object
items[].imageId Mandatory Strng 이미지 아이디
items[].imageType Mandatory String 이미지 타입 정보 참조
items[].imageName Mandatory String 이미지 파일 이름
items[].imageUrl Mandatory String 이미지 URL
items[].createTime Mandatory DateTime 이미지 업로드 시간
pageIndex Mandatory Integer 페이지 인덱스
pageSize Mandatory Integer 페이지 사이즈
itemCount Mandatory Integer 조회된 아이템 개수
hasPrevious Mandatory Boolean 이전 페이지 존재 여부
hasNext Mandatory Boolean 다음 페이지 존재 여부
totalCount Mandatory Integer 전체 개수

응답 Status

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

이미지 단건 조회

업로드된 이미지를 단건 조회합니다.

요청 URL

GET https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images/{imageId}

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 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
imageId Mandatory String 이미지 아이디 업로드된 이미지 아이디

Headers

API Header 바로가기

요청 Body

없음

응답 Body

{
    "imageId":"string",
    "imageType":"string",
    "imageName":"string",
    "imageUrl":"string",
    "createTime":"string"
}

응답 Status

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

이미지 삭제

업로드된 이미지를 삭제합니다.

요청 URL

DELETE https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images/{imageId}

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 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
imageId 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

이미지 타입 정보

항목 설명 비고
BASIC TEXT, COMMERCE, PREMIUM_VIDEO 이미지 권장 사이즈: 800 x 400px(가로 500px 이상)
이미지 비율(width / height): 0.5 ~ 1.333
jpg, png
최대 5MB
WIDE WIDE_IMAGE 이미지 권장 사이즈: 800 x 600px(가로 500px 이상)
이미지 비율(width / height): 0.5 ~ 1.0
jpg, png
최대 5MB
WIDE_ITEM_LIST_MAIN WIDE_ITEM_LIST 첫 번째 아이템 이미지 가로 500px 이상
이미지 비율(width / height): 0.5
jpg, png
최대 5MB
WIDE_ITEM_LIST_SUB WIDE_ITEM_LIST 두 번째 이후 아이템 이미지 가로 500px 이상
이미지 비율(width / height): 1.0
jpg, png
최대 5MB
CAROUSEL_FEED CAROUSEL_FEED 이미지 권장 사이즈: 800 x 600px 또는 800 x 400px(가로 500px 이상)
이미지 비율(width / height) 0.5 ~ 1.333
jpg, png
최대 5MB
CAROUSEL_COMMERCE CAROUSEL_COMMERCE 이미지 권장 사이즈: 800 x 600px 또는 800 x 400px(가로 500px 이상)
이미지 비율(width / height) 0.5 ~ 1.333 (전체 이미지 비율 동일)
jpg, png
최대 5MB

오류 코드

비즈메시지 수신 결과 코드

Status Error text Desc
0000 - 정상 발송
1001 NoJsonBody Request Body가 Json형식이 아님
1002 InvalidHubPartnerKey 파트너 키가 유효하지 않음
1003 InvalidSenderKey 발신 프로필 키가 유효하지 않음
1004 NoValueJsonElement Request BODY(Json)에서 name을 찾을 수 없음
1005 SenderNotFound 발신 프로필을 찾을 수 없음
1006 DeletedSender 삭제된 발신 프로필
1007 StoppedSender 차단 상태의 발신 프로필
1011 ContractNotFound 계약 정보를 찾을 수 없음
1012 InvalidUserKeyException 잘못된 형식의 유저 키 요청
1013 InvalidAppLink 유효하지 않은 app연결
1014 InvalidBizNum 유효하지 않은 사업자번호
1015 TalkUserIdNotFonud 유효하지 않은 app user id 요청
1016 BizNumNotEqual 사업자등록번호 불일치
1020 InvalidReceiveUserException 올바른 유저 식별자 값이 하나도 없는 경우
1021 BlockedProfile 차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
1022 DeactivatedProfile 닫힘 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
1023 DeletedProfile 삭제된 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
1024 DeletingProfile 삭제 대기 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
1025 SpammedProfile 메시지 차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
1026 UnableUseMessageType 해당 msg_type에서 사용할 수 없는 response_method 로 요청 (이미지 알림톡(AI)은 실시간으로 발송 불가)
1027 - 채널 메시지 제재 상태로 인한 메시지 전송 실패
1030 InvalidParameterException 잘못된 파라메터 요청
1033 - 템플릿 타입과 메시지 타입 불일치
2000 FailedToCheckFriendshipException 톡채널과 친구 관계 확인 시 에러 (시스템 에러)
2003 FailedToSendMessageByNoFriendshipException 메시지 전송 실패 (테스트 서버에서 카카오톡 채널을 추가하지 않은 경우)
2004 FailedToMatchTemplateException 템플릿 일치 확인 시 오류 발생 (카카오 내부 오류)
2005 FailedToReadImageException 카카오에서 이미지 메타 정보 읽어오는 중 에러
2006 FailedToMatchSerialNumberPrefixPattern 시리얼넘버 형식 불일치
3000 UnexceptedExcetpion 예기치 않은 오류 발생
3005 AckTimeoutException 메시지를 발송 했으나 수신확인 안 됨 (성공 불확실)
3006 FailedToSendMessageException 카카오 내부 시스템 오류로 메시지 전송 실패
3008 InvalidPhoneNumberException 전화번호 오류
3010 JsonParsseExcetpion Json 파싱 오류
3011 MessageNotFoundException 메시지가 존재하지 않음
3012 SerialNumberDuplicatedException 메시지 일련번호가 중복됨 (메시지 일련 번호는 고유의 값이 부여되어야 함)
3013 MessageEmptyException 빈 메시지
3014 MessageLengthOverLimitException 메시지 길이 제한 오류 (텍스트 타입 1000자 초과, 이미지 타입 400자 초과)
3015 TemplateNotFoundException 템플릿을 찾을 수 없음
3016 NoMatchedTemplateException 메시지 내용이 템플릿과 일치하지 않음
3018 NoSendAvailableException 메시지를 전송할 수 없음
3019 MessageNoUserException 톡유저가 아님
3020 MessageUserBlockedAlimTalkException 알림톡 차단
3021 MessageNotSupportedKakaotalkException 톡 최소 버전 미지원
3022 NoSendAvailableTimeException 메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시까지 발송 가능)
3023 MessageInvalidVideoException 메시지에 포함된 비디오를 전송할 수 없음 (비디오 주소 또는 썸네일 이미지 주소가 올바르지 않거나 썸네일 이미지가 규격에 맞지 않음)
3024 MessageInvaildImageException 메시지에 포함된 이미지를 전송할 수 없음
3025 ExceedMaxVariableLengthException 변수 글자 수 제한 초과
3026 Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})' 상담/봇 전환 버튼 extra, event 글자수 제한 초과
3027 NoMatchedTemplateButtonException 버튼 내용이 템플릿과 일치 하지 않음
3028 NoMatchedTemplateTitleException 메시지 강조 표기 타이틀이 템플릿과 일치하지 않음
3029 ExceedMaxTitleLengthException 메시지 강조 표기 타이틀 길이 제한 초과 (50자)
3031 - 텍스트 유형 불일치
3030 NoMatchedTemplateWithMessageTypeException 메시지 타입과 템플릿 강조유형이 일치하지 않음
3031 NoMatchedTemplateHeaderException 헤더가 템플릿과 일치하지 않음
3032 ExceedMaxHeaderLengthException 헤더 길이 제한 초과(16 자)
3033 NoMatchedTemplateItemHighlightException 아이템 하이라이트가 템플릿과 일치하지 않음
3034 ExceedMaxItemHighlightTitleLengthException 아이템 하이라이트 타이틀 길이 제한 초과 (이미지 없는 경우 30 자, 이미지 있는 경우 21 자)
3035 ExceedMaxItemHighlightDescriptionLengthException 아이템 하이라이트 디스크립션 길이 제한 초과 (이미지 없는 경우 19 자, 이미지 있는 경우 14 자)
3036 NoMatchedTemplateItemListException 아이템 리스트가 템플릿과 일치하지 않음
3037 ExceedMaxItemDescriptionLengthException 아이템 리스트의 아이템의 디스크립션 길이 제한 초과(23 자)
3038 NoMatchedTemplateItemSummaryException 아이템 요약 정보가 템플릿과 일치하지 않음
3039 ExceedMaxItemSummaryDescriptionLengthException 아이템 요약정보의 디스크립션 길이 제한 초과(14 자)
3040 InvalidItemSummaryDescriptionException 아이템 요약 정보의 디스크립션에 허용되지 않은 문자 포함(통화기호/코드, 숫자, 콤마, 소수점, 공백을 제외한 문자 포함)
3041 MessageInvalidWideItemListLengthException 와이드 아이템 리스트 개수 최소, 최대 개수 불일치
3042 NoMatchedTemplateRepresentLinkException 대표 링크가 템플릿과 일치하지 않음
3046 ExceedMaxAdditionalContentLengthException 부가 정보 최대 길이 제한 오류
3047 ExceedMaxCommerceTitleLengthException 커머스 정보 상품명 최대 길이 제한 오류
3050 MessageNotSupportedUnsubscribeException 수신 동의 거부 스펙 (N 타입) 미지원
3051 InvalidateCarouselItemMinException or InvalidateCarouselItemMaxException 캐러셀 아이템 리스트 개수 최소, 최대 개수 불일치
3052 CarouselMessageLengthOverLimitException 캐러셀 아이템 메시지 길이 초과
3056 WideItemListTitleLengthOverLimitException 와이드 아이템 리스트 타이틀 길이 제한 오류
3058 CarouselHeaderLengthOverLimitException 캐러셀 헤더 길이 제한 오류
3059 MessageNotSupportedCouponException 쿠폰 스펙 미지원
4000 ResponseHistoryNotFoundException 메시지 전송 결과를 찾을 수 없음
4001 UnKnownMessageStatusError 알수 없는 메시지 상태
7011 - 시리얼 넘버 패턴 에러
7014 - 메시지 유효 시간 초과 에러
8512 - 수신자 타입 찾을 수 없음
8514 - request_id 찾을 수 없음
8520 - 지원하지 않는 상품 타입 오류
8521 - 지원하지 않는 메시지 타입 오류
8522 - 지원하지 않는 텍스트 유형 오류
8523 - 지원하지 않는 response method 오류
8530 - 수신자 목록 사이즈 오류
8999 - 내부 서버 오류
9998 현재 서비스를 제공하고 있지 않습니다. 시스템에 문제가 발생하여 담당자 확인 중
9999 시스템에 알 수 없는 문제 발생, 담당자 확인 중 시스템에 문제가 발생하여 담당자 확인 중
B000 Prepare to relay failed 중계사 발송을 위한 사전 작업 실패
B001 Request to relay failed 중계사 발송 실패
B002 Filtering for request to relay failed 잘못된 요청으로 인해 필터링됨
B003 Invalid phone number format 올바르지 않은 발신번호 포멧
B004 Quota Exceed 쿼터 초과
B005 Message processing timeout exceed 메시지 요청 시간과 처리 시간의 차이가 허용 범위를 벗어남
B400 Invalid Request 메시지 형식 오류
B999 Unexpected server error 예기치 못한 에러