브랜드메시지

브랜드메시지는 카카오톡 채널 친구에게 브랜드형 메시지를 발송하는 카카오 비즈메시지 채널입니다. 템플릿 기반의 기본형 발송과 메시지 내용을 직접 구성하는 자유형 발송을 모두 지원합니다.

브랜드메시지 기본형 발송

기본형 브랜드메시지는 사전에 등록된 템플릿을 기준으로 발송합니다. 템플릿 코드 기반 치환 발송에 사용할 수 있습니다.

기본형 메시지 발송

POST/api/comm/v1/send/omni

브랜드메시지 기본형 발송 규격입니다. 사전 승인된 템플릿 코드를 사용하며 sendType은 basic입니다.

기본형 발송 방식은 2가지입니다.
1. 변수 분리 방식: messageVariable, buttonVariable, couponVariable 같은 Variable 필드에 치환값을 넣는 방식입니다.
2. 전문 방식: 기존 알림톡과 비슷하게 text, attachment, carousel 구조에 직접 값을 넣는 방식입니다.

두 방식은 같은 기본형 발송 안에서 선택적으로 사용하는 개념이며, 템플릿 구조와 msgType에 맞는 필드를 사용해야 합니다. Variable 필드는 변수 치환이 필요한 경우에만 사용합니다.

Body Parameters

{}JSON

destinations

필수Object Array

수신 정보 배열입니다. 동보발송 최대 200건입니다.

필수String

수신번호입니다.

ref

String

개별 참조 필드입니다.

messageFlow

필수Object Array

메시지를 추가하면 순서대로 자동 Fallback 메시지 처리됩니다.

brandmessage

필수Object

브랜드메시지 기본형 객체입니다.

sendType

필수String

브랜드메시지 발송 타입입니다.

msgType

필수String

카카오 비즈메시지 타입입니다.

targeting

필수String

고객사의 광고성 정보 수신동의 회원 대상 타겟팅입니다.

text

String

브랜드메시지 본문입니다.

header

String

헤더 정보입니다.

additionalContent

String

부가 정보입니다.

pushAlarm

String

푸시 알림 발송 여부입니다.

messageVariable

Object

메시지 영역 변수 정의입니다.

buttonVariable

Object

버튼 영역 변수 정의입니다.

couponVariable

Object

쿠폰 영역 변수 정의입니다.

imageVariable

Object

이미지 영역 변수 정의입니다.

videoVariable

Object

비디오 영역 변수 정의입니다.

commerceVariable

Object

커머스 영역 변수 정의입니다.

carouselVariable

Object Array

캐러셀 영역 변수 목록입니다.

messageVariable

Object

캐러셀 메시지 영역 변수입니다.

buttonVariable

Object

캐러셀 버튼 영역 변수입니다.

couponVariable

Object

캐러셀 쿠폰 영역 변수입니다.

imageVariable

Object

캐러셀 이미지 영역 변수입니다.

commerceVariable

Object

캐러셀 커머스 영역 변수입니다.

originCID

String

최초 발신사업자 식별코드입니다.

unsubscribePhoneNumber

String

무료 수신거부 전화번호입니다.

unsubscribeAuthNumber

String

무료 수신거부 인증번호입니다.

attachment

Object

첨부 정보 객체입니다.

button

Object Array

버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

item

Object

와이드 아이템 요소입니다.

list

Object Array

아이템 목록입니다.

title

String

아이템 제목입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

video

Object

동영상 요소입니다.

videoUrl

필수String

카카오TV 동영상 URL입니다.

thumbnailUrl

String

동영상 썸네일 URL입니다.

carousel

Object

캐러셀 객체입니다.

head

Object

캐러셀 인트로 정보입니다.

header

String

캐러셀 인트로 헤더입니다.

content

String

캐러셀 인트로 내용입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

list

Object Array

캐러셀 아이템 목록입니다.

header

String

캐러셀 아이템 제목입니다.

message

String

캐러셀 아이템 본문입니다.

additionalContent

String

부가 정보입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

tail

Object

더보기 버튼 정보입니다.

urlMobile

필수String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

paymentCode

String

정산용 부서 코드입니다.

groupKey

String

메시지 인사이트 에서 그룹으로 묶어서 통계를 확인하기 위해 설정하는 키입니다.

idempotencyKey

String

요청에 대한 멱등함을 구분하는 멱등성 키 필드입니다.

idempotencyTtl

Integer

멱등 처리키 유효시간 입니다.

ref

String

요청 참조 필드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 메시지 응답 데이터입니다.

destinations

Object Array

수신자별 처리 결과 배열입니다.

요청 예시

curl -X POST "/api/comm/v1/send/omni" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [{ "to": "01012345678", "messageVariable": { "name": "홍길동" } }],
    "messageFlow": [{
      "brandmessage": {
        "sendType": "basic",
        "msgType": "TEXT",
        "senderKey": "{senderKey}",
        "templateCode": "BM_TEMPLATE_001"
      }
    }],
    "ref": "brand-basic-20260331-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "data": {
      "destinations": [{
        "to": "01012345678",
        "msgKey": "20260424104234546POM101182450000",
        "code": "A000",
        "result": "Success"
      }]
    },
    "ref": "brand-basic-20260331-001"
  }
}

기본형 예약 발송

POST/api/comm/v1/reservation

브랜드메시지 기본형을 지정한 시각에 발송하도록 예약 등록합니다. 발송 가능한 상세 필드는 기본형 메시지 발송 규격과 동일합니다. 예약 등록 후 조회, 수정, 취소, 중지, 재개, 수신자 관리는 예약 관리 페이지에서 확인할 수 있습니다.

Body Parameters

{}JSON

destinations

필수Object Array

수신 정보 배열입니다. 동보발송 최대 200건입니다.

필수String

수신번호입니다.

ref

String

개별 참조 필드입니다.

messageFlow

필수Object Array

메시지를 추가하면 순서대로 자동 Fallback 메시지 처리됩니다.

brandmessage

필수Object

브랜드메시지 기본형 객체입니다.

sendType

필수String

브랜드메시지 발송 타입입니다.

msgType

필수String

카카오 비즈메시지 타입입니다.

targeting

필수String

고객사의 광고성 정보 수신동의 회원 대상 타겟팅입니다.

text

String

브랜드메시지 본문입니다.

header

String

헤더 정보입니다.

additionalContent

String

부가 정보입니다.

pushAlarm

String

푸시 알림 발송 여부입니다.

messageVariable

Object

메시지 영역 변수 정의입니다.

buttonVariable

Object

버튼 영역 변수 정의입니다.

couponVariable

Object

쿠폰 영역 변수 정의입니다.

imageVariable

Object

이미지 영역 변수 정의입니다.

videoVariable

Object

비디오 영역 변수 정의입니다.

commerceVariable

Object

커머스 영역 변수 정의입니다.

carouselVariable

Object Array

캐러셀 영역 변수 목록입니다.

messageVariable

Object

캐러셀 메시지 영역 변수입니다.

buttonVariable

Object

캐러셀 버튼 영역 변수입니다.

couponVariable

Object

캐러셀 쿠폰 영역 변수입니다.

imageVariable

Object

캐러셀 이미지 영역 변수입니다.

commerceVariable

Object

캐러셀 커머스 영역 변수입니다.

originCID

String

최초 발신사업자 식별코드입니다.

unsubscribePhoneNumber

String

무료 수신거부 전화번호입니다.

unsubscribeAuthNumber

String

무료 수신거부 인증번호입니다.

attachment

Object

첨부 정보 객체입니다.

button

Object Array

버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

item

Object

와이드 아이템 요소입니다.

list

Object Array

아이템 목록입니다.

title

String

아이템 제목입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

video

Object

동영상 요소입니다.

videoUrl

필수String

카카오TV 동영상 URL입니다.

thumbnailUrl

String

동영상 썸네일 URL입니다.

carousel

Object

캐러셀 객체입니다.

head

Object

캐러셀 인트로 정보입니다.

header

String

캐러셀 인트로 헤더입니다.

content

String

캐러셀 인트로 내용입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

list

Object Array

캐러셀 아이템 목록입니다.

