브랜드메시지 발송

카카오 브랜드메시지를 발송합니다. 승인된 브랜드 템플릿으로 보내는 template 모드와, 본문을 직접 보내는 free(자유형) 모드를 지원합니다.

POST /v1/messages/brand

사업자 회원 전용이며, 브랜드메시지를 사용할 수 있도록 등록된 발신프로필이 필요합니다. 발신프로필·템플릿은 웹사이트에서 등록·검수합니다.

요청 본문

필드	타입	설명
`profile` 필수	string	브랜드메시지 가능 발신프로필 키
`mode`	string	`template`(기본) 또는 `free`
`template_code`	string	`mode=template` 일 때 필수. 승인된 브랜드 템플릿 코드
`text`	string	`mode=free` 일 때 필수. 본문 (1,300자 이하, TEXT 유형)
`recipients` / `to` 택1	object[] / string[]	수신자 (최대 1,000명). `recipients[].variables` 로 수신자별 변수를 지정
`variables`	object	공통 변수 (수신자별 값이 우선)
`target`	string	발송 대상. `friend`(채널 친구, 기본) / `marketing`(광고 수신동의 회원 — 사전 발송 권한 신청 필요)
`targeting`	string	`target=marketing` 일 때 필수. `M`(수신동의 회원 전체) / `N`(수신동의 − 채널 친구) / `O`(수신동의 ∩ 채널 친구)
`unsubscribe_phone`	string	080 무료수신거부 번호. 생략 시 발신프로필 기본값
`unsubscribe_auth`	string	080 인증번호 (선택)
`group_tag_key`	string	그룹 태그 키 (선택)
`push_alarm`	boolean	푸시 알림 여부 (기본 `true`)
`adult`	boolean	성인용 여부 (자유형, 기본 `false`)
`send_at`, `name`, `exclude_optout`, `client_ref`, `dry_run`		알림톡과 동일

예시

템플릿 발송

curl

curl -X POST https://api-01.redbean8.io.kr/v1/messages/brand \
  -H "Authorization: Bearer $REDBEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-event-1107" \
  -d '{
    "profile": "2f81c0b7e4d9…",
    "mode": "template",
    "template_code": "EVENT_NOV",
    "recipients": [
      { "to": "01011112222", "variables": { "name": "홍길동" }, "ref": "U-1" }
    ],
    "client_ref": "brand-event-1107"
  }'

자유형 (마케팅 대상)

JSON

{
  "profile": "2f81c0b7e4d9…",
  "mode": "free",
  "text": "(광고) 11월 한정 쿠폰이 도착했습니다.",
  "target": "marketing",
  "targeting": "O",
  "unsubscribe_phone": "0801234567",
  "to": ["01011112222"]
}

응답

202 Accepted — 형식은 SMS 발송 응답과 같으며 channel 이 brand 입니다.

주의사항

브랜드메시지는 예약 취소가 불가합니다. (카카오/비즈뿌리오 정책) 취소 요청 시 422 CANCEL_NOT_ALLOWED.
mode, target, targeting 값이 허용 목록에 없으면 기본값으로 바꾸지 않고 422 INVALID_REQUEST 로 알려 드립니다.
마케팅 대상(M/N/O) 발송은 서비스 설정(VAS 코드)이 필요합니다. 설정이 없으면 503 PROVIDER_CONFIG_ERROR — 고객센터로 문의하세요.
변수는 모두 채워야 합니다. 누락 시 422 TEMPLATE_VARIABLE_MISSING.
브랜드메시지가 실패해도 문자로 대체 발송하지 않습니다. 실패 건은 FAILED 로 종료되고 요금은 환불됩니다.

오류

HTTP	code	원인
403	`BUSINESS_MEMBER_REQUIRED`	사업자 회원이 아님
422	`PROFILE_NOT_FOUND`	발신프로필 없음/비활성
422	`PROFILE_NOT_USABLE`	차단 또는 휴면 상태
422	`BRAND_NOT_ENABLED`	브랜드메시지를 쓸 수 없는 발신프로필
422	`TEMPLATE_NOT_FOUND`	브랜드 템플릿 코드 오류/미승인
422	`TEMPLATE_VARIABLE_MISSING`	필수 변수 누락