header

String

캐러셀 아이템 제목입니다.

message

String

캐러셀 아이템 본문입니다.

additionalContent

String

부가 정보입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

tail

Object

더보기 버튼 정보입니다.

urlMobile

필수String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

resvSendTime

필수String

예약 발송 시각입니다.

resvName

String

예약 건을 식별하기 위한 이름입니다.

ref

String

요청 참조 필드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

예약 등록 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/reservation" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [{
      "to": "01012345678"
    }],
    "messageFlow": [{
      "brandmessage": {
        "sendType": "basic",
        "msgType": "FT",
        "senderKey": "{senderKey}",
        "templateCode": "BM_TEMPLATE_001",
        "targeting": "M"
      }
    }],
    "resvSendTime": "2026-05-01 10:00:00",
    "resvName": "브랜드메시지 기본형 예약 발송",
    "ref": "brand-basic-resv-20260501-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "Success",
    "resvKey": "20260501100000RESV0000000001"
  }
}

기본형 템플릿 자동 치환 발송

POST/api/comm/v1/send/omni

메시지 발송 체험하기 샌드박스로 테스트하기

기본형 브랜드메시지를 템플릿 전문 없이 템플릿 코드와 치환 변수만으로 발송합니다. Bizgo API가 템플릿 코드에 맞는 전문을 생성한 뒤 destinations[].replaceWords 값을 치환해 발송합니다.

Body Parameters

{} JSON

destinations

필수Object Array

수신 정보 배열입니다.

필수String

수신번호입니다.

messageFlow

필수Object Array

메시지 규격 배열입니다.

brandmessage

필수Object

브랜드메시지 정보입니다.

sendType

필수String

템플릿 변수 자동 치환 발송 타입입니다.

targeting

필수String

고객사의 광고성 정보 수신동의 회원 대상 타겟팅입니다.

pushAlarm

String

메시지 도착 시 푸시 알림 발송 여부입니다.

originCID

String

최초 발신사업자 식별코드입니다.

unsubscribePhoneNumber

String

무료수신거부 전화번호입니다.

unsubscribeAuthNumber

String

무료수신거부 인증번호입니다.

paymentCode

String

정산용 부서 코드입니다.

groupKey

String

그룹 키입니다.

idempotencyKey

String

멱등성 키입니다.

idempotencyTtl

Integer

멱등성 키 만료 시간(초)입니다.

ref

String

요청 참조 필드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

메시지 접수 결과 데이터입니다.

destinations

Object Array

수신자별 접수 결과 배열입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/send/omni" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [{
      "to": "01000000000",
      "replaceWords": {
        "customerName": "홍길동",
        "point": "500"
      }
    }],
    "messageFlow": [{
      "brandmessage": {
        "senderKey": "{senderKey}",
        "templateCode": "{templateCode}",
        "sendType": "template",
        "targeting": "I",
        "pushAlarm": "Y",
        "originCID": "123456789",
        "unsubscribePhoneNumber": "0801234567",
        "unsubscribeAuthNumber": "12345"
      }
    }],
    "paymentCode": "brand-team-01",
    "groupKey": "brand-template-group-01",
    "idempotencyKey": "brand-template-idempotency-001",
    "idempotencyTtl": 300,
    "ref": "brand-template-001"
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "destinations": [{
        "to":"01000000000",
        "msgKey":"20260424104234546POM101182450000",
        "code":"A000",
        "result":"Success"
      }]
    },
    "ref":"brand-template-001"
  }
}

브랜드메시지 자유형 발송

자유형 브랜드메시지는 템플릿 등록 없이 메시지 내용을 직접 구성해 발송합니다. 메시지 타입에 맞는 이미지, 버튼, 캐러셀 요소를 함께 정의할 수 있습니다.

커머스·캐러셀 커머스 discountRate(할인율) 안내
허용 범위: 1~100
2026년 8월 4일부터 discountRate 값이 0이면 템플릿 등록·발송 요청이 실패 처리됩니다.
자유형 발송은 discount_rate, 변수 분리 방식은 고정변수 할인율에 동일하게 적용됩니다.
할인율을 사용하지 않을 때는 0 대신 null로 전송하세요.

자유형 메시지 발송

POST/api/comm/v1/send/omni

메시지 발송 체험하기 샌드박스로 테스트하기

브랜드메시지 자유형 발송 규격입니다. 템플릿 코드 없이 본문/버튼 값을 직접 구성하며 sendType은 free입니다.

Body Parameters

{}JSON

destinations

필수Object Array

수신 정보 배열입니다. 동보발송 최대 200건입니다.

필수String

수신번호입니다.

ref

String

개별 참조 필드입니다.

messageFlow

필수Object Array

메시지를 추가하면 순서대로 자동 Fallback 메시지 처리됩니다.

brandmessage

필수Object

브랜드메시지 자유형 객체입니다.

sendType

필수String

브랜드메시지 발송 타입입니다.

msgType

필수String

카카오 비즈메시지 타입입니다.

text

String

메시지 본문입니다.

targeting

String

고객사의 광고성 정보 수신동의 회원 대상 타겟팅입니다.

header

String

헤더 정보입니다.

additionalContent

String

부가 정보입니다.

groupTagKey

String

그룹태그 등록으로 발급받은 키입니다.

adult

String

성인 대상 메시지 여부입니다.

pushAlarm

String

푸시 알림 발송 여부입니다.

adFlag

String

광고성메시지 필수 표기 사항 노출 여부입니다.

originCID

String

최초 발신사업자 식별코드입니다.

unsubscribePhoneNumber

String

무료 수신거부 전화번호입니다.

unsubscribeAuthNumber

String

무료 수신거부 인증번호입니다.

attachment

Object

첨부 정보 객체입니다.

button

Object Array

버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

item

Object

와이드 아이템 요소입니다.

list

Object Array

아이템 목록입니다.

title

String

아이템 제목입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

video

Object

동영상 요소입니다.

videoUrl

필수String

카카오TV 동영상 URL입니다.

thumbnailUrl

String

동영상 썸네일 URL입니다.

carousel

Object

캐러셀 객체입니다.

head

Object

캐러셀 인트로 정보입니다.

header

String

캐러셀 인트로 헤더입니다.

content

String

캐러셀 인트로 내용입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

list

Object Array

캐러셀 아이템 목록입니다.

header

String

캐러셀 아이템 제목입니다.

message

String

캐러셀 아이템 본문입니다.

additionalContent

String

부가 정보입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

tail

Object

더보기 버튼 정보입니다.

urlMobile

필수String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

paymentCode

String

정산용 부서 코드입니다.

groupKey

String

메시지 인사이트 에서 그룹으로 묶어서 통계를 확인하기 위해 설정하는 키입니다.

idempotencyKey

String

요청에 대한 멱등함을 구분하는 멱등성 키 필드입니다.

idempotencyTtl

Integer

멱등 처리키 유효시간 입니다.

ref

String

요청 참조 필드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 메시지 응답 데이터입니다.

destinations

Object Array

수신자별 처리 결과 배열입니다.

요청 예시

curl -X POST "/api/comm/v1/send/omni" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [{ "to": "01012345678" }],
    "messageFlow": [{
      "brandmessage": {
        "sendType": "free",
        "msgType": "TEXT",
        "senderKey": "{senderKey}",
        "content": "자유형 브랜드메시지 본문입니다."
      }
    }],
    "ref": "brand-free-20260331-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "data": {
      "destinations": [{
        "to": "01012345678",
        "msgKey": "20260424104234546POM101182450000",
        "code": "A000",
        "result": "Success"
      }]
    },
    "ref": "brand-free-20260331-001"
  }
}

자유형 예약 발송

POST/api/comm/v1/reservation

브랜드메시지 자유형을 지정한 시각에 발송하도록 예약 등록합니다. 발송 가능한 상세 필드는 자유형 메시지 발송 규격과 동일합니다. 예약 등록 후 조회, 수정, 취소, 중지, 재개, 수신자 관리는 예약 관리 페이지에서 확인할 수 있습니다.

Body Parameters

{}JSON

destinations

필수Object Array

수신 정보 배열입니다. 동보발송 최대 200건입니다.

필수String

수신번호입니다.

ref

String

개별 참조 필드입니다.

messageFlow

필수Object Array

메시지를 추가하면 순서대로 자동 Fallback 메시지 처리됩니다.

brandmessage

필수Object

브랜드메시지 자유형 객체입니다.

sendType

필수String

브랜드메시지 발송 타입입니다.

msgType

필수String

카카오 비즈메시지 타입입니다.

text

String

메시지 본문입니다.

targeting

String

고객사의 광고성 정보 수신동의 회원 대상 타겟팅입니다.

header

String

헤더 정보입니다.

additionalContent

String

부가 정보입니다.

groupTagKey

String

그룹태그 등록으로 발급받은 키입니다.

adult

String

성인 대상 메시지 여부입니다.

pushAlarm

String

푸시 알림 발송 여부입니다.

adFlag

String

광고성메시지 필수 표기 사항 노출 여부입니다.

originCID

String

최초 발신사업자 식별코드입니다.

unsubscribePhoneNumber

String

무료 수신거부 전화번호입니다.

unsubscribeAuthNumber

String

무료 수신거부 인증번호입니다.

attachment

Object

첨부 정보 객체입니다.

button

Object Array

버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

item

Object

와이드 아이템 요소입니다.

list

Object Array

아이템 목록입니다.

title

String

아이템 제목입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

video

Object

동영상 요소입니다.

videoUrl

필수String

카카오TV 동영상 URL입니다.

thumbnailUrl

String

동영상 썸네일 URL입니다.

carousel

Object

캐러셀 객체입니다.

head

Object

캐러셀 인트로 정보입니다.

header

String

캐러셀 인트로 헤더입니다.

content

String

캐러셀 인트로 내용입니다.

urlMobile

String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

list

Object Array

캐러셀 아이템 목록입니다.

header

String

캐러셀 아이템 제목입니다.

message

String

캐러셀 아이템 본문입니다.

additionalContent

String

부가 정보입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

type

필수String

버튼 타입입니다.

name

String

버튼명입니다.

urlPc

String

PC 클릭 URL입니다.

urlMobile

String

모바일 클릭 URL입니다.

image

Object

이미지 요소입니다.

imgLink

String

이미지 클릭 URL입니다.

coupon

Object

쿠폰 요소입니다.

title

필수String

쿠폰명입니다.

description

필수String

쿠폰 상세 정보입니다.

commerce

Object

커머스 요소입니다.

title

필수String

상품명입니다.

regularPrice

필수Number

정가입니다.

discountPrice

Number

할인가입니다.

discountRate

Number

할인율(%)입니다.

discountFixed

Number

정액 할인금액입니다.

tail

Object

더보기 버튼 정보입니다.

urlMobile

필수String

모바일 클릭 URL입니다.

urlPc

String

PC 클릭 URL입니다.

schemeIos

String

iOS 커스텀 스킴입니다.

schemeAndroid

String

Android 커스텀 스킴입니다.

resvSendTime

필수String

예약 발송 시각입니다.

resvName

String

예약 건을 식별하기 위한 이름입니다.

ref

String

요청 참조 필드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

예약 등록 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/reservation" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [{
      "to": "01012345678"
    }],
    "messageFlow": [{
      "brandmessage": {
        "sendType": "free",
        "msgType": "FT",
        "senderKey": "{senderKey}",
        "content": "자유형 브랜드메시지 예약 발송 본문입니다.",
        "targeting": "M"
      }
    }],
    "resvSendTime": "2026-05-01 10:00:00",
    "resvName": "브랜드메시지 자유형 예약 발송",
    "ref": "brand-free-resv-20260501-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "Success",
    "resvKey": "20260501100000RESV0000000001"
  }
}

브랜드메시지 기본형 동보 발송

친구 그룹 또는 전체 친구를 대상으로 기본형 템플릿 메시지를 일괄 발송하는 기능입니다. 발송 제어(재개·중지·종료)와 상태 조회를 함께 제공합니다. 발송 전 예상 모수·소요 시간 확인은 브랜드메시지 발송 사전 확인을 참고하세요.

동보 발송

동보 발송 참고사항
메시지 발송에 사용하는 템플릿은 변수가 없어야 하며, 템플릿 상태가 등록(A)이어야 합니다.
요청한 동보 메시지 발송 시작 일시에 맞춰 자동 발송되며, 20:50~익일 08:00에는 자동 중지 후 익일 08:00 이후 자동 재개됩니다.
친구 그룹 사용 시 그룹 상태가 C(Completed)이고, 그룹 내 등록 유저 수(user_count)가 10 이상이어야 메시지 발송 예약이 가능합니다.
친구 그룹 내 친구 관계는 실시간으로 동기화됩니다.
전체 친구 발송·친구 그룹 발송 모두 발송 요청 시점의 친구 관계를 기반으로 발송 수를 설정하며, 실제 발송 시점의 친구 관계에 따라 설정된 발송 수 내에서 순차적으로 발송됩니다.

POST/api/comm/v1/center/brandmessage/groupMessage

메시지 발송 체험하기 샌드박스로 테스트하기

기본형 템플릿을 기준으로 카카오 친구 그룹 전체에 동보발송을 예약합니다. 발송 시작 시각은 요청 시점 기준 10분 이후부터 설정할 수 있고, 08:00~20:50(KST) 범위에서 운영합니다.

Body Parameters

{} JSON

brandmessage

필수Object

기본형 템플릿 동보발송 정보입니다.

sendStartAt

필수String

동보발송 시작 일시입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

originCID

String

최초 발신사업자 식별코드입니다.

paymentCode

String

정산용 부서 코드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

동보발송 응답 데이터입니다.

brandmessage

Object

동보발송 기본 정보입니다.

status

String

동보발송 상태입니다.

sendStartAt

String

동보발송 시작 일시입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "brandmessage": {
      "senderKey": "{senderKey}",
      "templateCode": "{templateCode}",
      "friendGroupKey": "{friendGroupKey}",
      "sendStartAt": "2026-04-08 16:40:00",
      "pushAlarm": "Y"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "requestId":"1203981",
        "status":"READY",
        "sendStartAt":"2026-04-08 16:40:00",
        "pushAlarm":"Y",
        "expectedCount": 7,
        "sendCount": 0,
        "senderKey":"{senderKey}",
        "msgType":"FI",
        "templateCode":"{templateCode}"
      }
    }
  }
}

동보 발송 재개

POST/api/comm/v1/center/brandmessage/groupMessage/resume

샌드박스로 테스트하기

중지된 기본형 템플릿 동보발송 요청을 다시 시작합니다.

Body Parameters

{} JSON

brandmessage

필수Object

동보발송 제어 정보입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

동보발송 응답 데이터입니다.

brandmessage

Object

동보발송 기본 정보입니다.

status

String

동보발송 상태입니다.

sendStartAt

String

동보발송 시작 일시입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/resume" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "brandmessage": {
      "senderKey": "{senderKey}",
      "requestId": "1203981"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "requestId":"1203981",
        "status":"READY",
        "sendStartAt":"2026-04-08 16:20:00",
        "pushAlarm":"Y",
        "expectedCount": 7,
        "sendCount": 0,
        "senderKey":"{senderKey}",
        "msgType":"FI",
        "templateCode":"{templateCode}"
      }
    }
  }
}

동보 발송 중지

POST/api/comm/v1/center/brandmessage/groupMessage/pause

샌드박스로 테스트하기

진행 중인 기본형 템플릿 동보발송 요청을 일시 중지합니다.

Body Parameters

{} JSON

brandmessage

필수Object

동보발송 제어 정보입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

동보발송 응답 데이터입니다.

brandmessage

Object

동보발송 기본 정보입니다.

status

String

동보발송 상태입니다.

sendStartAt

String

동보발송 시작 일시입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/pause" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "brandmessage": {
      "senderKey": "{senderKey}",
      "requestId": "1203981"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "requestId":"1203981",
        "status":"PAUSED",
        "sendStartAt":"2026-04-08 16:20:00",
        "pushAlarm":"Y",
        "expectedCount": 7,
        "sendCount": 3,
        "senderKey":"{senderKey}",
        "msgType":"FI",
        "templateCode":"{templateCode}"
      }
    }
  }
}

동보 발송 종료

POST/api/comm/v1/center/brandmessage/groupMessage/terminate

샌드박스로 테스트하기

예약 또는 진행 중인 기본형 템플릿 동보발송 요청을 종료합니다.

Body Parameters

{} JSON

brandmessage

필수Object

동보발송 제어 정보입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

동보발송 응답 데이터입니다.

brandmessage

Object

동보발송 기본 정보입니다.

status

String

동보발송 상태입니다.

sendStartAt

String

동보발송 시작 일시입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/terminate" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "brandmessage": {
      "senderKey": "{senderKey}",
      "requestId": "1203981"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "requestId":"1203981",
        "status":"TERMINATED",
        "sendStartAt":"2026-04-08 16:20:00",
        "pushAlarm":"Y",
        "expectedCount": 7,
        "sendCount": 3,
        "senderKey":"{senderKey}",
        "msgType":"FI",
        "templateCode":"{templateCode}"
      }
    }
  }
}

동보 발송 조회

GET/api/comm/v1/center/brandmessage/groupMessage

샌드박스로 테스트하기

발신프로필 키와 요청 아이디를 기준으로 특정 동보발송 요청 상태를 조회합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

requestId

필수Integer

동보발송 요청 아이디입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

동보발송 응답 데이터입니다.

brandmessage

Object

동보발송 기본 정보입니다.

status

String

동보발송 상태입니다.

sendStartAt

String

동보발송 시작 일시입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage?senderKey={senderKey}&requestId=1203981" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "requestId":"1203981",
        "status":"SENDING",
        "sendStartAt":"2026-04-08 16:40:00",
        "pushAlarm":"Y",
        "expectedCount": 7,
        "sendCount": 3,
        "senderKey":"{senderKey}",
        "msgType":"FI",
        "templateCode":"{templateCode}"
      }
    }
  }
}

최근 변경된 동보 발송 요청 목록 조회

GET/api/comm/v1/center/brandmessage/groupMessage/lastModified

샌드박스로 테스트하기

기준 시각 이후 변경된 동보발송 요청 아이디 목록을 조회합니다. 누락된 요청 상태를 후속 동기화할 때 사용할 수 있습니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

since

String

변경 기준 일시입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

변경 이력 응답 데이터입니다.

brandmessage

Object

동보발송 조회 결과입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/lastModified?senderKey={senderKey}&since=2026-04-08T15:00:00" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "requestIds": ["1203981", "1203982", "1203983"]
      }
    }
  }
}

브랜드메시지 발송 사전 확인

발송 전에 예상 발송 수·과금액, 보유 친구 수, 예상 소요시간을 미리 확인하는 조회 기능입니다. 친구 그룹 기반과 전화번호 명단 기반을 모두 지원하며, 동보 발송뿐 아니라 발송 전 사전 검증 용도로 사용합니다.

발송 예상 모수 확인 (친구그룹 기반)

GET/api/comm/v1/center/brandmessage/groupMessage/possible

샌드박스로 테스트하기

메시지 타입과 친구 그룹 조건을 기준으로 동보발송 예상 발송 수를 조회합니다. 친구 그룹을 사용할 경우 그룹 상태가 완료(C)이고 그룹 내 등록 유저 수가 10 이상이어야 발송 예약이 가능하며, 친구 관계는 실시간으로 동기화됩니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

msgType

필수String

브랜드메시지 타입입니다. (카카오 원본 chatBubbleType로 변환됩니다.)

friendGroupKey

String

대상 친구 그룹 키입니다. 미지정 시 전체 친구를 기준으로 조회합니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

발송 가능 수 응답 데이터입니다.

brandmessage

Object

동보발송 가능 수 결과입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/possible?senderKey={senderKey}&msgType=FI&friendGroupKey={friendGroupKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "possible": 320
      }
    }
  }
}

발송 예상 모수 확인 (전화번호 명단 기반)

POST/api/comm/v1/center/brandmessage/groupMessage/friend/possible

샌드박스로 테스트하기

전화번호 명단을 기준으로 동보발송 가능 예상 수를 조회합니다. 명단은 국가코드가 자동 정규화되며, 유효한 번호를 대상으로 발송 가능 모수를 계산합니다. 최소 10건 이상이어야 하고, 하나라도 형식이 잘못되면 요청 전체가 거부됩니다.

Body Parameters

{} JSON

senderKey

필수String

발신프로필 키입니다.

phoneNumbers

필수String Array

발송 가능 여부를 확인할 전화번호 목록입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

발송 가능 수 응답 데이터입니다.

brandmessage

Object

동보발송 가능 수 결과입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/friend/possible" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "senderKey": "{senderKey}",
    "phoneNumbers": [
      "01000000000",
      "01000000001"
    ]
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "possible": 320
      }
    }
  }
}

채널 전체 친구 수 조회

GET/api/comm/v1/center/brandmessage/groupMessage/friendCount

샌드박스로 테스트하기

발신프로필 기준 친구 수를 조회합니다. 동보발송 가능 대상 수를 사전에 확인할 때 사용합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

친구 수 응답 데이터입니다.

brandmessage

Object

친구 수 조회 결과입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/friendCount?senderKey={senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "count": 1250
      }
    }
  }
}

예상 소요시간 조회

GET/api/comm/v1/center/brandmessage/groupMessage/estimate

샌드박스로 테스트하기

동보발송 시작 시각과 대상 수를 기준으로 예상 종료 시각과 소요 시간을 조회합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

startTime

필수String

동보발송 시작 일시입니다.

count

필수Integer

발송 모수입니다.

target

String

대상 유형입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

예상 시간 응답 데이터입니다.

brandmessage

Object

동보발송 예상 시간 결과입니다.

estimatedFinishedAt

String

예상 종료 시각입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/estimate?senderKey={senderKey}&startTime=2026-04-08T16:40:00&count=320&target=FRIEND_GROUP" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "estimatedFinishedAt":"2026-04-08T16:58:00",
        "duration": 18
      }
    }
  }
}

이미지 파일 관리

브랜드메시지 템플릿과 자유형 메시지 구성에 사용할 이미지 파일을 업로드합니다. 메시지 타입과 레이아웃에 따라 업로드 경로를 구분합니다.

이미지 업로드

POST/api/comm/v1/file/brandmessage/default

샌드박스로 테스트하기

기본형 브랜드메시지에서 사용하는 이미지를 업로드합니다. 발송 본문에 파일을 직접 첨부하는 API가 아니라 브랜드메시지 템플릿 등록과 구성에 사용할 이미지 URL을 발급받는 API입니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 브랜드메시지 이미지 파일 바이너리입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/default" \
  -H "Authorization: {ApiKey}" \
  -F "file=@/path/brand-image.jpg"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "imgUrl":"https://example.kakao.image/brand-image.jpg"
    }
  }
}

와이드 이미지 업로드

POST/api/comm/v1/file/brandmessage/wide

샌드박스로 테스트하기

와이드 이미지형 브랜드메시지에서 사용하는 이미지를 업로드합니다. 발급된 imgUrl은 브랜드메시지 템플릿 또는 발송 구성에 사용합니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 브랜드메시지 이미지 파일 바이너리입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/wide" \
  -H "Authorization: {ApiKey}" \
  -F "file=@/path/brand-image.jpg"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "imgUrl":"https://example.kakao.image/brand-image.jpg"
    }
  }
}

와이드 리스트 첫번째 이미지 업로드

POST/api/comm/v1/file/brandmessage/wideItemList/first

샌드박스로 테스트하기

와이드 리스트형 브랜드메시지의 첫 번째 리스트 이미지에 사용할 이미지를 업로드합니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 브랜드메시지 이미지 파일 바이너리입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/wideItemList/first" \
  -H "Authorization: {ApiKey}" \
  -F "file=@/path/brand-image.jpg"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "imgUrl":"https://example.kakao.image/brand-image.jpg"
    }
  }
}

와이드 리스트 이미지 업로드

POST/api/comm/v1/file/brandmessage/wideItemList

샌드박스로 테스트하기

와이드 리스트형 브랜드메시지의 2~4번째 리스트 이미지에 사용할 이미지를 업로드합니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 브랜드메시지 이미지 파일 바이너리입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/wideItemList" \
  -H "Authorization: {ApiKey}" \
  -F "file=@/path/brand-image.jpg"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "imgUrl":"https://example.kakao.image/brand-image.jpg"
    }
  }
}

캐러셀 피드 이미지 업로드

POST/api/comm/v1/file/brandmessage/carouselFeed

샌드박스로 테스트하기

캐러셀 피드형 브랜드메시지에서 사용하는 이미지를 업로드합니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 브랜드메시지 이미지 파일 바이너리입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/carouselFeed" \
  -H "Authorization: {ApiKey}" \
  -F "file=@/path/brand-image.jpg"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "imgUrl":"https://example.kakao.image/brand-image.jpg"
    }
  }
}

캐러셀 커머스 이미지 업로드

POST/api/comm/v1/file/brandmessage/carouselCommerce

샌드박스로 테스트하기

캐러셀 커머스형 브랜드메시지에서 사용하는 이미지를 업로드합니다. 전체 캐러셀 이미지 비율은 동일하게 맞춰야 합니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 브랜드메시지 이미지 파일 바이너리입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/carouselCommerce" \
  -H "Authorization: {ApiKey}" \
  -F "file=@/path/brand-image.jpg"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "imgUrl":"https://example.kakao.image/brand-image.jpg"
    }
  }
}

동영상 관리

브랜드메시지에 사용할 동영상을 등록하고 처리 상태를 조회합니다. 발송용 동영상을 준비하는 방법은 두 가지입니다.

신규 업로드 — 아직 카카오에 올리지 않은 동영상. 업로드 채널을 발급받아 클라이언트가 그 채널로 파일을 직접 올리는 2단계 구조입니다. (이미지 파일 관리 API와 달리 파일을 직접 전송받지 않습니다.)
기존 동영상 등록 — 이미 채널에 올라가 있는 동영상. 재업로드 없이 vid 또는 videoUrl로 발송용 등록만 합니다.

신규 업로드 흐름

TEXT

1. 업로드 등록  POST /video/upload/register
   → 응답으로 vid, uploadUrl, token 발급
              │
              ▼
2. 파일 전송   클라이언트 → uploadUrl (카카오 서버로 직접 전송, token 사용)
              │
              ▼
3. 상태 확인   GET /video?vid=...
   → status 가 PUBLIC 이면 발송 가능 (PRIVATE 은 템플릿 등록만 가능)

1번 응답의 A000은 업로드 채널 발급 성공을 의미할 뿐, 동영상 등록 완료가 아닙니다. 실제 사용 가능 여부는 3번 조회의 status로 확인하세요.

2단계: 동영상 파일 전송

1단계 응답으로 받은 uploadUrl에 동영상 파일을 직접 전송합니다. uploadUrl과 token은 발급 후 5분간만 유효하며, 실패 시 업로드 등록(1단계)부터 다시 시도해야 합니다.

구분	값
메서드·URL	`POST {uploadUrl}`
헤더	`x-kamp-upload-token: {token}` · `Content-Type: multipart/form-data`
본문	`file` — 동영상 바이너리

Bash

curl -X POST \
  -H 'x-kamp-upload-token: {token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@{video_file}' \
  '{uploadUrl}'

이 전송은 카카오 업로드 서버로 직접 보내며 비즈고 API를 거치지 않습니다. 성공 응답의 vid로 3단계 상태 조회를 진행하세요. 실패 시 응답의 errCode·message로 원인(존재하지 않는 vid, 용량·해상도·길이 초과, 미지원 형식, 토큰 인증 실패 등)을 확인할 수 있습니다.

기존 동영상 등록 규칙

이미 카카오톡 채널에 올려둔 동영상은 위 2단계를 거치지 않고 vid 또는 videoUrl만 지정해 바로 등록합니다.

하나는 필수 — vid·videoUrl 중 최소 하나를 입력합니다. 둘 다 입력하면 videoUrl이 우선 적용됩니다.
videoUrl 형식 — https://business.kakao.com/{채널식별자}/videos/{vid}
등록 가능 상태 — PUBLIC 또는 PRIVATE 상태의 동영상만 등록할 수 있습니다.

동영상 상태 코드

조회·등록 응답의 status 값입니다.

status	설명
`REGISTERED`	업로드 등록됨
`ENCODING`	인코딩 중
`PUBLIC`	공개 — 발송·템플릿 등록 가능
`PRIVATE`	비공개 — 템플릿 등록만 가능
`VIOLATED`	정책 위반 동영상
`ILLEGAL`	불법촬영물 동영상
`DELETED`	삭제된 동영상
`ERROR`	업로드·인코딩 중 에러 발생

동영상 업로드 등록

POST/api/comm/v1/center/brandmessage/video/upload/register

샌드박스로 테스트하기

브랜드메시지에 사용할 동영상의 업로드를 등록하고, 카카오 업로드 채널 정보를 발급받습니다. 이 API는 업로드 채널만 발급하며, 실제 파일 전송은 응답으로 받은 uploadUrl로 직접 수행해야 합니다.

Body Parameters

{} JSON

senderKey

필수String

발신프로필 키입니다. max: 40

fileName

필수String

업로드할 동영상 파일 이름입니다.

fileSize

필수Number

업로드할 동영상 파일 크기입니다. 단위: byte

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 등록 결과 데이터입니다.

brandmessage

Object

브랜드메시지 응답 영역입니다.

video

Object

발급된 업로드 채널 정보입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video/upload/register" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "senderKey": "{senderKey}",
    "fileName": "brand-promotion.mp4",
    "fileSize": 4075447
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "video": {
          "vid":"rvuzx2fkv08xrgrrhuwsc151z",
          "uploadUrl":"https://up03-kamp.kakao.com/v4/upload/rvuzx2fkv08xrgrrhuwsc151z/open",
          "token":"zXupsa4sM18oTL-..."
        }
      }
    }
  }
}

기존 동영상 등록

POST/api/comm/v1/center/brandmessage/video/register

샌드박스로 테스트하기

카카오톡 채널에 이미 업로드되어 있는 동영상을 재업로드 없이 브랜드메시지 발송용으로 등록합니다. 업로드 채널을 발급받는 동영상 업로드 등록과는 별개의 API이며, 동영상 식별은 vid 또는 videoUrl 중 하나로만 지정합니다.

Body Parameters

{} JSON

senderKey

필수String

발신프로필 키입니다. max: 40

vid

String

등록할 동영상 식별자입니다. videoUrl과 함께 사용할 수 없습니다.

videoUrl

String

등록할 채널 동영상 URL입니다. vid와 함께 사용할 수 없습니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

등록 결과 데이터입니다.

brandmessage

Object

브랜드메시지 응답 영역입니다.

video

Object

등록된 동영상 정보입니다.

status

String

동영상 공개 상태입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video/register" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "senderKey": "{senderKey}",
    "vid": "rvhyrk8x0dqp0d8oiyc1w2m9t"
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "video": {
          "vid":"rvhyrk8x0dqp0d8oiyc1w2m9t",
          "status":"PUBLIC",
          "title":"도시",
          "thumbnailUrl":"https://thumb.kakaocdn.net/.../2.jpg",
          "videoUrl":"https://business.kakao.com/_jIxmCs/videos/1090870"
        }
      }
    }
  }
}

동영상 조회

GET/api/comm/v1/center/brandmessage/video

샌드박스로 테스트하기

동영상 식별자를 기준으로 업로드된 동영상 한 건의 처리 상태와 메타 정보를 조회합니다.

Query Parameters

vid

필수String

조회할 동영상 식별자입니다.

senderKey

필수String

발신프로필 키입니다. max: 40

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

조회 결과 데이터입니다.

brandmessage

Object

브랜드메시지 응답 영역입니다.

video

Object

동영상 정보입니다.

status

String

동영상 처리 상태입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video?vid={vid}&senderKey={senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "video": {
          "vid":"rvuzx2fkv08xrgrrhuwsc151z",
          "status":"PUBLIC",
          "title":"brand-promotion",
          "thumbnailUrl":"https://thumb.kakaocdn.net/.../2.jpg",
          "videoUrl":"https://business.kakao.com/_jIxmCs/videos/1079462"
        }
      }
    }
  }
}

동영상 목록 조회

GET/api/comm/v1/center/brandmessage/video/list

샌드박스로 테스트하기

발신프로필 기준으로 업로드한 동영상 이력을 목록으로 조회합니다. 등록일자로 필터링하고 offset과 limit으로 페이징할 수 있습니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다. max: 40

date

String

조회할 등록일자입니다. 미지정 시 전체를 조회합니다. 형식: yyyyMMdd

offset

Number

조회 시작 위치입니다. 음수는 사용할 수 없습니다. default: 0

limit

Number

조회 건수입니다. default: 100, max: 1000

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

조회 결과 데이터입니다.

videos

Object Array

동영상 이력 배열입니다.

status

String

동영상 처리 상태입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video/list?senderKey={senderKey}&date=20260624&offset=0&limit=100" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "offset": 0,
      "limit": 100,
      "totalCount": 1,
      "videos": [{
        "vid":"rvuzx2fkv08xrgrrhuwsc151z",
        "senderKey":"{senderKey}",
        "fileName":"brand-promotion.mp4",
        "fileSize": 4075447,
        "status":"PUBLIC",
        "title":"brand-promotion",
        "thumbnailUrl":"https://thumb.kakaocdn.net/.../2.jpg",
        "videoUrl":"https://business.kakao.com/_jIxmCs/videos/1079462",
        "modifiedAt":"2026-06-24 15:53:05",
        "regDate":"2026-06-24 15:52:29",
        "updateDate":"2026-06-24 15:53:05"
      }]
    }
  }
}

기본형 템플릿 관리

기본형 브랜드메시지 발송에 사용하는 템플릿을 조회하고 등록, 수정, 삭제합니다. 이미지가 필요한 유형은 이미지 파일 관리 API로 먼저 imgUrl을 발급받아 사용합니다.

템플릿 조회

GET/api/comm/v1/center/brandmessage/template

샌드박스로 테스트하기

발신프로필 키와 템플릿 코드를 기준으로 브랜드메시지 템플릿 상세 정보를 조회합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

templateCode

필수String

템플릿 코드입니다.

sendType

String

브랜드메시지 발송 타입입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

템플릿 응답 데이터입니다.

brandmessage

Object

브랜드메시지 템플릿 정보입니다.

carousel

Object

캐러셀 정보입니다.

head

Object

캐러셀 인트로 정보입니다.

list

Object Array

캐러셀 아이템 리스트입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

image

Object

캐러셀 아이템 이미지 요소입니다.

coupon

Object

캐러셀 아이템 쿠폰 요소입니다.

commerce

Object

캐러셀 아이템 커머스 요소입니다.

tail

Object

더보기 버튼 정보입니다.

attachment

Object

첨부 정보입니다.

button

Object Array

버튼 목록입니다.

image

Object

이미지 요소입니다.

item

Object

와이드 리스트 요소입니다.

list

Object Array

아이템 목록입니다.

coupon

Object

쿠폰 요소입니다.

commerce

Object

커머스 요소입니다.

video

Object

비디오 요소입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

status

String

템플릿 상태입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template?senderKey={senderKey}&templateCode={templateCode}&sendType=basic" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "senderKey":"{senderKey}",
        "sendType":"basic",
        "templateCode":"{templateCode}",
        "msgType":"FT",
        "text":"#{customerName}님, 혜택을 확인해 주세요.",
        "pushAlarm":"Y",
        "createAt":"2026-04-24T10:42:34+09:00",
        "modifiedAt":"2026-04-24T10:42:34+09:00",
        "status":"A"
      }
    }
  }
}

최근 변경 템플릿 조회

GET/api/comm/v1/center/brandmessage/template/lastModified

샌드박스로 테스트하기

지정한 시각 이후 최근 변경된 브랜드메시지 템플릿 목록을 조회합니다. 템플릿 최신화나 내부 동기화 배치 기준으로 사용할 수 있습니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

senderKeyType

String

발신키 유형입니다.

since

String

조회 시작 시각입니다.

page

Integer

페이지 번호입니다.

count

Integer

페이지당 조회 건수입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

최근 변경 템플릿 응답 데이터입니다.

brandmessage

Object

브랜드메시지 템플릿 결과 영역입니다.

templates

Object Array

최근 변경된 템플릿 목록입니다.

senderKeyType

String

발신키 유형입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template/lastModified?senderKey={senderKey}&senderKeyType=S&since=2026-04-23T09:00:00&page=1&count=100" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "templates": [{
          "senderKey":"{senderKey}",
          "senderKeyType":"S",
          "templateCode":"BRAND_TEXT_001"
        }]
      }
    }
  }
}

템플릿 등록

POST/api/comm/v1/center/brandmessage/template

샌드박스로 테스트하기

브랜드메시지 템플릿을 등록합니다. 이미지가 필요한 유형은 브랜드메시지 이미지 업로드 API로 발급받은 imgUrl을 함께 사용합니다.

Body Parameters

{} JSON

brandmessage

필수Object

브랜드메시지 템플릿 정보입니다.

sendType

필수String

카카오 브랜드메시지 타입입니다.

msgType

필수String

브랜드메시지 메시지 타입입니다.

templateName

필수String

템플릿 이름입니다.

carousel

Object

캐러셀 정보입니다.

head

Object

캐러셀 인트로 정보입니다.

list

Object Array

캐러셀 아이템 리스트입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

image

Object

캐러셀 아이템 이미지 요소입니다.

coupon

Object

캐러셀 아이템 쿠폰 요소입니다.

commerce

Object

캐러셀 아이템 커머스 요소입니다.

tail

Object

더보기 버튼 정보입니다.

attachment

Object

첨부 정보입니다.

button

Object Array

버튼 목록입니다.

image

Object

이미지 정보입니다.

item

Object

와이드 리스트 요소입니다.

list

Object Array

아이템 목록입니다.

coupon

Object

쿠폰 요소입니다.

commerce

Object

커머스 요소입니다.

video

Object

비디오 요소입니다.

header

String

헤더 정보입니다.

additionalContent

String

부가 정보입니다.

pushAlarm

String

메시지 푸시 알람 발송 여부입니다.

status

String

템플릿 상태입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

템플릿 응답 데이터입니다.

brandmessage

Object

브랜드메시지 템플릿 정보입니다.

carousel

Object

캐러셀 정보입니다.

head

Object

캐러셀 인트로 정보입니다.

list

Object Array

캐러셀 아이템 리스트입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

image

Object

캐러셀 아이템 이미지 요소입니다.

coupon

Object

캐러셀 아이템 쿠폰 요소입니다.

commerce

Object

캐러셀 아이템 커머스 요소입니다.

tail

Object

더보기 버튼 정보입니다.

attachment

Object

첨부 정보입니다.

button

Object Array

버튼 목록입니다.

image

Object

이미지 요소입니다.

item

Object

와이드 리스트 요소입니다.

list

Object Array

아이템 목록입니다.

coupon

Object

쿠폰 요소입니다.

commerce

Object

커머스 요소입니다.

video

Object

비디오 요소입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

status

String

템플릿 상태입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "brandmessage": {
      "senderKey": "{senderKey}",
      "sendType": "basic",
      "templateName": "브랜드 혜택 안내",
      "msgType": "FT",
      "text": "#{customerName}님, 새로운 혜택을 확인해 주세요.",
      "pushAlarm": "Y"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "senderKey":"{senderKey}",
        "sendType":"basic",
        "templateCode":"BRAND_TEXT_001",
        "msgType":"FT",
        "text":"#{customerName}님, 새로운 혜택을 확인해 주세요.",
        "pushAlarm":"Y",
        "createAt":"2026-04-24T10:42:34+09:00",
        "modifiedAt":"2026-04-24T10:42:34+09:00",
        "status":"A"
      }
    }
  }
}

템플릿 수정

PUT/api/comm/v1/center/brandmessage/template

샌드박스로 테스트하기

등록된 브랜드메시지 템플릿 정보를 수정합니다. 검수 상태와 카카오 정책에 따라 수정 가능한 범위가 달라질 수 있습니다.

Body Parameters

{} JSON

brandmessage

필수Object

브랜드메시지 템플릿 정보입니다.

sendType

필수String

카카오 브랜드메시지 타입입니다.

msgType

필수String

브랜드메시지 메시지 타입입니다.

templateName

필수String

템플릿 이름입니다.

carousel

Object

캐러셀 정보입니다.

head

Object

캐러셀 인트로 정보입니다.

list

Object Array

캐러셀 아이템 리스트입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

image

Object

캐러셀 아이템 이미지 요소입니다.

coupon

Object

캐러셀 아이템 쿠폰 요소입니다.

commerce

Object

캐러셀 아이템 커머스 요소입니다.

tail

Object

더보기 버튼 정보입니다.

attachment

Object

첨부 정보입니다.

button

Object Array

버튼 목록입니다.

image

Object

이미지 정보입니다.

item

Object

와이드 리스트 요소입니다.

list

Object Array

아이템 목록입니다.

coupon

Object

쿠폰 요소입니다.

commerce

Object

커머스 요소입니다.

video

Object

비디오 요소입니다.

header

String

헤더 정보입니다.

additionalContent

String

부가 정보입니다.

pushAlarm

String

메시지 푸시 알람 발송 여부입니다.

status

String

템플릿 상태입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

템플릿 응답 데이터입니다.

brandmessage

Object

브랜드메시지 템플릿 정보입니다.

carousel

Object

캐러셀 정보입니다.

head

Object

캐러셀 인트로 정보입니다.

list

Object Array

캐러셀 아이템 리스트입니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

button

Object Array

캐러셀 아이템 버튼 목록입니다.

image

Object

캐러셀 아이템 이미지 요소입니다.

coupon

Object

캐러셀 아이템 쿠폰 요소입니다.

commerce

Object

캐러셀 아이템 커머스 요소입니다.

tail

Object

더보기 버튼 정보입니다.

attachment

Object

첨부 정보입니다.

button

Object Array

버튼 목록입니다.

image

Object

이미지 요소입니다.

item

Object

와이드 리스트 요소입니다.

list

Object Array

아이템 목록입니다.

coupon

Object

쿠폰 요소입니다.

commerce

Object

커머스 요소입니다.

video

Object

비디오 요소입니다.

pushAlarm

String

메시지 푸시 알림 발송 여부입니다.

status

String

템플릿 상태입니다.

요청 예시

curl -X PUT "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "brandmessage": {
      "senderKey": "{senderKey}",
      "sendType": "basic",
      "templateName": "브랜드 혜택 안내 수정",
      "msgType": "FT",
      "text": "#{customerName}님, 업데이트된 혜택을 확인해 주세요.",
      "pushAlarm": "Y"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "brandmessage": {
        "senderKey":"{senderKey}",
        "sendType":"basic",
        "templateCode":"BRAND_TEXT_001",
        "msgType":"FT",
        "text":"#{customerName}님, 업데이트된 혜택을 확인해 주세요.",
        "pushAlarm":"Y",
        "createAt":"2026-04-24T10:42:34+09:00",
        "modifiedAt":"2026-04-24T10:42:34+09:00",
        "status":"A"
      }
    }
  }
}

템플릿 삭제

DELETE/api/comm/v1/center/brandmessage/template/senderKey/{senderKey}/templateCode/{templateCode}

샌드박스로 테스트하기

발신프로필 키와 템플릿 코드를 기준으로 브랜드메시지 템플릿을 삭제합니다.

Path Parameters

senderKey

필수String

발신프로필 키입니다.

templateCode

필수String

삭제할 템플릿 코드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template/senderKey/{senderKey}/templateCode/{templateCode}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

그룹태그 관리

그룹태그는 브랜드메시지 템플릿과 운영 대상을 분류하기 위한 관리 정보입니다. 발신프로필 기준으로 그룹태그를 조회하고 등록, 수정, 삭제할 수 있습니다.

전체 그룹태그 조회

GET/api/comm/v1/center/brandmessage/groupTag/list

샌드박스로 테스트하기

발신프로필 키를 기준으로 브랜드메시지 전체 그룹태그 목록을 조회합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

그룹태그 응답 데이터입니다.

groupTags

Object Array

그룹태그 목록입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag/list?senderKey={senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "groupTags": [{
        "groupTagKey":"{groupTagKey}",
        "groupTagName":"VIP 고객"
      }]
    }
  }
}

그룹태그 조회

GET/api/comm/v1/center/brandmessage/groupTag

샌드박스로 테스트하기

발신프로필 키와 그룹태그 키를 기준으로 브랜드메시지 그룹태그 상세 정보를 조회합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

groupTagKey

필수String

그룹태그 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

그룹태그 응답 데이터입니다.

groupTags

Object Array

그룹태그 목록입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag?senderKey={senderKey}&groupTagKey={groupTagKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "groupTags": [{
        "groupTagKey":"{groupTagKey}",
        "groupTagName":"VIP 고객"
      }]
    }
  }
}

그룹태그 등록

POST/api/comm/v1/center/brandmessage/groupTag

샌드박스로 테스트하기

브랜드메시지 그룹태그를 등록합니다.

Body Parameters

{} JSON

groupTag

필수Object

브랜드메시지 그룹태그 정보입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

그룹태그 응답 데이터입니다.

groupTags

Object Array

그룹태그 목록입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "groupTag": {
      "groupTagKey": "VIP_CUSTOMER",
      "groupTagName": "VIP 고객"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "groupTags": [{
        "groupTagKey":"VIP_CUSTOMER",
        "groupTagName":"VIP 고객"
      }]
    }
  }
}

그룹태그 수정

PUT/api/comm/v1/center/brandmessage/groupTag

샌드박스로 테스트하기

등록된 브랜드메시지 그룹태그 정보를 수정합니다.

Body Parameters

{} JSON

groupTag

필수Object

브랜드메시지 그룹태그 정보입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

그룹태그 응답 데이터입니다.

groupTags

Object Array

그룹태그 목록입니다.

요청 예시

curl -X PUT "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "groupTag": {
      "groupTagKey": "VIP_CUSTOMER",
      "groupTagName": "VIP 고객 수정"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "groupTags": [{
        "groupTagKey":"VIP_CUSTOMER",
        "groupTagName":"VIP 고객 수정"
      }]
    }
  }
}

그룹태그 삭제

DELETE/api/comm/v1/center/brandmessage/groupTag/senderKey/{senderKey}/groupTagKey/{groupTagKey}

샌드박스로 테스트하기

발신프로필 키와 그룹태그 키를 기준으로 브랜드메시지 그룹태그를 삭제합니다.

Path Parameters

senderKey

필수String

발신프로필 키입니다.

groupTagKey

필수String

삭제할 그룹태그 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag/senderKey/{senderKey}/groupTagKey/{groupTagKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

친구 그룹 관리

친구 그룹은 발신프로필 기준으로 친구 대상을 그룹화해 기본형 동보발송에 활용하는 관리 기능입니다. 파일 업로드나 전화번호 배열로 그룹을 생성하고, 그룹별 전화번호를 추가, 삭제할 수 있습니다.

친구 그룹 파일 업로드

POST/api/comm/v1/center/brandmessage/friendGroup/file

샌드박스로 테스트하기

전화번호 목록 파일을 업로드해 친구 그룹 등록 또는 전화번호 추가·삭제에 사용할 임시 파일 키를 발급받습니다.

Body Parameters

FORM-DATA

senderKey

필수String

발신프로필 키입니다.

file

필수Binary

업로드할 전화번호 목록 파일입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

친구 그룹 파일 업로드 결과입니다.

friendGroup

Object

임시 업로드 파일 정보입니다.

expiredAt

String

만료 일시입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/file" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: multipart/form-data" \
  -F "senderKey={senderKey}" \
  -F "file=@friend-group.csv"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "friendGroup": {
        "fileKey":"{fileKey}",
        "expiredAt":"2026-04-10 14:03:25"
      }
    }
  }
}

친구 그룹 등록

POST/api/comm/v1/center/brandmessage/friendGroup

샌드박스로 테스트하기

친구 그룹을 생성합니다. fileKey 또는 phoneNumbers를 이용해 그룹에 포함할 전화번호 목록을 함께 등록할 수 있습니다.

Body Parameters

{} JSON

friendGroup

필수Object

친구 그룹 정보입니다.

friendGroupKey

필수String

친구 그룹 키입니다.

phoneNumbers

String Array

전화번호 목록입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

친구 그룹 응답 데이터입니다.

friendGroup

Object

친구 그룹 정보입니다.

status

String

친구 그룹 처리 상태입니다.

createdAt

String

생성 일시입니다.

modifiedAt

String

수정 일시입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "friendGroup": {
      "senderKey": "{senderKey}",
      "friendGroupKey": "VIP_CUSTOMERS",
      "phoneNumbers": [
        "01000000000",
        "01000000001"
      ]
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "friendGroup": {
        "friendGroupKey":"VIP_CUSTOMERS",
        "requestId": 1203981,
        "status":"IN_PROGRESS",
        "createdAt":"2026-04-09 15:10:00",
        "modifiedAt":"2026-04-09 15:10:00"
      }
    }
  }
}

친구 그룹 조회

GET/api/comm/v1/center/brandmessage/friendGroup

샌드박스로 테스트하기

발신프로필 키와 친구 그룹 키를 기준으로 친구 그룹 상세 정보를 조회합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

friendGroupKey

필수String

친구 그룹 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

친구 그룹 상세 응답 데이터입니다.

friendGroup

Object

친구 그룹 상세 정보입니다.

friendCount

Integer

친구 수입니다.

status

String

친구 그룹 처리 상태입니다.

createdAt

String

생성 일시입니다.

modifiedAt

String

수정 일시입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup?senderKey={senderKey}&friendGroupKey=VIP_CUSTOMERS" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "friendGroup": {
        "friendGroupKey":"VIP_CUSTOMERS",
        "userCount": 12000,
        "friendCount": 11540,
        "status":"COMPLETED",
        "createdAt":"2026-04-09 15:10:00",
        "modifiedAt":"2026-04-09 15:12:25"
      }
    }
  }
}

친구 그룹 목록 조회

GET/api/comm/v1/center/brandmessage/friendGroup/list

샌드박스로 테스트하기

발신프로필 기준으로 등록된 친구 그룹 목록을 조회합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

친구 그룹 목록 응답 데이터입니다.

friendGroups

Object Array

친구 그룹 목록입니다.

status

String

친구 그룹 처리 상태입니다.

createdAt

String

생성 일시입니다.

modifiedAt

String

수정 일시입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/list?senderKey={senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "friendGroups": [{
        "friendGroupKey":"VIP_CUSTOMERS",
        "userCount": 12000,
        "friendCount": 11540,
        "status":"COMPLETED",
        "createdAt":"2026-04-09 15:10:00",
        "modifiedAt":"2026-04-09 15:12:25"
      }]
    }
  }
}

친구 그룹 삭제

DELETE/api/comm/v1/center/brandmessage/friendGroup/senderKey/{senderKey}/friendGroupKey/{friendGroupKey}

샌드박스로 테스트하기

발신프로필 키와 친구 그룹 키를 기준으로 친구 그룹을 삭제합니다.

Path Parameters

senderKey

필수String

발신프로필 키입니다.

friendGroupKey

필수String

삭제할 친구 그룹 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/senderKey/{senderKey}/friendGroupKey/{friendGroupKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

친구 그룹 내 전화번호 추가

POST/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/update

샌드박스로 테스트하기

기존 친구 그룹에 전화번호 목록을 추가합니다. fileKey 또는 phoneNumbers를 이용해 입력할 수 있습니다.

Body Parameters

{} JSON

friendGroup

필수Object

친구 그룹 정보입니다.

friendGroupKey

필수String

친구 그룹 키입니다.

phoneNumbers

String Array

전화번호 목록입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

친구 그룹 응답 데이터입니다.

friendGroup

Object

친구 그룹 정보입니다.

status

String

친구 그룹 처리 상태입니다.

createdAt

String

생성 일시입니다.

modifiedAt

String

수정 일시입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/update" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "friendGroup": {
      "senderKey": "{senderKey}",
      "friendGroupKey": "VIP_CUSTOMERS",
      "phoneNumbers": [
        "01000000002",
        "01000000003"
      ]
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "friendGroup": {
        "friendGroupKey":"VIP_CUSTOMERS",
        "requestId": 1203982,
        "status":"IN_PROGRESS",
        "createdAt":"2026-04-09 15:15:00",
        "modifiedAt":"2026-04-09 15:15:00"
      }
    }
  }
}

친구 그룹 내 전화번호 삭제

POST/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/delete

샌드박스로 테스트하기

기존 친구 그룹에서 전화번호 목록을 삭제합니다. fileKey 또는 phoneNumbers를 이용해 입력할 수 있습니다.

Body Parameters

{} JSON

friendGroup

필수Object

친구 그룹 정보입니다.

friendGroupKey

필수String

친구 그룹 키입니다.

phoneNumbers

String Array

전화번호 목록입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

친구 그룹 응답 데이터입니다.

friendGroup

Object

친구 그룹 정보입니다.

status

String

친구 그룹 처리 상태입니다.

createdAt

String

생성 일시입니다.

modifiedAt

String

수정 일시입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/delete" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "friendGroup": {
      "senderKey": "{senderKey}",
      "friendGroupKey": "VIP_CUSTOMERS",
      "phoneNumbers": [
        "01000000003"
      ]
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "friendGroup": {
        "friendGroupKey":"VIP_CUSTOMERS",
        "requestId": 1203983,
        "status":"IN_PROGRESS",
        "createdAt":"2026-04-09 15:18:00",
        "modifiedAt":"2026-04-09 15:18:00"
      }
    }
  }
}

광고성 정보 수신동의 관리

광고성 브랜드메시지 발송에 필요한 수신동의 증적자료를 발신프로필 기준으로 업로드합니다.

증적자료 파일 업로드

POST/api/comm/v1/center/brandmessage/marketingAgree

샌드박스로 테스트하기

광고성 정보 수신동의를 입증하는 증적자료 파일을 업로드합니다. 업로드된 파일은 발신프로필 기준으로 관리되며, 응답으로 받은 파일 키와 URL로 등록 결과를 확인할 수 있습니다.

Body Parameters

FORM-DATA

senderKey

필수String

발신프로필 키입니다. max: 40

file

필수Binary

업로드할 증적자료 파일입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

업로드 결과 데이터입니다.

marketingAgree

Object

업로드된 증적자료 정보입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/marketingAgree" \
  -H "Authorization: {ApiKey}" \
  -F "senderKey={senderKey}" \
  -F "file=@/path/marketing-agree.pdf"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "marketingAgree": {
        "fileKey":"{fileKey}",
        "fileUrl":"https://mud-kage.kakao.com/.../marketing-agree.pdf"
      }
    }
  }
}

무료수신거부 관리

브랜드메시지 광고성 안내에 필요한 무료수신거부 정보를 발신프로필 기준으로 관리합니다.

발신프로필 무료수신거부 정보 입력

POST/api/comm/v1/center/brandmessage/unSubscribeContent

샌드박스로 테스트하기

발신프로필의 무료수신거부 전화번호와 인증번호를 등록합니다. 광고성 메시지 하단의 무료수신거부 안내에 사용할 수 있습니다.

Body Parameters

{} JSON

brandmessage

필수Object

무료수신거부 정보입니다.

unsubscribePhoneNumber

필수String

무료수신거부 전화번호입니다.

unsubscribeAuthNumber

String

무료수신거부 인증번호입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/unSubscribeContent" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "brandmessage": {
      "senderKey": "{senderKey}",
      "unsubscribePhoneNumber": "080-1234-1234",
      "unsubscribeAuthNumber": "12345"
    }
  }'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}