BIZAPIv3.11.1

비즈뿌리오 메시지 API (BIZAPI)

공통 사항

메시지 API (BIZAPI) — 모든 발송 API 호출에 공통으로 적용되는 사양.

연동 규격

항목 값
프로토콜 HTTPS (443)
도메인 (운영) https://api.bizppurio.com
도메인 (검수) https://dev-api.bizppurio.com
메서드 POST
인코딩 UTF-8
Content-Type application/json; charset=utf-8
인증 Bearer 토큰 (Authorization: Bearer {accessToken})
HTTP Keep-Alive Timeout 4초 이하

WARNING: Keep-Alive Timeout 이 4초를 초과하면 서버가 연결을 종료하여 일부 요청이 실패하거나 재시도가 필요할 수 있습니다.

인증 흐름

고객사비즈뿌리오 서버(api.bizppurio.com)① POST /v1/token — Basic Auth: account + apiKey② accessToken + expired (24h)③ 후속 호출 — Authorization: Bearer {accessToken}만료 직전 재발급 — 만료된 토큰은 인증 오류

자세한 토큰 발급은 인증 API 를 참고하세요.

공통 응답 형식

{
  "code": 1000,
  "description": "Success",
  "refkey": "test1234",
  "messagekey": "190922175225820#ft002951seXXXXXX"
}
필드 설명
code 결과 코드 (1000 = 성공, 그 외 전송 결과 코드 참고)
description 결과 메시지
refkey 요청 시 보낸 고객사 키 (echo)
messagekey 비즈뿌리오 발급 메시지 키 (결과 조회·중복 검사용)

Rate Limit

특정 시간 내 호출 가능한 API 요청 횟수 제한입니다. 제한값을 초과하면 HTTP 429 가 반환됩니다.

  • 모든 API 요청 횟수가 카운트됩니다 (토큰 발급 / 메시지 발송 / 리포트 요청 등)
  • 재시도 로직이 있는 경우 재시도 간격을 충분히 늘려야 합니다
  • 제한 값 상향은 고객센터 문의

응답 헤더:

헤더 설명
RateLimit-Limit 기준 시간 내 최대 요청 가능 횟수
RateLimit-Remaining 기준 시간 내 남은 요청 가능 횟수
RateLimit-Reset 기준 시간 갱신까지 남은 시간 (ms)

초과 시 응답 예시:

HTTP/1.1 429 Too Many Requests
Content-type: application/json
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 0.299

{
  "code": 5002,
  "description": "too many requests",
  "refkey": "test1234"
}

Quickstart BIZAPI

비즈뿌리오 API로 SMS 1건을 보내는 가장 짧은 경로입니다.

사전 조건

  • 비즈뿌리오 운영 또는 검수 계정 (계정ID·암호)
  • 등록된 발신번호 1개
  • 본인 휴대폰 번호 (수신 테스트용)

준비가 안 됐다면 사전 준비부터 진행하세요.

1. 환경 변수 세팅

# 검수 환경
export BP_HOST="dev-api.bizppurio.com"
# 운영 환경에서는 export BP_HOST="api.bizppurio.com"

export BP_ACCOUNT="bizUserId001"
export BP_PASSWORD="mypassword"
export BP_FROM="07000000000"      # 등록된 발신번호
export BP_TO="01012345678"        # 수신 테스트 번호

2. 인증 토큰 발급

AUTH=$(printf '%s' "$BP_ACCOUNT:$BP_PASSWORD" | base64)

ACCESS_TOKEN=$(curl -s -X POST "https://$BP_HOST/v1/token" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-type: application/json; charset=utf-8" \
  | python -c "import sys, json; print(json.load(sys.stdin)['accesstoken'])")

echo "$ACCESS_TOKEN"

응답 예시:

{
  "accesstoken": "eyJ0eXAiOiJKV1QiLC...",
  "type": "Bearer",
  "expired": "20260429185520"
}

NOTE: 토큰은 24시간 유효합니다. 매 요청마다 발급하지 말고 캐싱해서 사용하세요.

3. SMS 메시지 전송

curl -X POST "https://$BP_HOST/v3/message" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "account": "'"$BP_ACCOUNT"'",
    "refkey": "test-'"$(date +%s)"'",
    "type": "sms",
    "from": "'"$BP_FROM"'",
    "to": "'"$BP_TO"'",
    "content": {
      "sms": {
        "message": "비즈뿌리오 API Quickstart 테스트입니다."
      }
    }
  }'

성공 응답 예시:

{
  "code": 1000,
  "description": "Success",
  "refkey": "test-1735459200",
  "messagekey": "260429185700123#sms027420XXXXXXXX"
}

code: 1000이면 비즈뿌리오 서버가 메시지를 정상 접수한 것입니다. 잠시 후 등록한 수신번호로 SMS가 도착합니다.

WARNING: code가 1000이 아니면 BIZAPI 응답 상태 코드를 참고해 원인을 확인하세요. 자주 마주치는 케이스: 3001(Basic 인증 실패), 3010(IP 화이트리스트 미등록), 2000(페이로드 오류).

4. 발송 결과 확인

발송 결과는 두 가지 방식으로 받을 수 있습니다.

Webhook (권장)

비즈뿌리오에 사전 등록한 URL로 결과가 자동 PUSH됩니다.

{
  "DEVICE": "SMS",
  "CMSGID": "260429185700123#sms027420XXXXXXXX",
  "MSGID": "0429se_SL46760273836XXXXXXXX",
  "PHONE": "01012345678",
  "MEDIA": "SMS",
  "UNIXTIME": "1735459200",
  "RESULT": "4100",
  "REFKEY": "test-1735459200"
}

RESULT: 4100이면 단말기 전달 성공입니다. 자세한 키와 코드는 Webhook·발송 결과 코드 참고.

결과 재요청 (Webhook 누락 시)

curl -X POST "https://$BP_HOST/v2/report" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "account": "'"$BP_ACCOUNT"'",
    "messagekey": "260429185700123#sms027420XXXXXXXX"
  }'

다음 단계

하고 싶은 것 진행
LMS / MMS / 알림톡·브랜드메시지·RCS·NTALK 발송 메시지 채널 카탈로그
발송 실패 시 다른 채널로 자동 전환 대체 발송
대량 발송 / Rate Limit 다루기 Rate Limit 가이드
MMS에 이미지 첨부 MMS 파일 업로드
Polling 방식 결과 수신 전송 결과 조회

트러블슈팅

증상 원인·해결
3001 Basic Base64 인코딩 확인 (계정:암호 형식)
3010 비즈뿌리오에 접속 IP 등록
2000 페이로드 형식 오류 — content.sms.message 구조 확인
5002 (HTTP 429) Rate Limit 초과 — RateLimit-Reset 헤더 참고 후 백오프
code: 1000인데 SMS 미수신 결과는 RESULT 코드 확인 — 4100=성공, 4400~=음영지역, 4430=스팸 등

자세한 가이드는 API errors와 발송 결과 코드를 참고하세요.

인증

액세스 토큰 발급

post/v1/token

인증 토큰 발급

비즈뿌리오 계정과 암호를 Basic 인증 방식으로 전송하여 액세스 토큰을 발급받습니다.

  • Authorization 값은 계정:암호 문자열을 콜론으로 연결한 뒤 Base64 인코딩
  • 토큰 유효 시간 24시간 — 만료 후 재발급 필요
  • 토큰을 캐싱하여 매 요청마다 재발급하지 않도록 운영
echo -n "bizUserId001:mypassword" | base64
# bXlhY2NvdW50Om15cGFzc3dvcmQ=
cURL
curl -X POST "{baseUrl}/v1/token" \
  -H "Authorization: Basic {base64(account:password)}"
응답
200토큰 발급 성공
파라미터타입필수설명
accesstokenstring필수
인증 토큰 (이후 모든 API 호출의 Authorization 헤더에 사용)
typestring필수
항상 "Bearer"
= Bearer
expiredstring필수
토큰 만료 시간 (yyyyMMddHHmmss)
응답 · 200
{
  "accesstoken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "type": "Bearer",
  "expired": "20201110185520"
}
400인증 실패. 주요 코드: - `3001` Basic 인증 정보가 유효하지 않음 - `3006` 계정이 존재하지 않음 - `3007` 계정 암호가 유효하지 않음 - `3009` 계정 중지 상태 - `3010` 등록된 접속 허용 IP와 불일치
파라미터타입필수설명
codeinteger필수
비즈뿌리오 결과 코드
descriptionstring필수—
refkeystring(32)—
요청 시 전달한 고객사 키 (가능한 경우)
응답 · 400
{
  "code": 0,
  "description": "string",
  "refkey": "string"
}

메시지 전송

모든 채널 공통 발송 엔드포인트 (/v3/message). 채널별 페이로드는 content.oneOf 안에 모두 정의되어 있으며 본 페이지에서 펼쳐 확인할 수 있습니다.

post/v3/message

메시지 전송

모든 채널의 메시지 전송에 사용하는 단일 엔드포인트입니다.
채널은 type 필드로 구분되며, content 객체는 type에 매칭되는 채널 키 하나만 포함합니다.

sendtime 동작 규칙

  • 비즈뿌리오 서버 시간 기준, 한국 표준시(GMT+9)
  • 과거 시간 입력 시 즉시 발송
  • 즉시 발송을 원하는 경우 미입력
  • 네이버 톡톡은 예약 불가 (sendtime에 관계없이 즉시 발송)
  • 브랜드메시지는 예약 취소 불가

RESEND — 대체 전송

같은 메신저(카카오톡)끼리는 대체 불가. 2차 대체는 1차가 rich 채널(RCS/AT/AI/BT)일 때만 가능합니다.

본발송 1차 대체 2차 대체
문자(sms/lms/mms) — —
알림톡(at/ai) 문자(SMS/LMS/MMS) 또는 RCS (1차 RCS) 문자(SMS/LMS/MMS)
브랜드메시지(ut~ua) 문자(SMS/LMS/MMS) 또는 RCS (1차 RCS) 문자(SMS/LMS/MMS)
RCS 문자(SMS/LMS/MMS) 또는 카카오(알림톡/브랜드메시지) (1차 카카오) 문자(SMS/LMS/MMS)
네이버 톡톡(ntalk) — —
cURL
curl -X POST "{baseUrl}/v3/message" \
  -H "Authorization: Bearer {accessToken}"
응답
200요청 접수 성공
파라미터타입필수설명
codeinteger필수
결과 코드 (1000 = 성공)
descriptionstring필수—
messagekeystring(32)필수
비즈뿌리오 메시지 키 — 고객 문의 및 리포트 재요청 기준
refkeystring(32)필수
요청 시 전달한 고객사 키
응답 · 200
{
  "code": 1000,
  "description": "Success",
  "messagekey": "190922175225820#ft002951seXXXXXX",
  "refkey": "test1234"
}
400요청 실패. 주요 응답 코드: - `2000` 메시지가 유효하지 않음 - `3000~3013` 인증/계정 관련 오류 - `3014` 데이터 포맷 에러
파라미터타입필수설명
codeinteger필수
비즈뿌리오 결과 코드
descriptionstring필수—
refkeystring(32)—
요청 시 전달한 고객사 키 (가능한 경우)
응답 · 400
{
  "code": 2000,
  "description": "invalid message",
  "refkey": "test1234"
}
429Rate Limit 초과 (`code: 5002`). `RateLimit-Reset` 헤더 참고하여 백오프 후 재시도.
파라미터타입필수설명
codeinteger필수
비즈뿌리오 결과 코드
descriptionstring필수—
refkeystring(32)—
요청 시 전달한 고객사 키 (가능한 경우)
응답 · 429
{
  "code": 5002,
  "description": "too many requests",
  "refkey": "test1234"
}
post/v3/messagetype=sms

SMS

실제 HTTP endpoint: POST /v3/message — type: sms SMS 페이로드만 보여주는 채널별 문서 페이지입니다.
통합 endpoint 와 공통 설명은 POST /v3/message 를 참고하세요.

요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
typestring필수

메시지 데이터 타입. 채널 식별자로 사용되며, content 객체는 이 값과 매칭되는 키 하나만 포함합니다.

= sms
fromstring(16)필수
발신 번호
tostring(16)필수
수신 번호
refkeystring(32)필수
고객사에서 부여한 키 (UTF-8 기준 최대 32바이트)
countrystring(5)—
국가 코드 (국제 메시지 발송 시)
userinfostring(50)—
정산용 부서 코드
resellercodestring—
특부가사업자 식별코드 (9자리 숫자)
sendtimestring—
예약 발송 시각 (unixtime, GMT+9 기준, 최대 30일 이내)
contentobject필수
SMS 페이로드 (type: sms)
└smsobject필수—
└messagestring필수
본문 (EUC-KR 기준 최대 90바이트)
curl -X POST "{baseUrl}/v3/message" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "sms",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "sms": {
      "message": "SMS 전송"
    }
  }
}'
post/v3/messagetype=lms

LMS

실제 HTTP endpoint: POST /v3/message — type: lms LMS 페이로드만 보여주는 채널별 문서 페이지입니다.
통합 endpoint 와 공통 설명은 POST /v3/message 를 참고하세요.

요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
typestring필수

메시지 데이터 타입. 채널 식별자로 사용되며, content 객체는 이 값과 매칭되는 키 하나만 포함합니다.

= lms
fromstring(16)필수
발신 번호
tostring(16)필수
수신 번호
refkeystring(32)필수
고객사에서 부여한 키 (UTF-8 기준 최대 32바이트)
countrystring(5)—
국가 코드 (국제 메시지 발송 시)
userinfostring(50)—
정산용 부서 코드
resellercodestring—
특부가사업자 식별코드 (9자리 숫자)
sendtimestring—
예약 발송 시각 (unixtime, GMT+9 기준, 최대 30일 이내)
contentobject필수
LMS 페이로드 (type: lms)
└lmsobject필수—
└subjectstring—
제목 (EUC-KR 기준 최대 64바이트)
└messagestring필수
본문 (EUC-KR 기준 최대 2000바이트)
curl -X POST "{baseUrl}/v3/message" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "lms",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "lms": {
      "subject": "제목",
      "message": "LMS 전송"
    }
  }
}'
post/v3/messagetype=mms

MMS

실제 HTTP endpoint: POST /v3/message — type: mms MMS 페이로드만 보여주는 채널별 문서 페이지입니다.
통합 endpoint 와 공통 설명은 POST /v3/message 를 참고하세요.

요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
typestring필수

메시지 데이터 타입. 채널 식별자로 사용되며, content 객체는 이 값과 매칭되는 키 하나만 포함합니다.

= mms
fromstring(16)필수
발신 번호
tostring(16)필수
수신 번호
refkeystring(32)필수
고객사에서 부여한 키 (UTF-8 기준 최대 32바이트)
countrystring(5)—
국가 코드 (국제 메시지 발송 시)
userinfostring(50)—
정산용 부서 코드
resellercodestring—
특부가사업자 식별코드 (9자리 숫자)
sendtimestring—
예약 발송 시각 (unixtime, GMT+9 기준, 최대 30일 이내)
contentobject필수

MMS 페이로드 (type: mms) — LMS + 이미지 첨부 (최대 3개). 본문은 선택 (이미지만 발송 가능).
이미지는 POST /v2/file로 사전 업로드한 후 받은 filekey를 file[].key에 사용.

└mmsobject필수—
└subjectstring—
제목 (EUC-KR 기준 최대 64바이트)
└messagestring—
본문 (EUC-KR 기준 최대 2000바이트, 선택)
└filearray<object>(~3)필수
첨부파일 배열 (최대 3개)
└typestring필수
파일 유형 (현재 IMG만 지원)
= IMG
└keystring(40)필수
파일 키 (/v2/file 응답의 filekey)
curl -X POST "{baseUrl}/v3/message" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "mms",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "mms": {
      "subject": "제목",
      "message": "MMS 전송",
      "file": [
        {
          "type": "IMG",
          "key": "1585011852_DD7482861185100000001.jpg"
        }
      ]
    }
  }
}'
post/v3/messagetype=rcs

RCS

실제 HTTP endpoint: POST /v3/message — type: rcs RCS 페이로드만 보여주는 채널별 문서 페이지입니다.
통합 endpoint 와 공통 설명은 POST /v3/message 를 참고하세요.

RCS는 이통 3사의 리치 메시징 채널입니다. 안드로이드 RCS(채팅+ 지원 단말)와 통합 RCS(이통 3사 표준 규격) 모두 type: rcs 하나로 발송하며, messagebaseid 값으로 메시지 유형이 결정됩니다.

사전 준비: ① RCS 브랜드 개설·대행사 설정 (RCS 비즈센터) → ② RCS 브랜드 등록 (비즈뿌리오) → ③ 발신번호·템플릿 등록/승인

RCS의 상세 규격 — MESSAGEBASE ID 유형별 표(안드로이드 RCS / 통합 RCS), 슬라이드형 글자수·라인수 정의, 이미지·동영상 첨부(media) 규격, 버튼 Action 7종 규격 — 은 RCS 연동 규격을 참고하세요. 아래 요청 본문 스키마에서 각 필드의 레벨별 정의와 예시를 확인할 수 있습니다.

요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
typestring필수

메시지 데이터 타입. 채널 식별자로 사용되며, content 객체는 이 값과 매칭되는 키 하나만 포함합니다.

= rcs
fromstring(16)필수
발신 번호
tostring(16)필수
수신 번호
refkeystring(32)필수
고객사에서 부여한 키 (UTF-8 기준 최대 32바이트)
countrystring(5)—
국가 코드 (국제 메시지 발송 시)
userinfostring(50)—
정산용 부서 코드
resellercodestring—
특부가사업자 식별코드 (9자리 숫자)
sendtimestring—
예약 발송 시각 (unixtime, GMT+9 기준, 최대 30일 이내)
contentobject필수

RCS 페이로드 (type: rcs) — 안드로이드 RCS / 통합 RCS 모두 지원.
MESSAGEBASE ID 유형별 표·안드로이드 vs 통합 차이는 RCS 발송 페이지 를 참고하세요.

└rcsobject필수—
└messagebaseidstring(40)필수
메시지 베이스 ID (MESSAGEBASE ID — 유형별 표는 RCS 발송 페이지 참고)
└chatbotidstring(40)필수
RCS 비즈센터에서 생성한 챗봇 ID
└brandkeystring(64)—
브랜드별 제공되는 특수 키 (2023.08.01 이후 잘못된 값은 실패)
└headerstring(1)필수
메시지 상단 식별 문구. 0=Web 발신 / 1=광고. 통합 RCS는 0만 허용
= 0 | 1
└footerstring(64)—
하단 수신거부 문구 (안드로이드 RCS 전용)
└copyallowedstring(1)—
복사/공유 메뉴 표시 (안드로이드 RCS 전용, 기본 N)
= Y | N
└agencyidstring(20)—
대행사 ID (기본: daoutech)
└agencykeystring(64)—
대행사 Key (2차 대행사인 경우 필수)
└groupidstring(20)—
캠페인 그룹 ID (통계용)
└messageobject—
메시지 베이스에서 치환할 본문 객체 (messagebaseid에 따라 필드 구성·media 값 상이) — RCS 연동 규격 — MESSAGE 참조
└buttonarray<object>—
버튼 배열 (캐러셀은 카드별로 객체, 빈 카드는 {}로 순서 유지)
└suggestionsarray<object>—
제안(suggestion) 배열
└actionobject필수
RCS Action — 7종 중 정확히 1개만 포함. 타입별 필드는 RCS 연동 규격 — BUTTON 참조
└displayTextstring필수
버튼에 출력될 텍스트
└postbackobject—
챗봇 콜백 데이터
└datastring——
resendobject—
대체 발송 설정 (본 발송 실패 시 다른 채널로 자동 전환). 채널 조합·규격은 대체 발송 참조
recontentobject—
대체 채널별 본문 (resend와 짝) — 대체 발송 참조
curl -X POST "{baseUrl}/v3/message" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "rcs",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "rcs": {
      "messagebaseid": "RPLSAXX001",
      "chatbotid": "15880000",
      "header": "0",
      "message": {
        "title": "줄바꿈 없는 14자 권장",
        "description": "(광고)\n안녕하세요! RCS LMS\n무료 수신 거부 080-1234-5678\n"
      },
      "button": [
        {
          "suggestions": [
            {
              "action": {
                "urlAction": {
                  "openUrl": {
                    "url": "https://www.bizppurio.com"
                  }
                }
              },
              "displayText": "비즈뿌리오로 이동"
            }
          ]
        }
      ]
    }
  }
}'
post/v3/messagetype=at

카카오 알림톡

실제 HTTP endpoint: POST /v3/message — type: at 알림톡 페이로드만 보여주는 채널별 문서 페이지입니다.
통합 endpoint 와 공통 설명은 POST /v3/message 를 참고하세요.

알림톡은 사전 등록·승인된 템플릿 기반으로 발송합니다. senderkey(발신 프로필 키)와 templatecode로 템플릿을 지정하고, message에는 변수 치환이 끝난 최종 본문을 입력합니다.

사전 준비 — 알림톡·브랜드메시지 공통: ① 카카오톡 채널 개설·비즈니스 채널 신청 (카카오 비즈니스) → ② 발신 프로필 키 생성 (비즈뿌리오) → ③ 템플릿 등록/승인

공통 입력 규칙

  • 템플릿에 포함된 구성 요소는 필수 입력 — 템플릿에 버튼(button)·바로연결(quickreply)·강조표기(title)가 등록돼 있으면 발송 요청에도 해당 필드를 반드시 전달합니다.
  • 본문은 이모지를 포함한 UTF-8 범위 내 문자열 사용 가능합니다 (카카오·RCS·네이버 톡톡 공통).

구성 요소와 한도

필드 한도 비고
message 한글/영문 1,300자 필수 — 변수 치환 후 최종 본문
title 50자 강조표기형 — 본문 중 강조할 핵심 정보
header 16자 아이템리스트형 헤더
item list: title 6자 · description 23자 아이템리스트. summary는 title 6자 · 가격정보 14자 (통화기호·통화코드·숫자만)
itemhighlight title 30자 · description 19자 이미지 동반 시 21자 / 13자. title 끝에 \s 플래그 포함 시 취소선 적용
button 최대 5개 14종 — 타입별 필수 파라미터는 알림톡 버튼 표
quickreply 최대 10개 6종 — 알림톡 바로연결 표
link — 대표 링크 (URL·앱 스킴)

광고성 메시지가 필요하다면 브랜드메시지(UT 등 8종)를 사용하세요. 같은 발신프로필을 사용하지만 발송 조건·버튼 타입이 다릅니다 — 브랜드메시지 선택 가이드 참고.

이미지 알림톡: 알림톡 템플릿이 이미지 강조 유형이면 동일 페이로드에 type: ai 로 발송합니다.

요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
typestring필수

메시지 데이터 타입. 채널 식별자로 사용되며, content 객체는 이 값과 매칭되는 키 하나만 포함합니다.

= at
fromstring(16)필수
발신 번호
tostring(16)필수
수신 번호
refkeystring(32)필수
고객사에서 부여한 키 (UTF-8 기준 최대 32바이트)
countrystring(5)—
국가 코드 (국제 메시지 발송 시)
userinfostring(50)—
정산용 부서 코드
resellercodestring—
특부가사업자 식별코드 (9자리 숫자)
sendtimestring—
예약 발송 시각 (unixtime, GMT+9 기준, 최대 30일 이내)
contentobject필수
카카오 알림톡 페이로드 (type: at)
└atobject필수

페이로드 키는 type 값과 일치해야 합니다 — 알림톡은 at.
이미지 강조형은 type: ai 로 발송하며 키도 ai 를 사용합니다(하위 구조는 아래와 동일).

└senderkeystring(40)필수
발신 프로필 키
└templatecodestring(32)필수
템플릿 코드
└messagestring(1300)필수
본문 (한글/영문 최대 1300자, 변수 치환 후)
└buttonarray<object>(~5)—
버튼 (최대 5개, 템플릿 포함 시 필수) — 타입·필드 규격은 카카오 연동 규격 — 알림톡 버튼 참조
└namestring(28)필수
버튼 제목 (AC 타입은 '채널 추가' 고정)
└typestring필수
버튼 타입 — 타입별 사용 가능/필수 파라미터는 카카오 연동 규격 의 "알림톡 버튼" 표 참조
= WL | AL | DS | BK | MD | BC | BT | AC | P1 | P2 | P3 | BF | TN | MP
└url_pcstring—
PC 환경 이동 URL
└url_mobilestring—
Mobile 환경 이동 URL (WL 필수)
└scheme_iosstring—
iOS 앱 Custom Scheme
└scheme_androidstring—
Android 앱 Custom Scheme
└chat_extrastring(50)—
상담톡/봇 전환 시 메타정보
└chat_eventstring(50)—
봇 전환 시 이벤트명
└plugin_idstring(24)—
플러그인 ID
└relay_idstring—
플러그인 실행 시 X-Kakao-Plugin-Relay-Id 헤더 전달 값
└oneclick_idstring—
원클릭 결제 ID
└product_idstring—
원클릭 결제 상품 ID
└tel_numberstring(14)—
전화번호 (TN 전용, 하이픈 포함)
└biz_form_idinteger—
비즈니스폼 ID (BF 전용)
└map_addressstring—
지도보기 주소 (MP 전용)
└map_coordinatesstring—
지도보기 위경도 좌표 (MP 전용, map_address 우선)
└quickreplyarray<object>(~10)—
바로연결 (최대 10개, 템플릿 포함 시 필수) — 타입·필드 규격은 카카오 연동 규격 — 알림톡 바로연결 참조
└namestring(14)필수
바로연결 텍스트
└typestring필수
바로연결 타입 (WL·AL·BK·BC·BT·BF 6종) — 타입별 사용 가능/필수 파라미터는 카카오 연동 규격 의 "알림톡 바로연결" 표 참조
= WL | AL | BK | BC | BT | BF
└url_pcstring——
└url_mobilestring——
└scheme_iosstring——
└scheme_androidstring——
└chat_extrastring(50)——
└chat_eventstring(50)——
└titlestring(50)—
강조 표기할 핵심 정보
└headerstring(16)—
아이템리스트 헤더
└itemobject—
알림톡 아이템리스트와 아이템 요약정보
└listarray<object>필수
아이템 리스트
└titlestring(6)필수
타이틀
└descriptionstring(23)필수
부가정보
└summaryobject—
아이템 요약 정보
└titlestring(6)필수
타이틀
└descriptionstring(14)필수
가격정보 (통화기호/ISO4217/숫자/콤마/소수점 2자리)
└itemhighlightobject—
아이템 하이라이트
└titlestring(30)필수
타이틀 (이미지 동반 시 21자, 내용 끝 \s 플래그 시 취소선)
└descriptionstring(19)필수
부가정보 (이미지 동반 시 13자)
└linkobject—
대표 링크
└url_mobilestring—
Mobile 환경 이동 URL
└url_pcstring—
PC 환경 이동 URL
└scheme_androidstring—
Android 앱 Custom Scheme
└scheme_iosstring—
iOS 앱 Custom Scheme
resendobject—
대체 발송 설정 (본 발송 실패 시 다른 채널로 자동 전환). 채널 조합·규격은 대체 발송 참조
recontentobject—
대체 채널별 본문 (resend와 짝) — 대체 발송 참조
curl -X POST "{baseUrl}/v3/message" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "at",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "at": {
      "senderkey": "abc123XXXXX",
      "templatecode": "tempXXXX",
      "message": "알림톡 + 버튼(WL)",
      "button": [
        {
          "name": "웹 링크 버튼",
          "type": "WL",
          "url_mobile": "https://www.daou.com"
        }
      ]
    }
  }
}'
post/v3/messagetype=ut

카카오 브랜드메시지

실제 HTTP endpoint: POST /v3/message — 카카오 브랜드메시지 8종(UT/UI/UW/UL/UC/UM/UP/UA)을 하나로 안내하는 문서 페이지입니다. type 값(ut~ua)으로 말풍선 형태를 지정하며, 아래 예시 뷰어에서 대상·방식·타입별 전체 64개 조합을 확인할 수 있습니다.
통합 endpoint 와 공통 설명은 POST /v3/message 를 참고하세요.

브랜드메시지는 고객사의 광고성 정보 수신 동의 회원 또는 카카오 채널 친구 대상으로 발송하는 광고성 메시지 상품입니다. 8종 타입(UT/UI/UW/UL/UC/UM/UP/UA)이 동일한 페이로드 구조를 사용합니다.

발송 대상·형태 결정 가이드(4-STEP)·타겟팅(M/N/O)·타입별 구성은 카카오 연동 규격 — 브랜드메시지 선택 가이드 를 참고하세요.

발송 조건 (8종 공통)

WARNING: 광고성 상품이므로 발송 가능 시간은 08:00～20:50 (한국 시간) 입니다. 해외 전화번호로 카카오톡에 가입한 사용자는 시간 제한이 없습니다.

  • 채널을 차단한 사용자에게는 발송되지 않습니다.
  • 고객사 회원 대상(sendtarget: marketing)은 사전 발송 권한 신청이 필요하고 targeting(M/N/O)이 필수이며, 카카오톡 25.4.0 이상 사용자에게만 발송됩니다.
  • 채널 친구 대상(sendtarget: friend)은 발신프로필 등록 후 바로 발송 가능하며 targeting을 사용하지 않습니다.
요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
typestring필수

메시지 데이터 타입. 채널 식별자로 사용되며, content 객체는 이 값과 매칭되는 키 하나만 포함합니다.

= ut
fromstring(16)필수
발신 번호
tostring(16)필수
수신 번호
refkeystring(32)필수
고객사에서 부여한 키 (UTF-8 기준 최대 32바이트)
countrystring(5)—
국가 코드 (국제 메시지 발송 시)
userinfostring(50)—
정산용 부서 코드
resellercodestring—
특부가사업자 식별코드 (9자리 숫자)
sendtimestring—
예약 발송 시각 (unixtime, GMT+9 기준, 최대 30일 이내)
contentobject필수

카카오 브랜드메시지 — TEXT (type: ut). 8종 타입(UT/UI/UW/UL/UC/UM/UP/UA)은 동일 구조(BrandPayload)를 공유합니다.
타입별 구성·본문 필드·타겟팅은 카카오 연동 규격 — 브랜드메시지 선택 가이드 를 참조하세요. 요청 예제 8종을 그대로 복사해 사용할 수 있습니다.

└utallOf필수

페이로드 키는 type 값과 일치해야 합니다 — 말풍선 형태에 따라
ut(TEXT)·ui(IMAGE)·uw(WIDE)·ul(WIDE_ITEM_LIST)·uc(CAROUSEL_FEED)·um(COMMERCE)·up(PREMIUM_VIDEO)·ua(CAROUSEL_COMMERCE).
8종 모두 아래 동일 구조를 사용합니다.

└senderkeystring(40)필수
발신 프로필 키
└brandmessagetypestring필수
브랜드메시지 타입 (BASIC=기본형 / FREE=자유형)
= BASIC | FREE
└sendtargetstring필수

발송 대상 타입:

  • marketing 고객사의 광고성 정보 수신동의 회원 대상 (targeting 필수)
  • friend 채널 친구 대상 (targeting 미사용)
= marketing | friend
└targetingstring—
sendtarget: marketing일 때 필수, friend일 때 미사용 (발송 권한 신청 필요). M/N/O 의미·타겟팅 상세는 카카오 연동 규격 — 브랜드메시지 타겟팅 참조
= M | N | O
└unsubscribephonenumberstring(13)—

sendtarget: marketing(고객사 회원 대상)일 때만 사용, friend(채널 친구 대상)에서는 미사용.
무료수신거부 전화번호. unsubscribephonenumber·unsubscribeauthnumber 둘 다 미입력 시
발신프로필에 등록된 무료수신거부 정보로 발송됩니다. (예: 080-1234-1234)

└unsubscribeauthnumberstring(10)—

sendtarget: marketing(고객사 회원 대상)일 때만 사용, friend(채널 친구 대상)에서는 미사용.
무료수신거부 인증번호. 둘 다 미입력 시 발신프로필 정보로 발송되며,
unsubscribephonenumber 없이 unsubscribeauthnumber만 입력은 불가합니다. (예: 1234)

└pushalarmstring(1)—
푸시 알람 여부 (기본 Y). N 입력 시 수신자 단말에 푸시 알람 없이 발송됩니다.
= Y | N
└adultstring(1)—
성인용 메시지 (기본 N)
= Y | N
└grouptagkeystring(40)—
그룹 태그 키 (통계용)
└변수 미사용object—
템플릿 그대로 발송. 변수·본문 필드를 사용하지 않습니다.
└brandmessagetypeconst—
= BASIC
└templatecodestring(64)—
템플릿 코드 (기본형 필수)
└변수 사용 (변수 분리 방식)object—
템플릿 변수를 영역별 변수 필드로 분리 전달합니다.
└brandmessagetypeconst—
= BASIC
└templatecodestring(64)—
템플릿 코드 (기본형 필수)
└messagevariableobject—

메시지 영역 변수 — 변수 분리 방식 (BASIC)에서 사용.
각 key 는 템플릿에 정의한 변수명(고객사가 직접 지정), 값은 그 변수에 치환할 문자열입니다.
TEXT/IMAGE/WIDE: 본문 / WIDE_ITEM_LIST: 헤더·타이틀·링크 / PREMIUM_VIDEO: 헤더·본문 / COMMERCE: 부가정보

└buttonvariableobject—

버튼 링크 변수. key 는 템플릿 버튼에 정의한 변수명, 값은 치환할 링크입니다.

└couponvariableobject—

쿠폰 링크 변수. key 는 템플릿 쿠폰에 정의한 변수명, 값은 치환할 값입니다.
값으로 "ESCAPE_COUPON" 전달 시 템플릿에 쿠폰이 있어도 말풍선에서 제외.

└imagevariablearray<string>—
이미지 변수 (IMAGE/WIDE 1개, WIDE_ITEM_LIST는 리스트 개수만큼). 미입력 시 템플릿 이미지 사용
└videovariableobject—
비디오 변수 (PREMIUM_VIDEO 전용)
└commercevariableobject—

커머스 변수 (COMMERCE 전용). key 는 변수명, 값은 치환할 값입니다.
가격 고정변수: 할인가격 · 정상가격 · 할인율 · 정액할인가격

└carouselvariablearray<object>—
캐러셀 변수 배열 (CAROUSEL_FEED/COMMERCE 전용). 인트로 변수는 배열 첫 번째에 위치. 변수 없는 캐러셀은 빈 객체 {}로 순서 유지
└messagevariableobject——
└buttonvariableobject——
└imagevariableobject——
└couponvariableobject——
└commercevariableobject——
└변수 사용 (전문 방식)object—
본문·버튼·첨부를 전문으로 직접 구성합니다.
└brandmessagetypeconst—
= BASIC
└templatecodestring(64)—
템플릿 코드 (기본형 필수)
└messagestring—

본문 — 전문 방식 / 자유형. 타입별 제한:

  • TEXT/IMAGE: 1300자 (줄바꿈 99개, URL 형식 입력 가능)
  • WIDE / PREMIUM_VIDEO: 76자 (5개)
  • UL/UC/UM/UA: 사용 안 함
└buttonarray<object>—

버튼. 타입별 개수 제한:

  • TEXT/IMAGE: 최대 5개 (쿠폰 적용 시 4개)
  • WIDE / WIDE_ITEM_LIST: 2개
  • PREMIUM_VIDEO: 1개
  • COMMERCE: 1~2개
└typestring필수
브랜드메시지 버튼 타입 — 타입별 사용 가능/필수 파라미터는 카카오 연동 규격 — 브랜드메시지 버튼 참조
= WL | AL | BK | MD | BC | BT | BF | AC
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└chat_extrastring—
상담톡/봇 전환 시 전달할 메타정보
└chat_eventstring—
봇 전환 시 연결할 봇 이벤트명
└biz_form_keyinteger—
비즈니스폼 키 (BF 전용)
└imageobject—
이미지 요소
└img_urlstring—
KAPI 이미지 업로드 API로 사전 등록한 이미지 URL
└img_linkstring(1000)—
이미지 클릭 시 이동 URL. 미설정 시 카카오톡 내 이미지 뷰어 사용
└headerstring(20)—
WIDE_ITEM_LIST 필수 / PREMIUM_VIDEO 선택 (최대 20자)
└itemobject—
와이드 아이템 리스트 (WIDE_ITEM_LIST/UL 전용, list 3~5개)
└listarray<object>(3~4)필수—
└titlestring—
아이템 제목 — 1번째 선택(최대 25자) / 2~5번째 필수(최대 30자), 줄바꿈 1개
└img_urlstring—
아이템 이미지 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└carouselobject—

캐러셀 (CAROUSEL_FEED/UC, CAROUSEL_COMMERCE/UA 필수). 3-레벨: head (인트로, UA만) / list[] / tail.

  • UC: list 2～6개
  • UA: 인트로 있으면 1～6, 없으면 2～6
└headobject—
캐러셀 인트로 (CAROUSEL_COMMERCE 전용)
└headerstring(20)—
인트로 헤더 (줄바꿈 불가)
└contentstring(50)—
인트로 내용 (줄바꿈 최대 2개)
└image_urlstring—
인트로 이미지 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└listarray<object>(1~6)——
└headerstring(20)—
캐러셀 리스트 헤더 (줄바꿈 불가)
└messagestring(180)—
캐러셀 리스트 내용 (줄바꿈 최대 10개)
└additional_contentstring(34)—
부가 정보 (줄바꿈 최대 1개)
└attachmentobject—
캐러셀 아이템 첨부 (버튼·이미지·쿠폰·커머스)
└buttonarray<object>——
└typestring필수
브랜드메시지 버튼 타입 — 타입별 사용 가능/필수 파라미터는 카카오 연동 규격 — 브랜드메시지 버튼 참조
= WL | AL | BK | MD | BC | BT | BF | AC
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└chat_extrastring—
상담톡/봇 전환 시 전달할 메타정보
└chat_eventstring—
봇 전환 시 연결할 봇 이벤트명
└biz_form_keyinteger—
비즈니스폼 키 (BF 전용)
└imageobject—
이미지 요소
└img_urlstring—
KAPI 이미지 업로드 API로 사전 등록한 이미지 URL
└img_linkstring(1000)—
이미지 클릭 시 이동 URL. 미설정 시 카카오톡 내 이미지 뷰어 사용
└couponobject—

쿠폰 요소. 링크 필수값 — 기본 쿠폰은 url_mobile 필수,
채널 쿠폰 URL(alimtalk=coupon://) 사용 시 scheme_android/scheme_ios 중 하나 필수.

└titlestring—

쿠폰 제목 — 5가지 형식만 허용:

  • ${숫자}원 할인 쿠폰 (1 ≤ 숫자 ≤ 99,999,999)
  • ${숫자}% 할인 쿠폰 (1 ≤ 숫자 ≤ 100)
  • 배송비 할인 쿠폰
  • ${7자 이내} 무료 쿠폰
  • ${7자 이내} UP 쿠폰
└descriptionstring—
쿠폰 설명. WIDE/WIDE_ITEM_LIST/PREMIUM_VIDEO: 최대 18자 / 그 외: 최대 12자 (줄바꿈 불가)
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL (기본 쿠폰 필수)
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme (채널 쿠폰 URL 사용 시 scheme_ios 와 함께 둘 중 하나 필수)
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└commerceobject—
커머스 요소. discount_price 있으면 discount_rate 또는 discount_fixed 중 하나 필수
└titlestring(30)—
상품 제목 (줄바꿈 불가)
└regular_priceinteger(0~99999999)—
정상 가격
└discount_priceinteger(0~99999999)—
할인 후 가격
└discount_rateinteger(0~100)—
할인율
└discount_fixedinteger(0~999999)—
정액 할인 가격
└commerceobject—
커머스 요소. discount_price 있으면 discount_rate 또는 discount_fixed 중 하나 필수
└titlestring(30)—
상품 제목 (줄바꿈 불가)
└regular_priceinteger(0~99999999)—
정상 가격
└discount_priceinteger(0~99999999)—
할인 후 가격
└discount_rateinteger(0~100)—
할인율
└discount_fixedinteger(0~999999)—
정액 할인 가격
└videoobject—

비디오 요소 (PREMIUM_VIDEO/UP 필수). 카카오TV URL 형식:

  • https://tv.kakao.com/v/<id>
  • https://tv.kakao.com/channel/<id>/cliplink/<id>
└video_urlstring(500)—
카카오TV 동영상 URL
└thumbnail_urlstring(500)—
비공개 동영상의 경우 필수
└couponobject—

쿠폰 요소. 링크 필수값 — 기본 쿠폰은 url_mobile 필수,
채널 쿠폰 URL(alimtalk=coupon://) 사용 시 scheme_android/scheme_ios 중 하나 필수.

└titlestring—

쿠폰 제목 — 5가지 형식만 허용:

  • ${숫자}원 할인 쿠폰 (1 ≤ 숫자 ≤ 99,999,999)
  • ${숫자}% 할인 쿠폰 (1 ≤ 숫자 ≤ 100)
  • 배송비 할인 쿠폰
  • ${7자 이내} 무료 쿠폰
  • ${7자 이내} UP 쿠폰
└descriptionstring—
쿠폰 설명. WIDE/WIDE_ITEM_LIST/PREMIUM_VIDEO: 최대 18자 / 그 외: 최대 12자 (줄바꿈 불가)
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL (기본 쿠폰 필수)
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme (채널 쿠폰 URL 사용 시 scheme_ios 와 함께 둘 중 하나 필수)
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└additionalcontentstring(34)—
부가정보 (COMMERCE 최대 34자)
└자유형 (템플릿 미사용)object—

템플릿 없이 본문을 직접 작성해 발송합니다(brandmessagetype: FREE).
templatecode는 사용하지 않습니다. 본문/첨부 필드는 전문 방식과 동일합니다.

└brandmessagetypeconst—
= FREE
└messagestring—

본문 — 전문 방식 / 자유형. 타입별 제한:

  • TEXT/IMAGE: 1300자 (줄바꿈 99개, URL 형식 입력 가능)
  • WIDE / PREMIUM_VIDEO: 76자 (5개)
  • UL/UC/UM/UA: 사용 안 함
└buttonarray<object>—

버튼. 타입별 개수 제한:

  • TEXT/IMAGE: 최대 5개 (쿠폰 적용 시 4개)
  • WIDE / WIDE_ITEM_LIST: 2개
  • PREMIUM_VIDEO: 1개
  • COMMERCE: 1~2개
└typestring필수
브랜드메시지 버튼 타입 — 타입별 사용 가능/필수 파라미터는 카카오 연동 규격 — 브랜드메시지 버튼 참조
= WL | AL | BK | MD | BC | BT | BF | AC
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└chat_extrastring—
상담톡/봇 전환 시 전달할 메타정보
└chat_eventstring—
봇 전환 시 연결할 봇 이벤트명
└biz_form_keyinteger—
비즈니스폼 키 (BF 전용)
└imageobject—
이미지 요소
└img_urlstring—
KAPI 이미지 업로드 API로 사전 등록한 이미지 URL
└img_linkstring(1000)—
이미지 클릭 시 이동 URL. 미설정 시 카카오톡 내 이미지 뷰어 사용
└headerstring(20)—
WIDE_ITEM_LIST 필수 / PREMIUM_VIDEO 선택 (최대 20자)
└itemobject—
와이드 아이템 리스트 (WIDE_ITEM_LIST/UL 전용, list 3~5개)
└listarray<object>(3~4)필수—
└titlestring—
아이템 제목 — 1번째 선택(최대 25자) / 2~5번째 필수(최대 30자), 줄바꿈 1개
└img_urlstring—
아이템 이미지 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└carouselobject—

캐러셀 (CAROUSEL_FEED/UC, CAROUSEL_COMMERCE/UA 필수). 3-레벨: head (인트로, UA만) / list[] / tail.

  • UC: list 2～6개
  • UA: 인트로 있으면 1～6, 없으면 2～6
└headobject—
캐러셀 인트로 (CAROUSEL_COMMERCE 전용)
└headerstring(20)—
인트로 헤더 (줄바꿈 불가)
└contentstring(50)—
인트로 내용 (줄바꿈 최대 2개)
└image_urlstring—
인트로 이미지 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└listarray<object>(1~6)——
└headerstring(20)—
캐러셀 리스트 헤더 (줄바꿈 불가)
└messagestring(180)—
캐러셀 리스트 내용 (줄바꿈 최대 10개)
└additional_contentstring(34)—
부가 정보 (줄바꿈 최대 1개)
└attachmentobject—
캐러셀 아이템 첨부 (버튼·이미지·쿠폰·커머스)
└buttonarray<object>——
└typestring필수
브랜드메시지 버튼 타입 — 타입별 사용 가능/필수 파라미터는 카카오 연동 규격 — 브랜드메시지 버튼 참조
= WL | AL | BK | MD | BC | BT | BF | AC
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme
└chat_extrastring—
상담톡/봇 전환 시 전달할 메타정보
└chat_eventstring—
봇 전환 시 연결할 봇 이벤트명
└biz_form_keyinteger—
비즈니스폼 키 (BF 전용)
└imageobject—
이미지 요소
└img_urlstring—
KAPI 이미지 업로드 API로 사전 등록한 이미지 URL
└img_linkstring(1000)—
이미지 클릭 시 이동 URL. 미설정 시 카카오톡 내 이미지 뷰어 사용
└couponobject—

쿠폰 요소. 링크 필수값 — 기본 쿠폰은 url_mobile 필수,
채널 쿠폰 URL(alimtalk=coupon://) 사용 시 scheme_android/scheme_ios 중 하나 필수.

└titlestring—

쿠폰 제목 — 5가지 형식만 허용:

  • ${숫자}원 할인 쿠폰 (1 ≤ 숫자 ≤ 99,999,999)
  • ${숫자}% 할인 쿠폰 (1 ≤ 숫자 ≤ 100)
  • 배송비 할인 쿠폰
  • ${7자 이내} 무료 쿠폰
  • ${7자 이내} UP 쿠폰
└descriptionstring—
쿠폰 설명. WIDE/WIDE_ITEM_LIST/PREMIUM_VIDEO: 최대 18자 / 그 외: 최대 12자 (줄바꿈 불가)
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL (기본 쿠폰 필수)
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme (채널 쿠폰 URL 사용 시 scheme_ios 와 함께 둘 중 하나 필수)
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└commerceobject—
커머스 요소. discount_price 있으면 discount_rate 또는 discount_fixed 중 하나 필수
└titlestring(30)—
상품 제목 (줄바꿈 불가)
└regular_priceinteger(0~99999999)—
정상 가격
└discount_priceinteger(0~99999999)—
할인 후 가격
└discount_rateinteger(0~100)—
할인율
└discount_fixedinteger(0~999999)—
정액 할인 가격
└commerceobject—
커머스 요소. discount_price 있으면 discount_rate 또는 discount_fixed 중 하나 필수
└titlestring(30)—
상품 제목 (줄바꿈 불가)
└regular_priceinteger(0~99999999)—
정상 가격
└discount_priceinteger(0~99999999)—
할인 후 가격
└discount_rateinteger(0~100)—
할인율
└discount_fixedinteger(0~999999)—
정액 할인 가격
└videoobject—

비디오 요소 (PREMIUM_VIDEO/UP 필수). 카카오TV URL 형식:

  • https://tv.kakao.com/v/<id>
  • https://tv.kakao.com/channel/<id>/cliplink/<id>
└video_urlstring(500)—
카카오TV 동영상 URL
└thumbnail_urlstring(500)—
비공개 동영상의 경우 필수
└couponobject—

쿠폰 요소. 링크 필수값 — 기본 쿠폰은 url_mobile 필수,
채널 쿠폰 URL(alimtalk=coupon://) 사용 시 scheme_android/scheme_ios 중 하나 필수.

└titlestring—

쿠폰 제목 — 5가지 형식만 허용:

  • ${숫자}원 할인 쿠폰 (1 ≤ 숫자 ≤ 99,999,999)
  • ${숫자}% 할인 쿠폰 (1 ≤ 숫자 ≤ 100)
  • 배송비 할인 쿠폰
  • ${7자 이내} 무료 쿠폰
  • ${7자 이내} UP 쿠폰
└descriptionstring—
쿠폰 설명. WIDE/WIDE_ITEM_LIST/PREMIUM_VIDEO: 최대 18자 / 그 외: 최대 12자 (줄바꿈 불가)
└url_mobilestring(1000)—
MOBILE 환경에서 이동할 URL (기본 쿠폰 필수)
└url_pcstring(1000)—
PC 환경에서 이동할 URL
└scheme_androidstring(1000)—
ANDROID 환경, Application Custom Scheme (채널 쿠폰 URL 사용 시 scheme_ios 와 함께 둘 중 하나 필수)
└scheme_iosstring(1000)—
iOS 환경, Application Custom Scheme
└additionalcontentstring(34)—
부가정보 (COMMERCE 최대 34자)
resendobject—
대체 발송 설정 (본 발송 실패 시 다른 채널로 자동 전환). 채널 조합·규격은 대체 발송 참조
recontentobject—
대체 채널별 본문 (resend와 짝) — 대체 발송 참조
대상
방식
고객사 회원 › 변수 미사용 › 텍스트brandmessagetype: BASICsendtarget: marketingtargeting: M
message.json· TEXT
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}

브랜드메시지 예시 — 전체 64개 조합

발송 대상 2 × 방식 4 × 타입 8. 인쇄/PDF 전용 선형 목록입니다.

고객사 회원 › 변수 미사용 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 미사용 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 미사용 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 미사용 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 미사용 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 미사용 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 미사용 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 미사용 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M"
    }
  }
}
고객사 회원 › 변수 분리 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "messagevariable": {
        "변수": "이름"
      },
      "buttonvariable": {
        "1": "www.bizppurio.com"
      },
      "couponvariable": {
        "1": "www.bizppurio.com",
        "상품명": "상품"
      }
    }
  }
}
고객사 회원 › 변수 분리 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "messagevariable": {
        "A": "testA"
      },
      "buttonvariable": {
        "B": "testB"
      },
      "couponvariable": {
        "C": "testC",
        "할인금액": "1234"
      },
      "imagevariable": [
        "https://{이미지}"
      ]
    }
  }
}
고객사 회원 › 변수 분리 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "messagevariable": {
        "내용": "와이드 이미지 메시지는 최대 76자(줄바꿈: 최대 1개)"
      },
      "buttonvariable": {
        "mobile링크": "http://bizppurio.com/",
        "android링크": "kakao://buttons-linkAnd",
        "ios링크": "kakao://buttons-linkIos"
      },
      "couponvariable": {
        "할인금액": "500",
        "쿠폰설명": "쿠폰설명 최대 18자"
      },
      "imagevariable": [
        "{img_url}"
      ]
    }
  }
}
고객사 회원 › 변수 분리 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "messagevariable": {
        "헤더": "헤헤더더",
        "타이틀": "타타이이틀틀",
        "링크": "www.bizppurio.com",
        "타이틀2": "타타이이틀틀2",
        "링크2": "www.bizppurio.com",
        "타이틀3": "타타이이틀틀3",
        "링크3": "www.bizppurio.com",
        "타이틀4": "타타이이틀틀4",
        "링크4": "www.bizppurio.com"
      },
      "buttonvariable": {
        "모바일링크": "www.bizppurio.com"
      },
      "couponvariable": {
        "할인금액": "30,000",
        "모바일링크": "www.bizppurio.com"
      },
      "imagevariable": [
        "{img_url1}",
        "{img_url2}",
        "{img_url3}",
        "{img_url4}"
      ]
    }
  }
}
고객사 회원 › 변수 분리 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "carouselvariable": [
        {
          "messagevariable": {
            "이름": "이름",
            "상품명": "상품명",
            "가격": "가격"
          },
          "couponvariable": {
            "할인금액": "10,000"
          }
        },
        {
          "messagevariable": {
            "이름": "이름",
            "상품명": "상품명",
            "가격": "가격"
          },
          "buttonvariable": {
            "모바일링크": "www.bizppurio.com"
          }
        }
      ]
    }
  }
}
고객사 회원 › 변수 분리 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "messagevariable": {
        "이름": "30,000",
        "상품명": "상품",
        "가격": "가격"
      },
      "buttonvariable": {
        "모바일링크": "www.bizppurio.com"
      },
      "videovariable": {
        "video_url": "{video_url}",
        "thumbnail_url": "{thumbnail_url}"
      }
    }
  }
}
고객사 회원 › 변수 분리 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "messagevariable": {
        "부가정보": "부가정보"
      },
      "commercevariable": {
        "정상가격": "30000",
        "할인가격": "20000",
        "할인율": "10",
        "정액할인가격": "10"
      },
      "buttonvariable": {
        "모바일링크": "www.bizppurio.com"
      },
      "couponvariable": {
        "할인금액": "10",
        "모바일링크": "www.bizppurio.com"
      }
    }
  }
}
고객사 회원 › 변수 분리 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "carouselvariable": [
        {
          "messagevariable": {
            "헤더": "헤더",
            "내용": "내용",
            "모바일링크": "www.bizppurio.com"
          }
        },
        {
          "messagevariable": {
            "부가정보": "부가정보"
          },
          "commercevariable": {
            "상품": "키키",
            "정상가격": "100",
            "할인가격": "90",
            "할인율": "10"
          },
          "buttonvariable": {
            "모바일링크": "www.bizppurio.com",
            "모바일링크2": "www.bizppurio.com"
          },
          "couponvariable": {
            "할인금액": 20,
            "내용": "내용",
            "모바일링크": "www.bizppurio.com"
          }
        }
      ]
    }
  }
}
고객사 회원 › 전문 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "message": "변수\n텍스트_변수_테스트",
      "button": [
        {
          "type": "WL",
          "url_mobile": "http://www.bizppurio.com"
        }
      ],
      "coupon": {
        "title": "상품 무료 쿠폰",
        "url_mobile": "http://www.bizppurio.com"
      }
    }
  }
}
고객사 회원 › 전문 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "message": "브랜드메시지 이미지"
    }
  }
}
고객사 회원 › 전문 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "message": "와이드 이미지 메시지는 최대 76자(줄바꿈: 최대 1개)"
    }
  }
}
고객사 회원 › 전문 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "header": "헤더",
      "item": {
        "list": [
          {
            "title": "최대 25자(줄바꿈: 최대 1개)",
            "img_url": "{img_url1}",
            "url_mobile": "https://www.bizppurio.com",
            "scheme_android": "kakao://mainWideItem-linkAnd",
            "scheme_ios": "kakao://mainWideItem-linkIos"
          },
          {
            "title": "최대 30자(줄바꿈: 최대 1개)",
            "img_url": "{img_url2}"
          },
          {
            "title": "최대 30자(줄바꿈: 최대 1개)",
            "img_url": "{img_url3}",
            "url_mobile": "https://www.bizppurio.com",
            "scheme_ios": "kakao://subWideItem-linkIos"
          },
          {
            "title": "최대 30자(줄바꿈: 최대 1개)",
            "img_url": "{img_url4}",
            "url_mobile": "https://www.bizppurio.com"
          }
        ]
      },
      "button": [
        {
          "type": "WL",
          "url_mobile": "https://bizppurio.com"
        }
      ],
      "coupon": {
        "title": "1원 할인 쿠폰",
        "url_mobile": "http://bizppurio.com"
      }
    }
  }
}
고객사 회원 › 전문 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "carousel": {
        "list": [
          {
            "header": "최대 20자(줄바꿈: 불가)",
            "message": "최대 180자(줄바꿈: 최대 2개)",
            "attachment": {
              "coupon": {
                "title": "이모티콘 무료 쿠폰",
                "description": "최대 12자",
                "url_mobile": "https://bizppurio.com"
              },
              "image": {
                "img_url": "{img_url1}",
                "img_link": "https://bizppurio.com"
              }
            }
          },
          {
            "header": "최대 20자(줄바꿈: 불가)",
            "message": "최대 180자(줄바꿈: 최대 2개)",
            "attachment": {
              "image": {
                "img_url": "{img_url2}"
              }
            }
          }
        ]
      }
    }
  }
}
고객사 회원 › 전문 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "video": {
        "video_url": "{video_url}",
        "thumbnail_url": "{thumbnail_url}"
      },
      "message": "프리미엄 동영상 메시지는 최대 76자 (줄바꿈: 최대 1개)",
      "button": [
        {
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ]
    }
  }
}
고객사 회원 › 전문 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "image": {
        "img_url": "{img_url}"
      },
      "commerce": {
        "regular_price": 3000,
        "discount_price": 2000,
        "discount_rate": 33
      },
      "additionalcontent": "부가정보",
      "button": [
        {
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ],
      "coupon": {
        "title": "10원 할인 쿠폰",
        "url_mobile": "https://www.bizppurio.com"
      }
    }
  }
}
고객사 회원 › 전문 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "tempXXXX",
      "targeting": "M",
      "carousel": {
        "head": {
          "header": "최대 20자 (줄바꿈: 불가)",
          "content": "최대 50자 (줄바꿈: 최대 2개)"
        },
        "list": [
          {
            "attachment": {
              "commerce": {
                "regular_price": 3000,
                "discount_price": 1000,
                "discount_rate": 67
              },
              "button": [
                {
                  "type": "WL",
                  "url_mobile": "https://www.bizppurio.com"
                }
              ],
              "image": {
                "img_url": "{img_url1}"
              }
            }
          },
          {
            "attachment": {
              "image": {
                "img_url": "{img_url2}",
                "img_link": "https://bizppurio.com"
              }
            }
          },
          {
            "attachment": {
              "button": [
                {
                  "type": "AL",
                  "url_mobile": "https://www.bizppurio.com",
                  "scheme_android": "kakao://buttons-linkAnd",
                  "scheme_ios": "kakao://buttons-linkIos"
                }
              ],
              "image": {
                "img_url": "{img_url3}"
              }
            }
          }
        ]
      }
    }
  }
}
고객사 회원 › 자유형 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "message": "변수\n텍스트_변수_테스트",
      "button": [
        {
          "name": "버튼",
          "type": "WL",
          "url_mobile": "http://www.bizppurio.com"
        }
      ]
    }
  }
}
고객사 회원 › 자유형 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "message": "브랜드메시지 이미지",
      "image": {
        "img_url": "https://{이미지}",
        "img_link": "https://{이미지링크}"
      }
    }
  }
}
고객사 회원 › 자유형 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "message": "메시지",
      "image": {
        "img_url": "{img_url}",
        "img_link": "http://bizppurio.com"
      }
    }
  }
}
고객사 회원 › 자유형 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "header": "와이드 리스트 header",
      "item": {
        "list": [
          {
            "title": "1번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          },
          {
            "title": "2번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          },
          {
            "title": "3번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          },
          {
            "title": "4번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          }
        ]
      },
      "button": [
        {
          "name": "버튼명입니다.",
          "type": "WL",
          "url_mobile": "http://bizppurio.com/"
        }
      ],
      "coupon": {
        "title": "1원 할인 쿠폰",
        "description": "쿠폰 상세 내용입니다.",
        "url_mobile": "http://bizppurio.com/"
      }
    }
  }
}
고객사 회원 › 자유형 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "carousel": {
        "list": [
          {
            "header": "1번 캐러셀 피드 헤더",
            "message": "1번 캐러셀 피드 메시지",
            "attachment": {
              "image": {
                "img_url": "{img_url}"
              },
              "coupon": {
                "description": "쿠폰 상세일까요?",
                "title": "10원 할인 쿠폰",
                "url_mobile": "https://www.bizppurio.com"
              }
            }
          },
          {
            "header": "2번 캐러셀 피드 헤더",
            "message": "2번 캐러셀 피드 메시지",
            "attachment": {
              "image": {
                "img_url": "{img_url}"
              },
              "button": [
                {
                  "name": "필수",
                  "type": "WL",
                  "url_mobile": "https://www.bizppurio.com"
                }
              ]
            }
          }
        ]
      }
    }
  }
}
고객사 회원 › 자유형 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "video": {
        "video_url": "{video_url}",
        "thumbnail_url": "{thumbnail_url}"
      },
      "header": "헤더입니다.",
      "message": "#{이름} 님 안녕하세요, #{상품명} 할인 판매 중입니다!\n#{가격} 원에 드릴게요.",
      "button": [
        {
          "name": "버튼명입니다.",
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ]
    }
  }
}
고객사 회원 › 자유형 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "image": {
        "img_url": "{img_url}"
      },
      "commerce": {
        "title": "상품명입니다.",
        "regular_price": 3000,
        "discount_price": 2000,
        "discount_rate": 33
      },
      "additionalcontent": "부가정보",
      "button": [
        {
          "name": "버튼명입니다.",
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ]
    }
  }
}
고객사 회원 › 자유형 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "marketing",
      "targeting": "M",
      "carousel": {
        "head": {
          "header": "인트로 피드 헤더",
          "content": "인트로 피드 컨텐츠",
          "image_url": "{image_url}"
        },
        "list": [
          {
            "additional_content": "",
            "attachment": {
              "image": {
                "img_url": "{image_url}"
              },
              "commerce": {
                "title": "타이틀",
                "regular_price": 3000,
                "discount_fixed": 1000
              },
              "button": [
                {
                  "name": "버튼",
                  "type": "WL",
                  "url_mobile": "https://bizppurio.com"
                },
                {
                  "name": "버튼",
                  "type": "WL",
                  "url_mobile": "https://bizppurio.com",
                  "url_pc": "https://www.bizppurio.com"
                }
              ]
            }
          }
        ]
      }
    }
  }
}
채널 친구 › 변수 미사용 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 미사용 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 미사용 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 미사용 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 미사용 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 미사용 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 미사용 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 미사용 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX"
    }
  }
}
채널 친구 › 변수 분리 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "messagevariable": {
        "변수": "이름"
      },
      "buttonvariable": {
        "1": "www.bizppurio.com"
      },
      "couponvariable": {
        "1": "www.bizppurio.com",
        "상품명": "상품"
      }
    }
  }
}
채널 친구 › 변수 분리 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "messagevariable": {
        "A": "testA"
      },
      "buttonvariable": {
        "B": "testB"
      },
      "couponvariable": {
        "C": "testC",
        "할인금액": "1234"
      },
      "imagevariable": [
        "https://{이미지}"
      ]
    }
  }
}
채널 친구 › 변수 분리 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "messagevariable": {
        "내용": "와이드 이미지 메시지는 최대 76자(줄바꿈: 최대 1개)"
      },
      "buttonvariable": {
        "mobile링크": "http://bizppurio.com/",
        "android링크": "kakao://buttons-linkAnd",
        "ios링크": "kakao://buttons-linkIos"
      },
      "couponvariable": {
        "할인금액": "500",
        "쿠폰설명": "쿠폰설명 최대 18자"
      },
      "imagevariable": [
        "{img_url}"
      ]
    }
  }
}
채널 친구 › 변수 분리 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "messagevariable": {
        "헤더": "헤헤더더",
        "타이틀": "타타이이틀틀",
        "링크": "www.bizppurio.com",
        "타이틀2": "타타이이틀틀2",
        "링크2": "www.bizppurio.com",
        "타이틀3": "타타이이틀틀3",
        "링크3": "www.bizppurio.com",
        "타이틀4": "타타이이틀틀4",
        "링크4": "www.bizppurio.com"
      },
      "buttonvariable": {
        "모바일링크": "www.bizppurio.com"
      },
      "couponvariable": {
        "할인금액": "30,000",
        "모바일링크": "www.bizppurio.com"
      },
      "imagevariable": [
        "{img_url1}",
        "{img_url2}",
        "{img_url3}",
        "{img_url4}"
      ]
    }
  }
}
채널 친구 › 변수 분리 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "carouselvariable": [
        {
          "messagevariable": {
            "이름": "이름",
            "상품명": "상품명",
            "가격": "가격"
          },
          "couponvariable": {
            "할인금액": "10,000"
          }
        },
        {
          "messagevariable": {
            "이름": "이름",
            "상품명": "상품명",
            "가격": "가격"
          },
          "buttonvariable": {
            "모바일링크": "www.bizppurio.com"
          }
        }
      ]
    }
  }
}
채널 친구 › 변수 분리 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "messagevariable": {
        "이름": "30,000",
        "상품명": "상품",
        "가격": "가격"
      },
      "buttonvariable": {
        "모바일링크": "www.bizppurio.com"
      },
      "videovariable": {
        "video_url": "{video_url}",
        "thumbnail_url": "{thumbnail_url}"
      }
    }
  }
}
채널 친구 › 변수 분리 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "messagevariable": {
        "부가정보": "부가정보"
      },
      "commercevariable": {
        "정상가격": "30000",
        "할인가격": "20000",
        "할인율": "10",
        "정액할인가격": "10"
      },
      "buttonvariable": {
        "모바일링크": "www.bizppurio.com"
      },
      "couponvariable": {
        "할인금액": "10",
        "모바일링크": "www.bizppurio.com"
      }
    }
  }
}
채널 친구 › 변수 분리 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "carouselvariable": [
        {
          "messagevariable": {
            "헤더": "헤더",
            "내용": "내용",
            "모바일링크": "www.bizppurio.com"
          }
        },
        {
          "messagevariable": {
            "부가정보": "부가정보"
          },
          "commercevariable": {
            "상품": "키키",
            "정상가격": "100",
            "할인가격": "90",
            "할인율": "10"
          },
          "buttonvariable": {
            "모바일링크": "www.bizppurio.com",
            "모바일링크2": "www.bizppurio.com"
          },
          "couponvariable": {
            "할인금액": 20,
            "내용": "내용",
            "모바일링크": "www.bizppurio.com"
          }
        }
      ]
    }
  }
}
채널 친구 › 전문 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "message": "변수\n텍스트_변수_테스트",
      "button": [
        {
          "type": "WL",
          "url_mobile": "http://www.bizppurio.com"
        }
      ],
      "coupon": {
        "title": "상품 무료 쿠폰",
        "url_mobile": "http://www.bizppurio.com"
      }
    }
  }
}
채널 친구 › 전문 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "message": "브랜드메시지 이미지"
    }
  }
}
채널 친구 › 전문 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "message": "와이드 이미지 메시지는 최대 76자(줄바꿈: 최대 1개)"
    }
  }
}
채널 친구 › 전문 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "header": "헤더",
      "item": {
        "list": [
          {
            "title": "최대 25자(줄바꿈: 최대 1개)",
            "img_url": "{img_url1}",
            "url_mobile": "https://www.bizppurio.com",
            "scheme_android": "kakao://mainWideItem-linkAnd",
            "scheme_ios": "kakao://mainWideItem-linkIos"
          },
          {
            "title": "최대 30자(줄바꿈: 최대 1개)",
            "img_url": "{img_url2}"
          },
          {
            "title": "최대 30자(줄바꿈: 최대 1개)",
            "img_url": "{img_url3}",
            "url_mobile": "https://www.bizppurio.com",
            "scheme_ios": "kakao://subWideItem-linkIos"
          },
          {
            "title": "최대 30자(줄바꿈: 최대 1개)",
            "img_url": "{img_url4}",
            "url_mobile": "https://www.bizppurio.com"
          }
        ]
      },
      "button": [
        {
          "type": "WL",
          "url_mobile": "https://bizppurio.com"
        }
      ],
      "coupon": {
        "title": "1원 할인 쿠폰",
        "url_mobile": "http://bizppurio.com"
      }
    }
  }
}
채널 친구 › 전문 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "carousel": {
        "list": [
          {
            "header": "최대 20자(줄바꿈: 불가)",
            "message": "최대 180자(줄바꿈: 최대 2개)",
            "attachment": {
              "coupon": {
                "title": "이모티콘 무료 쿠폰",
                "description": "최대 12자",
                "url_mobile": "https://bizppurio.com"
              },
              "image": {
                "img_url": "{img_url1}",
                "img_link": "https://bizppurio.com"
              }
            }
          },
          {
            "header": "최대 20자(줄바꿈: 불가)",
            "message": "최대 180자(줄바꿈: 최대 2개)",
            "attachment": {
              "image": {
                "img_url": "{img_url2}"
              }
            }
          }
        ]
      }
    }
  }
}
채널 친구 › 전문 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "video": {
        "video_url": "{video_url}",
        "thumbnail_url": "{thumbnail_url}"
      },
      "message": "프리미엄 동영상 메시지는 최대 76자 (줄바꿈: 최대 1개)",
      "button": [
        {
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ]
    }
  }
}
채널 친구 › 전문 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "image": {
        "img_url": "{img_url}"
      },
      "commerce": {
        "regular_price": 3000,
        "discount_price": 2000,
        "discount_rate": 33
      },
      "additionalcontent": "부가정보",
      "button": [
        {
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ],
      "coupon": {
        "title": "10원 할인 쿠폰",
        "url_mobile": "https://www.bizppurio.com"
      }
    }
  }
}
채널 친구 › 전문 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "BASIC",
      "sendtarget": "friend",
      "templatecode": "tempXXXX",
      "carousel": {
        "head": {
          "header": "최대 20자 (줄바꿈: 불가)",
          "content": "최대 50자 (줄바꿈: 최대 2개)"
        },
        "list": [
          {
            "attachment": {
              "commerce": {
                "regular_price": 3000,
                "discount_price": 1000,
                "discount_rate": 67
              },
              "button": [
                {
                  "type": "WL",
                  "url_mobile": "https://www.bizppurio.com"
                }
              ],
              "image": {
                "img_url": "{img_url1}"
              }
            }
          },
          {
            "attachment": {
              "image": {
                "img_url": "{img_url2}",
                "img_link": "https://bizppurio.com"
              }
            }
          },
          {
            "attachment": {
              "button": [
                {
                  "type": "AL",
                  "url_mobile": "https://www.bizppurio.com",
                  "scheme_android": "kakao://buttons-linkAnd",
                  "scheme_ios": "kakao://buttons-linkIos"
                }
              ],
              "image": {
                "img_url": "{img_url3}"
              }
            }
          }
        ]
      }
    }
  }
}
채널 친구 › 자유형 › 텍스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ut",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ut": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "message": "변수\n텍스트_변수_테스트",
      "button": [
        {
          "name": "버튼",
          "type": "WL",
          "url_mobile": "http://www.bizppurio.com"
        }
      ]
    }
  }
}
채널 친구 › 자유형 › 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ui",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ui": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "message": "브랜드메시지 이미지",
      "image": {
        "img_url": "https://{이미지}",
        "img_link": "https://{이미지링크}"
      }
    }
  }
}
채널 친구 › 자유형 › 와이드 이미지
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uw",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uw": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "message": "메시지",
      "image": {
        "img_url": "{img_url}",
        "img_link": "http://bizppurio.com"
      }
    }
  }
}
채널 친구 › 자유형 › 와이드 리스트
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ul",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ul": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "header": "와이드 리스트 header",
      "item": {
        "list": [
          {
            "title": "1번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          },
          {
            "title": "2번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          },
          {
            "title": "3번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          },
          {
            "title": "4번 아이템",
            "img_url": "{img_url}",
            "url_mobile": "http://bizppurio.com/"
          }
        ]
      },
      "button": [
        {
          "name": "버튼명입니다.",
          "type": "WL",
          "url_mobile": "http://bizppurio.com/"
        }
      ],
      "coupon": {
        "title": "1원 할인 쿠폰",
        "description": "쿠폰 상세 내용입니다.",
        "url_mobile": "http://bizppurio.com/"
      }
    }
  }
}
채널 친구 › 자유형 › 캐러셀 피드
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "uc",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "uc": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "carousel": {
        "list": [
          {
            "header": "1번 캐러셀 피드 헤더",
            "message": "1번 캐러셀 피드 메시지",
            "attachment": {
              "image": {
                "img_url": "{img_url}"
              },
              "coupon": {
                "description": "쿠폰 상세일까요?",
                "title": "10원 할인 쿠폰",
                "url_mobile": "https://www.bizppurio.com"
              }
            }
          },
          {
            "header": "2번 캐러셀 피드 헤더",
            "message": "2번 캐러셀 피드 메시지",
            "attachment": {
              "image": {
                "img_url": "{img_url}"
              },
              "button": [
                {
                  "name": "필수",
                  "type": "WL",
                  "url_mobile": "https://www.bizppurio.com"
                }
              ]
            }
          }
        ]
      }
    }
  }
}
채널 친구 › 자유형 › 프리미엄 동영상
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "up",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "up": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "video": {
        "video_url": "{video_url}",
        "thumbnail_url": "{thumbnail_url}"
      },
      "header": "헤더입니다.",
      "message": "#{이름} 님 안녕하세요, #{상품명} 할인 판매 중입니다!\n#{가격} 원에 드릴게요.",
      "button": [
        {
          "name": "버튼명입니다.",
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ]
    }
  }
}
채널 친구 › 자유형 › 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "image": {
        "img_url": "{img_url}"
      },
      "commerce": {
        "title": "상품명입니다.",
        "regular_price": 3000,
        "discount_price": 2000,
        "discount_rate": 33
      },
      "additionalcontent": "부가정보",
      "button": [
        {
          "name": "버튼명입니다.",
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ]
    }
  }
}
채널 친구 › 자유형 › 캐러셀 커머스
{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ua",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ua": {
      "senderkey": "abc123XXXXX",
      "brandmessagetype": "FREE",
      "sendtarget": "friend",
      "carousel": {
        "head": {
          "header": "인트로 피드 헤더",
          "content": "인트로 피드 컨텐츠",
          "image_url": "{image_url}"
        },
        "list": [
          {
            "additional_content": "",
            "attachment": {
              "image": {
                "img_url": "{image_url}"
              },
              "commerce": {
                "title": "타이틀",
                "regular_price": 3000,
                "discount_fixed": 1000
              },
              "button": [
                {
                  "name": "버튼",
                  "type": "WL",
                  "url_mobile": "https://bizppurio.com"
                },
                {
                  "name": "버튼",
                  "type": "WL",
                  "url_mobile": "https://bizppurio.com",
                  "url_pc": "https://www.bizppurio.com"
                }
              ]
            }
          }
        ]
      }
    }
  }
}
post/v3/messagetype=ntalk

네이버 톡톡

실제 HTTP endpoint: POST /v3/message — type: ntalk 네이버 톡톡 페이로드만 보여주는 채널별 문서 페이지입니다.
통합 endpoint 와 공통 설명은 POST /v3/message 를 참고하세요.

네이버 톡톡은 사전 검수된 템플릿 기반으로 발송합니다. 본문 구성 방식은 두 가지입니다.

방식 사용 파라미터 설명
변수 치환 발송 templatecode + extra.templateParams 템플릿의 변수를 키/값 쌍으로 치환 (값 최대 150자)
고정 컨텐츠 발송 templatecode + message 템플릿이 변환되어 발송될 최종 텍스트를 직접 입력 (최대 2,048자)

사전 준비: 네이버 톡톡 채널 개설 (파트너센터) 후 발송 ID(partnerid)·Key(partnerkey) 확보

WARNING: 네이버 톡톡은 예약 발송이 불가합니다 — sendtime 값과 무관하게 즉시 발송됩니다.

템플릿 타입 (templatetype)

templatetype 상품코드 (productcode) 설명
ID INFORMATION 정보 — 기본 (Default)
IG INFORMATION 정보 — 선물전달 (Gift). extra.attachment.gift.coupon 사용
IT INFORMATION 정보 — 테이블 (Table)
BD BENEFIT 혜택 — 기본 (Default)
BM BENEFIT 혜택 — LMS (Message)
BC BENEFIT 혜택 — 캐러셀 커머스/피드 (Carousel)
BL BENEFIT 혜택 — 리스트 커머스/피드 (List)
CT CARDINFO 카드 템플릿

첨부 (extra.attachment)

  • 버튼 (buttons) — 템플릿에 등록한 버튼 최대 5개. WEB_LINK 타입은 pcUrl/mobileUrl 필수, APP_LINK 타입은 aOsAppScheme/iOsAppScheme 필수
  • 이미지 — imageUrl(http로 시작하는 URL) 또는 imageHashId(이미지 업로드 API로 발급받은 hashId, 64자)
  • 선물 (gift.coupon) — 선물전달 타입(IG) 전용. code·endDate(예: "2024-04-10") 필수, name 미입력 시 템플릿 등록 이름 사용
요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
typestring필수

메시지 데이터 타입. 채널 식별자로 사용되며, content 객체는 이 값과 매칭되는 키 하나만 포함합니다.

= ntalk
fromstring(16)필수
발신 번호
tostring(16)필수
수신 번호
refkeystring(32)필수
고객사에서 부여한 키 (UTF-8 기준 최대 32바이트)
countrystring(5)—
국가 코드 (국제 메시지 발송 시)
userinfostring(50)—
정산용 부서 코드
resellercodestring—
특부가사업자 식별코드 (9자리 숫자)
sendtimestring—
예약 발송 시각 (unixtime, GMT+9 기준, 최대 30일 이내)
contentobject필수

네이버 톡톡 (type: ntalk) — 사전 검수된 템플릿 기반 발송. 예약 발송 불가 (즉시 발송).
템플릿 타입 표·첨부 규칙은 네이버 톡톡 발송 페이지 를 참고하세요.

└ntalkobject필수—
└partneridstring(40)필수
네이버 톡톡 발송 ID
└partnerkeystring(64)필수
네이버 톡톡 발송 Key
└productcodestring(64)필수
상품 코드 (INFORMATION / BENEFIT / CARDINFO)
= INFORMATION | BENEFIT | CARDINFO
└templatecodestring(64)필수
템플릿 코드
└templatetypestring(2)—
템플릿 타입 (타입 표는 네이버 톡톡 발송 페이지 참고)
= ID | IG | IT | BD | BM | BC | BL | CT
└usernamestring(5)—
전화번호 소유자 실명
└groupkeystring(30)—
발송 그룹 키 (발송 그룹에 포함된 템플릿/파트너로 발송 시 필수)
└messagestring(2048)—
템플릿이 변환되어 발송될 최종 텍스트 (고정 컨텐츠 발송 시)
└extraobject—
네이버 톡톡 추가 데이터 — 템플릿 치환 변수 + 첨부
└templateParamsobject—
템플릿에서 치환할 키/값 쌍 (값은 최대 150자)
└attachmentobject—
네이버 톡톡 첨부 데이터 — 이미지 / 버튼 / 선물
└imageUrlstring—
http로 시작하는 이미지 URL
└imageHashIdstring(64)—
이미지 업로드 API로 업로드한 hashId
└buttonsarray<object>(~5)—
템플릿 등록한 버튼 정보 (최대 5개)
└buttonCodestring필수
등록 시 사용한 버튼 코드
└pcUrlstring—
PC 환경 이동 링크 (WEB_LINK 시 필수)
└mobileUrlstring—
Mobile 환경 이동 링크 (WEB_LINK 시 필수)
└aOsAppSchemestring—
Android 앱 링크 (APP_LINK 시 필수)
└iOsAppSchemestring—
iOS 앱 링크 (APP_LINK 시 필수)
└giftobject—
선물 전달 타입 템플릿(IG)에서 사용
└couponobject——
└codestring필수
쿠폰 코드
└endDatestring필수
쿠폰 종료일자 (예: "2024-04-10")
└namestring—
쿠폰 이름. 미입력 시 템플릿 등록 이름 사용
└publisherstring—
쿠폰 발급자. 미입력 시 표시되지 않음
└imageUrlstring—
쿠폰에 표시될 이미지 URL
curl -X POST "{baseUrl}/v3/message" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "refkey": "test1234",
  "type": "ntalk",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "ntalk": {
      "partnerid": "partnerid",
      "partnerkey": "partnerkey",
      "templatetype": "ID",
      "productcode": "INFORMATION",
      "templatecode": "templateXXXX",
      "extra": {
        "templateParams": {
          "orderNo": "19102387851"
        },
        "attachment": {
          "buttons": [
            {
              "buttonCode": "dailyExpressionGroup",
              "pcUrl": "https://www.yourdomain.com/order/19102387851",
              "mobileUrl": "https://m.yourdomain.com/order/19102387851"
            }
          ]
        }
      }
    }
  }
}'

파일 업로드

MMS 발송용 이미지 등록 (/v2/file)

post/v2/file

MMS 파일 업로드

MMS 발송 시 첨부할 이미지를 업로드하여 filekey를 발급받습니다.

항목 값
확장자 jpg, jpeg
크기 300 KB 이하
1회 업로드 수 1개

파일은 최대 3개까지 MMS 본문에 첨부할 수 있습니다. 1회 업로드는 1개만 허용되므로 3개를 첨부하려면 업로드를 3번 호출하세요.

요청 본문
파라미터타입필수설명
accountstring(20)필수
비즈뿌리오 계정
filestring <binary>필수
업로드할 이미지 파일 (jpg/jpeg, 300KB 이하)
sendtimestring—
발송 시간 (unixtime, GMT+9, 발송 +1일 이내). 미입력 시 현재 시간.
curl -X POST "{baseUrl}/v2/file" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "string",
  "file": "{binary}",
  "sendtime": "string"
}'
응답
200업로드 성공
파라미터타입필수설명
filekeystring(40)필수
발급된 파일 키 — MMS 발송 시 content.mms.file[].key에 사용
응답 · 200
{
  "filekey": "0920msg_123912934949595969"
}
400요청 실패. 주요 응답 코드: - `2000` 메시지가 유효하지 않음 - `3000~3013` 인증/계정 관련 오류 - `3014` 데이터 포맷 에러
파라미터타입필수설명
codeinteger필수
비즈뿌리오 결과 코드
descriptionstring필수—
refkeystring(32)—
요청 시 전달한 고객사 키 (가능한 경우)
응답 · 400
{
  "code": 2000,
  "description": "invalid message",
  "refkey": "test1234"
}

전송 결과 조회

결과 재요청 및 Polling 조회/완료 처리

post/v2/report

전송 결과 재요청

특정 메시지의 전송 결과를 다시 요청합니다. Webhook을 받지 못했거나 누락된 경우에 사용합니다.
결과 자체는 등록된 Webhook URL로 다시 PUSH됩니다.

요청 본문
파라미터타입필수설명
accountstring(20)필수—
messagekeystring(32)필수
메시지 전송 응답에서 받은 messagekey
curl -X POST "{baseUrl}/v2/report" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "messagekey": "190922175225820#ft002951seXXXXXX"
}'
응답
200재요청 접수 성공
파라미터타입필수설명
codeinteger필수—
descriptionstring필수—
응답 · 200
{
  "code": 1000,
  "description": "Success"
}
400요청 실패. 주요 응답 코드: - `2000` 메시지가 유효하지 않음 - `3000~3013` 인증/계정 관련 오류 - `3014` 데이터 포맷 에러
파라미터타입필수설명
codeinteger필수
비즈뿌리오 결과 코드
descriptionstring필수—
refkeystring(32)—
요청 시 전달한 고객사 키 (가능한 경우)
응답 · 400
{
  "code": 2000,
  "description": "invalid message",
  "refkey": "test1234"
}
post/v1/result/request

전송 결과 요청 (Polling)

Polling 사용 사전 신청 필요. 빈번한 호출은 정책에 따라 차단될 수 있습니다.

운영 규칙

  • 1회 호출 시 최대 1,000개 결과 응답
  • 결과 조회 후 반드시 /v1/result/confirm을 호출해야 동일 결과가 다시 응답되지 않습니다
  • 3일 동안 조회/완료 처리하지 않으면 결과 데이터는 제거됩니다
요청 본문
파라미터타입필수설명
accountstring(20)필수—
curl -X POST "{baseUrl}/v1/result/request" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001"
}'
응답
200Polling 응답
파라미터타입필수설명
codeinteger필수—
descriptionstring필수—
reportarray<object>필수—
└devicestring필수
메시지 유형
└cmsgidstring필수
메시지 키
└msgidstring필수
비즈뿌리오 메시지 키 (완료 처리 시 사용)
└phonestring필수—
└mediastring필수
실제 발송된 메시지 상세 유형 (Webhook MEDIA 표 참고)
└unixtimestring필수—
└resultstring필수
이통사/카카오/RCS 결과 코드
└to_namestring——
└userdatastring——
└wapinfostring—
SKT/KTF/LGT/KAO
└telresstring——
└teltimestring——
└kaoresstring——
└kaotimestring——
└rcsresstring——
└rcstimestring——
└retry_flagstring——
└resend_flagstring——
└refkeystring——
응답 · 200
{
  "code": 1000,
  "description": "success",
  "report": [
    {
      "device": "SMS",
      "cmsgid": "201027134355944sms027420XXXXXXXX",
      "msgid": "1027se_SL46760273836XXXXXXXX",
      "phone": "01012345678",
      "media": "SMS",
      "unixtime": "1603773837",
      "result": "4100",
      "userdata": "daoutech",
      "wapinfo": "SKT",
      "refkey": "test1234"
    }
  ]
}
400요청 실패. 주요 응답 코드: - `2000` 메시지가 유효하지 않음 - `3000~3013` 인증/계정 관련 오류 - `3014` 데이터 포맷 에러
파라미터타입필수설명
codeinteger필수
비즈뿌리오 결과 코드
descriptionstring필수—
refkeystring(32)—
요청 시 전달한 고객사 키 (가능한 경우)
응답 · 400
{
  "code": 2000,
  "description": "invalid message",
  "refkey": "test1234"
}
post/v1/result/confirm

전송 결과 완료 처리 (Polling)

Polling으로 받은 결과를 처리 완료로 표시합니다.
호출하지 않으면 동일한 결과가 다음 Polling 호출에서 계속 응답됩니다.

요청 본문
파라미터타입필수설명
accountstring(20)필수—
msgidarray<object>(~1000)필수
비즈뿌리오 메시지 키 배열 (최대 1000개)
└msgidstring필수—
curl -X POST "{baseUrl}/v1/result/confirm" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "account": "bizUserId001",
  "msgid": [
    {
      "msgid": "1027se_SL46760273836XXXXXXXX"
    },
    {
      "msgid": "1027se_SL46760273836XXXXXXXX"
    }
  ]
}'
응답
200완료 처리 성공
파라미터타입필수설명
codeinteger필수—
descriptionstring필수—
응답 · 200
{
  "code": 1000,
  "description": "Success"
}
400요청 실패. 주요 응답 코드: - `2000` 메시지가 유효하지 않음 - `3000~3013` 인증/계정 관련 오류 - `3014` 데이터 포맷 에러
파라미터타입필수설명
codeinteger필수
비즈뿌리오 결과 코드
descriptionstring필수—
refkeystring(32)—
요청 시 전달한 고객사 키 (가능한 경우)
응답 · 400
{
  "code": 2000,
  "description": "invalid message",
  "refkey": "test1234"
}

가이드

메시지 API 활용 가이드 모음 — 대체 발송 / Rate Limit / 이미지 업로드 / 국제 / 결과 수신.

대체 발송

알림톡·브랜드메시지·RCS는 수신자 단말 환경·앱 사용 여부에 따라 도달이 보장되지 않습니다. 비즈뿌리오는 본 발송 실패 시 다른 채널로 자동 전환하는 **대체 발송(RESEND)**을 지원합니다.

"재발송"의 두 가지 동작

비즈뿌리오에서 "재..." 라는 표현은 두 가지 다른 동작을 가리켜 혼동하기 쉽습니다. 먼저 구분합니다.

동작 키워드 무엇이 일어나는가 언제 사용
대체 발송 (RESEND) resend.first / resend.second 본 발송 실패 시 다른 채널로 자동 1회 더 발송 알림톡/RCS 도달 보장 안 될 때
결과 재요청 POST /v2/report 보관된 결과를 Webhook URL로 다시 PUSH (새 발송 아님 — 결과 수신 참고) Webhook 누락·장애 복구

대체 발송 (RESEND)

본 발송이 실패하면 비즈뿌리오 서버가 자동으로 다른 채널로 보냅니다 (고객사 코드 불필요, 1·2차까지, 추가 비용 발생).

사용 패턴

본 발송 1차 대체 2차 대체 의도
AT (알림톡) SMS — 카카오톡 미사용자에게 도달
AT RCS SMS RCS 단말 우선, 미수신 시 SMS
BT (브랜드메시지) RCS MMS 풍부한 표현 → 풍부한 표현 → 텍스트
RCS AT SMS 안드로이드 채팅+ 미지원 단말 처리
RCS BT SMS RCS 미지원 + 광고성 메시지

API 패턴

resend 객체로 대체 채널을 명시하고, recontent에 각 대체 채널의 페이로드를 둡니다.

1차 대체만

알림톡(AT) 실패 시 SMS로 대체:

{
  "account": "test",
  "refkey": "test1234",
  "type": "at",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "at": {
      "senderkey": "12345",
      "templatecode": "template",
      "message": "알림톡 본문",
      "button": [
        { "name": "자세히 보기", "type": "WL", "url_mobile": "https://example.com" }
      ]
    }
  },
  "resend": { "first": "sms" },
  "recontent": {
    "sms": { "message": "SMS 대체 발송 본문" }
  }
}

1차·2차 대체 (RCS → AT → SMS)

{
  "type": "rcs",
  "content": { "rcs": { "messagebaseid": "SL000000", "chatbotid": "...", "message": { "title": "...", "description": "..." } } },
  "resend": { "first": "at", "second": "sms" },
  "recontent": {
    "at": { "senderkey": "...", "templatecode": "...", "message": "AT 본문" },
    "sms": { "message": "SMS 대체 발송" }
  }
}

지원 조합 (본 발송별)

대체 가능 조합은 본 발송 채널에 따라 정해집니다. 카카오(알림톡·브랜드)끼리 대체는 불가하며, 2차 대체는 1차가 RCS(카카오 본발송 시) 또는 카카오(RCS 본발송 시)일 때만 가능합니다. 2차 대체는 항상 문자(SMS·LMS·MMS)입니다.

본 발송 1차 대체 (resend.first) 2차 대체 (resend.second)
알림톡 AT·AI SMS·LMS·MMS 또는 RCS 1차가 RCS일 때만 SMS·LMS·MMS
브랜드 UT~UA (8종) SMS·LMS·MMS 또는 RCS 1차가 RCS일 때만 SMS·LMS·MMS
RCS SMS·LMS·MMS 또는 카카오(AT·AI·UT~UA) 1차가 카카오일 때만 SMS·LMS·MMS

각 대체 채널의 본문은 recontent.<채널> 에 넣습니다(미입력 시 본 발송 본문을 대체 채널 규격에 맞게 자동 변환). 자세한 사양은 API 메시지 전송 참고.

본문 처리 (recontent)

시나리오 recontent.<type>
원본 본문 그대로 사용 비워두기 — 자동으로 원본 본문 사용
다른 본문 사용 명시 입력
SMS 길이 초과 가능성 항상 명시 입력 (90바이트 이하로 짧게)

WARNING: SMS 대체의 함정 — recontent를 비워두면 원본 본문을 사용하지만, 본문이 SMS 90바이트를 초과하면 발송되지 않습니다. SMS 대체는 항상 짧은 본문으로 별도 작성하세요.

결과 매핑

대체 발송이 실제로 발생하면 결과 리포트는 추가 레코드로 생성됩니다. refkey로 원본 트랜잭션을 매핑하고, 결과 코드 분기(WAPINFO(SKT/KTF/LGT/KAO) · RESEND_FLAG)로 어떤 채널에서 도달했는지 식별하세요.

운영 권장

  1. 대체 발송 활성화 신청 — 비즈뿌리오 계정에 사용 권한 사전 확인
  2. 대체 본문 별도 작성 — 알림톡 1300자 본문이 SMS 90바이트로 잘리지 않게 별도 작성
  3. refkey 매핑 — 결과 수신 시 대체 발송 분기에 대비
  4. 트래픽 비용 — 알림톡 대비 SMS는 단가가 높으므로 대체 발송율 모니터링

재발송 결정 트리

"재발송이 필요"하다는 요구사항이 들어왔을 때:

본 발송이 아직 발생하지 않았는가?예 — 설계 단계대체 발송 (RESEND) 함께 등록아니오고객사가 발송 결과(리포트)를 받지 못했는가?예 — 발송 후 35일 이내 (비즈뿌리오 보관 중)결과 재요청 — POST /v2/report예 — 35일 경과비즈뿌리오 [발송 조회]에서 확인

Rate Limit

비즈뿌리오 API는 기준 시간 내 호출 가능 횟수가 제한됩니다. 제한을 초과하면 HTTP 429와 함께 code: 5002가 반환됩니다.

NOTE: Rate Limit 카운트 대상: 토큰 발급 / 메시지 발송 / 결과 재요청 / 파일 업로드 — 모든 API 요청이 카운트됩니다.

응답 헤더 — RateLimit-*

성공·실패 응답 모두 다음 헤더가 포함됩니다.

헤더 의미
RateLimit-Limit 기준 시간 내 최대 요청 가능 횟수
RateLimit-Remaining 기준 시간 내 남은 요청 가능 횟수
RateLimit-Reset 기준 시간 갱신까지 남은 시간 (ms)

초과 시 응답

HTTP/1.1 429 Too Many Requests
Content-type: application/json
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 0.299

{
  "code": 5002,
  "description": "too many requests",
  "refkey": "test1234"
}

백오프 — RateLimit-Reset 활용

429 응답 시 RateLimit-Reset 헤더 값만큼 대기 후 재시도하는 것이 가장 정확합니다.

response = post(...)
if response.status == 429:
    sleep(response.headers["RateLimit-Reset"] + 여유분)
    retry()

재시도 간격은 충분히 늘려 제한 값에 다시 도달하지 않게 하고, RateLimit-Remaining이 0에 가까워지면 호출 측에서 미리 속도를 낮추세요. 헤더를 활용하기 어려운 환경에서는 일반적인 지수 백오프(시도마다 대기 2배 + jitter, 상한 30초)를 적용합니다.

운영 권장

  1. 토큰 캐싱 — 토큰은 24시간 유효하므로 매 요청마다 발급하면 Rate Limit을 빨리 소진합니다.
  2. 동시성 제한 — 무제한 병렬 호출 대신 동시 호출 수를 제한하세요 (세마포어·커넥션 풀).
  3. 대량 발송은 큐로 분산 — 큐에 적재 후 워커가 일정 속도로 소비하고, 429 발생 건은 재시도 큐로 복귀시키세요.

제한 상향 신청

기본 Rate Limit이 부족하면 비즈뿌리오 고객센터로 상향 요청 가능. 다음 정보를 함께 전달:

  • 비즈뿌리오 계정 (bizId)
  • 사용 시나리오 (트랜잭션·캠페인·채널 종류)
  • 예상 일/시간당 발송 건수
  • 피크 시간대

관련 코드

코드 HTTP 설명 권장 처리
5002 429 Rate Limit 초과 RateLimit-Reset 만큼 백오프
5004 503 너무 많은 커넥션 짧은 백오프 (1~5초)
5003 502 인프라 일시 오류 재시도 (지수 백오프)
5005 504 게이트웨이 타임아웃 재시도 (지수 백오프)

전체 코드는 BIZAPI 응답 상태 코드 참고.

이미지 업로드

MMS는 이미지를 본문에 첨부하는 메시지입니다. 파일 본체는 별도 엔드포인트로 사전 업로드하고, MMS 발송 시에는 발급받은 filekey만 참조하는 2단계 흐름입니다.

흐름

① POST /v2/filefilekey 발급② POST /v3/message (mms)content.mms.file[].key = filekeytype: "IMG"③ 결과 수신

1단계 — 파일 업로드

제약

항목 값
Content-Type multipart/form-data
확장자 jpg, jpeg
크기 300 KB 이하
1회 업로드 1개 (3장 첨부 시 3번 호출)

호출

curl -X POST https://api.bizppurio.com/v2/file \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "account=bizUserId001" \
  -F "sendtime=1640962800" \
  -F "file=@1.jpg"

응답

{
  "filekey": "0920msg_123912934949595969"
}

sendtime 미입력 시 현재 시각으로 처리. 업로드 후 +1일 이내에만 사용 가능.

2단계 — MMS 발송

업로드 응답의 filekey를 content.mms.file[].key에 사용:

{
  "account": "bizUserId001",
  "refkey": "promo-2026042801",
  "type": "mms",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "mms": {
      "subject": "신상 출시 안내",
      "message": "신상품을 만나보세요!",
      "file": [
        { "type": "IMG", "key": "0920msg_123912934949595969" },
        { "type": "IMG", "key": "0920msg_123912934949595970" },
        { "type": "IMG", "key": "0920msg_123912934949595971" }
      ]
    }
  }
}
필드 값
content.mms.file 최대 3개
content.mms.file[].type 현재 IMG만 지원
content.mms.file[].key /v2/file 응답의 filekey
content.mms.message 선택 — 이미지만 발송도 가능

자세한 사양은 MMS 채널 · MMS 파일 업로드 API 참고.

운영 권장 — 이미지 캐싱

같은 이미지를 반복 발송할 때마다 업로드하면 비효율적입니다.

고객사 DBimage_id · file_url · bizppurio_filekey · uploaded_at발송 시filekey가 있고 발급 +1일 이내인가?예filekey 그대로 사용 — 업로드 생략아니오POST /v2/file — 새 filekey 발급DB에 filekey · 발급시각 갱신

filekey는 발급 시점 기준 +1일 이내에만 사용 가능하므로 캐시할 수 있습니다.

브랜드메시지 이미지는 다른 흐름

채널 이미지 등록 방법 참조 필드
MMS POST /v2/file → filekey content.mms.file[].key
브랜드메시지 (BT) KAPI 브랜드메시지 이미지 업로드 (/v4/brand/image/...) content.<type>.image.img_url
RCS RAPI 파일 등록 → fileId content.rcs.message.media = "maapfile://{fileId}"

자주 발생하는 문제

증상 원인·해결
code: 3014 (데이터 포맷 에러) file[]이 비어있음 — MMS는 file 필수
9019 지원하지 않는 첨부파일 확장자 / 크기 검증
9027 MMS 첨부파일 이미지 사이즈 초과 300KB 초과
9017 존재하지 않는 첨부파일 filekey 만료 (1일 경과)
9018 0바이트 첨부파일 파일 손상 — 다시 업로드

국제 메시지

해외 수신자에게 메시지를 발송할 때는 국가 코드, 인코딩(GSM vs 유니코드), 채널별 제약을 모두 고려해야 합니다.

채널별 길이 제한

채널 길이 제한 인코딩
sms 최대 140 byte GSM 표준 1byte/자, 유니코드 2byte/자
lms 최대 420 byte 동일
at (알림톡) 한글/영문 1000자 —

WARNING: SMS/LMS는 메시지에 유니코드 1자라도 포함되면 전체가 유니코드 기준으로 처리됩니다 (140byte → 70자, 420byte → 200자).

GSM 캐릭터 셋

sms/lms 국제 발송에서 1byte로 처리되는 문자입니다.

분류 1자 byte 예시
GSM 표준 1 ! " # $ % ' ( ) * + , - . / : ; < = > ? @ _, 숫자, 영문 대소문자, Ä Å Æ Ç É Ñ Ø ø Ü ß Ö à ä å æ è é ì ñ ò ö ù ü Δ Φ Γ Λ Ω Π Ψ Σ Θ Ξ
GSM 확장 2 | ^ € { } [ ] ~ \

인코딩 예시

메시지 문자당 byte 총 byte
Bonjour monde 1 13
This ^ That ^만 2byte (확장) 12
안녕하세요 2 (유니코드) 10
안녕 DAOU 전체 유니코드 (1자라도 포함되면) 14

수신 번호 표기 — 두 가지 방식

방식 1: to에 국가 코드 포함

{ "to": "00211012345678" }   // 미국(1) + 01012345678

00 또는 + 접두 없이 국제 표기 그대로.

방식 2: country 파라미터 분리

{
  "country": "1",
  "to": "01012345678"
}

이 방식이 가독성이 좋고, 알림톡에서는 이 방식만 사용 가능합니다.

채널별 국제 발송 지원

메시지 유형 country 파라미터 대체 발송
sms / lms ✓ —
at / ai ✓ sms / lms 대체 가능
mms (사양 제한) —
rcs 미지원 —
ntalk 미지원 —

운영 권장

  1. 국가별 단가 — 비즈뿌리오 고객센터에 사용 국가별 단가 사전 확인
  2. 본문 길이 검증 — 국제 SMS는 70자 컷 (유니코드)이 빈번하므로 호출 전 byte 계산
  3. 수신 번호 정규화 — 사용자 입력에서 +, -, () 등 제거 후 국가 코드 분리
  4. 알림톡 국제 발송 — 카카오톡 자체가 국제 사용 가능하므로 효율적이지만, 수신자가 카카오톡 사용자여야 함
  5. 시간대 고려 — sendtime은 한국 표준시(GMT+9) 기준 — 해외 시간대로 발송 시 환산 필요

발송 예시

SMS — 미국

{
  "type": "sms",
  "from": "07000000000",
  "country": "1",
  "to": "01012345678",
  "content": { "sms": { "message": "Hello from Bizppurio." } }
}

LMS — 일본

{
  "type": "lms",
  "from": "07000000000",
  "country": "81",
  "to": "9012341234",
  "content": {
    "lms": {
      "subject": "お知らせ",
      "message": "ビズプリオから日本のお客様向けのメッセージです。"
    }
  }
}

(일본어는 유니코드 — 200자까지)

알림톡 + SMS 대체 (해외)

{
  "type": "at",
  "country": "1",
  "to": "01012345678",
  "content": { "at": { "senderkey": "...", "templatecode": "...", "message": "..." } },
  "resend": { "first": "sms" },
  "recontent": { "sms": { "message": "Backup SMS for international." } }
}

결과 수신

비즈뿌리오 발송 결과(통신사·카카오·RCS의 도달 결과)를 받는 방법은 Webhook과 Polling 두 가지입니다.

방식 적용 설명
Webhook (URL Push) API 권장 비즈뿌리오 → 고객사 URL로 결과 PUSH
Polling API (옵션) 고객사가 주기적으로 결과 조회 — 사전 신청 필요

Webhook (URL Push) — API 권장

비즈뿌리오 서버가 결과를 고객사가 사전 등록한 URL로 PUSH합니다.

흐름

고객사 서버결과 수신 URL (사전 등록)비즈뿌리오 서버POST {등록 URL} — application/jsonDEVICE · CMSGID · MSGID · PHONE · MEDIA · RESULT · REFKEY …200 OK 응답

사전 준비

Webhook (URL Push)를 사용하려면 결과 수신 URL(IP/PORT)을 비즈뿌리오에 사전 등록해야 합니다. 비즈뿌리오 사이트 [내 정보] → [API 관리] 또는 고객센터로 등록 요청.

항목 값
URL 예시 https://yourdomain.com/api/bizppurio/result
포트 443 / 80 외 포트는 별도 방화벽 허용 신청 필요

운영 권장

  1. HTTPS 권장 — HTTP는 결과 데이터가 평문으로 노출됨
  2. HTTP 200 OK 즉시 반환 — 처리는 비동기로 큐에 넣고 우선 200 응답
  3. 멱등성 — 같은 MSGID가 두 번 들어와도 중복 처리되지 않도록
  4. REFKEY로 원본 매칭 — 고객사 내부 트랜잭션과 매칭
  5. 인증 — 비즈뿌리오는 별도 인증 헤더를 보내지 않음. URL 자체에 시크릿 토큰을 포함하거나 IP 화이트리스트(고정 IP)로 보호
  6. 누락 복구 — 일정 주기로 결과 재요청 호출하여 누락분 복구

키 컨벤션 주의

Webhook 모두 대문자 (DEVICE, MSGID, RESULT)
Polling 응답 모두 소문자 (device, msgid, result)

같은 의미의 같은 데이터지만 키 케이스가 다릅니다. 두 방식을 함께 쓴다면 정규화 필요.

Polling — API (옵션)

고객사가 주기적으로 결과를 조회하는 방식. 사전 신청 필요.

흐름

고객사 서버비즈뿌리오 서버① POST /v1/result/request② 최대 1000개 결과 응답결과 처리③ POST /v1/result/confirm — 처리 완료 표시 (필수)confirm 누락 시 같은 결과가 다음 polling에서 재응답

WARNING: /v1/result/confirm 호출 누락하면 같은 결과가 다음 polling에서 계속 응답됩니다. 3일 내 처리 안 하면 결과 데이터는 제거됩니다.

Webhook vs Polling 비교

항목 Webhook Polling
도달 방향 비즈뿌리오 → 고객사 고객사 → 비즈뿌리오
인프라 요구 공개 가능한 수신 URL 필요 호출 가능한 outbound만
지연 즉시 폴링 주기에 따름
사전 신청 필요 (URL 등록) 필요 (Polling 사용 신청)
누락 복구 결과 재요청으로 복구 정기 polling으로 복구
권장 환경 DMZ 외부 통신 가능 폐쇄망·아웃바운드 only

자세한 사양은 전송 결과 조회 참고.

결과 재요청 (/v2/report)

Webhook 수신 서버가 일시 다운되었거나 결과를 잃어버렸을 때, 비즈뿌리오 서버에 보관된 결과를 Webhook URL로 다시 PUSH하도록 요청합니다. 새 발송이 일어나지 않습니다.

curl -X POST https://api.bizppurio.com/v2/report \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-type: application/json" \
  -d '{
    "account": "bizUserId001",
    "messagekey": "190922175225820#ft002951seXXXXXX"
  }'

응답은 단순 성공/실패이며, 실제 결과는 등록된 Webhook URL로 PUSH됩니다.

  • 비즈뿌리오 보관 주기 35일 경과 메시지는 조회 불가 (code: 3012)
  • 통신사로부터 결과 미수신 상태인 메시지는 조회 불가 (code: 3013)
  • Polling 방식은 별도로 결과 요청 사용

자세한 사양은 전송 결과 재요청 참고.

결과 코드 분류

코드 범위 채널 의미
4100 SMS 정상 전달
6600 LMS/MMS 정상 전달
7000 카카오 (AT/FT/BT) 정상
8000 RCS 정상
5000 NTALK 정상
그 외 채널별 실패 사유 발송 결과 코드
9000 시리즈 공통 실패 사유 코드

운영 패턴 — 단일 결과 수집 파이프라인

세 방식 모두 일관된 결과 데이터 모델로 통합하면 다운스트림 코드가 단순해집니다.

Webhook 수신 핸들러Polling 워커정규화 모듈키 케이스 통일코드 → 의미 매핑REFKEY 기반 트랜잭션 매핑고객사 결과 테이블

자주 발생하는 문제

증상 원인·해결
Webhook이 도달하지 않음 URL/IP 등록 확인, 방화벽 인바운드 허용
Webhook 중복 도달 정상 동작 — 멱등성으로 처리
Polling 결과가 항상 같음 /v1/result/confirm 호출 누락

첨부 파일 규격

채널별로 지원하는 첨부파일 포맷과 크기 제한입니다.

채널별 지원 포맷

채널 카테고리 지원 포맷
MMS Image jpg
FAX Docs doc, docx, xls, xlsx, ppt, pptx, hwp, pdf, txt, html
Image bmp, gif, jpg, png

채널별 크기 제한

채널 항목 제한
MMS 이미지 1개 300 KB 이하 (MMS 파일 업로드)
MMS 첨부 개수 최대 3개

RCS 미디어

RCS는 별도의 이미지·동영상 등록 절차를 사용합니다.

항목 사양
이미지 등록 비즈뿌리오 사이트 [메시지관리] → [RCS 관리] → [RCS 이미지 관리]
이미지 유효기간 등록일로부터 365일 (자동 삭제)
이미지 URL 포맷 maapfile://{fileId}
동영상 URL 형식 YouTube 3가지 형식 + ,maapfile://{썸네일 fileId}

자세한 RCS 미디어 사양은 RCS 채널 페이지를 참고하세요.

RCS 연동 규격

메시지 API(type: rcs)로 발송하는 RCS의 상세 규격입니다. RCS는 안드로이드 RCS(채팅+ 지원 단말)와 통합 RCS(이통 3사 표준 규격) 두 체계로 구분되며, messagebaseid 값으로 메시지 유형이 결정됩니다.

사전 준비: ① RCS 브랜드 개설·대행사 설정 (RCS 비즈센터) → ② RCS 브랜드 등록 (비즈뿌리오) → ③ 발신번호·템플릿 등록/승인

MESSAGEBASE_ID

messagebaseid 는 메시지 포맷(카드 유형)을 지정하는 코드입니다. 통합 RCS는 단말 제조사와 무관하게 국내 이통 3사에서 제공하는 RCS 표준 규격입니다(안드로이드 10 이상, iOS 26 이상 지원). 상품 타입·발송 변수는 안드로이드 RCS와 동일하지만 아래 항목이 다릅니다.

항목 안드로이드 RCS 통합 RCS
수신 가능 단말 안드로이드 채팅+ 지원 단말 (예: 삼성 갤럭시) 국내 이통사 RCS 연동 모든 단말
(광고) 표기 header: "1" 설정 header는 "0"만 허용 ("1" 입력 시 실패) — 타이틀·본문에 직접 표기, 글자 수에 포함
무료수신거부 표기 footer 설정 footer 미사용 — 본문 끝에 직접 표기, 글자 수에 포함
copyallowed 지원 (메시지별 복사 가능 여부 설정) 미지원 (단말 정책에 따름)
오픈리치카드 지원 미지원

안드로이드 RCS

안드로이드 채팅+ 지원 단말(예: 삼성 갤럭시)에서 수신 가능한 표준 포맷입니다.

MESSAGEBASE ID 메시지 유형 카드(형태) 카드 장수 카드별 최대 버튼 수 최대 본문 글자 수
SS000000 SMS Standalone 1 1 100
SL000000 LMS Standalone 1 3 1,300
SMwThT00 MMS 세로형(Tall) 1 2 1,300
SMwThM00 MMS 세로형(Medium) 1 2 1,300
CMwMhM0200 MMS 슬라이드형(Medium, 2장) 2 2 글자/라인 수 정의*
CMwMhM0300 MMS 슬라이드형(Medium, 3장) 3 2 글자/라인 수 정의*
CMwMhM0400 MMS 슬라이드형(Medium, 4장) 4 2 글자/라인 수 정의*
CMwMhM0500 MMS 슬라이드형(Medium, 5장) 5 2 글자/라인 수 정의*
CMwMhM0600 MMS 슬라이드형(Medium, 6장) 6 2 글자/라인 수 정의*
CMwShS0200 MMS 슬라이드형(Small, 2장) 2 2 글자/라인 수 정의*
CMwShS0300 MMS 슬라이드형(Small, 3장) 3 2 글자/라인 수 정의*
CMwShS0400 MMS 슬라이드형(Small, 4장) 4 2 글자/라인 수 정의*
CMwShS0500 MMS 슬라이드형(Small, 5장) 5 2 글자/라인 수 정의*
CMwShS0600 MMS 슬라이드형(Small, 6장) 6 2 글자/라인 수 정의*
OMHITV0001 신규 MMS 이미지 & 타이틀 강조형 (3:4) 1 2 150
OMHITS0001 신규 MMS 이미지 & 타이틀 강조형 (1:1) 1 2 150
OMHIMV0001 신규 MMS 이미지 강조형 (3:4) 1 2 150
OMHIMS0001 신규 MMS 이미지 강조형 (1:1) 1 2 150
OMTBNV0001 신규 MMS 썸네일형 (세로) 1 2 150
OMTBNH0001 신규 MMS 썸네일형 (가로) 1 2 150
OMSNSS0001 신규 MMS SNS형 1 2 150
OMSNSH0001 신규 MMS SNS형 (중간버튼) 1 2 150
UBR.로 시작 (템플릿별 상이) 템플릿 서술(description) 1 2 90
UBR.로 시작 (템플릿별 상이) 템플릿 스타일(cell) 1 2 90
UBR.로 시작 (템플릿별 상이) 템플릿 기본(free) 1 0 90
IBR.로 시작 (템플릿별 상이) 이미지 템플릿 신규 MMS 동일 (8종) 1 2 1,000
LBR.로 시작 (템플릿별 상이) LMS 템플릿 LMS 템플릿 (4종) 1 2 1,300

템플릿(UBR./IBR./LBR.) 은 RBC에 등록한 RCS 템플릿입니다. UBR.(텍스트)은 정보성 전용으로 고정부+변수부 합산 90자 초과 시 전송 불가, IBR.(이미지)는 media 파라미터 입력이 불필요합니다.

글자수 및 라인수 정의 (슬라이드형 CMw…)

  • 글자 수: 1줄당 정상적으로 표현 가능한 글자 수 (한글 '가' 기준 측정)
  • 줄(라인) 수: expand 없이 메시지 버블 최대 크기에서 표현 가능한 description 줄 수

LMS (Standalone, No media) — 글자 수: 타이틀 16 / 디스크립션 18 / 버튼명 17

줄 수 (접힌 경우) 버튼 0개 버튼 1개 버튼 2개 버튼 3개
디스크립션 only 28 26 24 22
타이틀 1줄 + 디스크립션 27 25 23 20
타이틀 2줄 + 디스크립션 26 23 21 19

MMS 세로형 (Standalone, Media Top) — 글자 수: 타이틀 16 / 디스크립션 18 / 버튼명 17

줄 수 — Media Tall (접힌 경우) 버튼 0개 버튼 1개 버튼 2개
디스크립션 only 9 8 6
타이틀 1줄 + 디스크립션 8 6 4
타이틀 2줄 + 디스크립션 7 5 3
줄 수 — Media Medium (접힌 경우) 버튼 0개 버튼 1개 버튼 2개
디스크립션 only 15 13 11
타이틀 1줄 + 디스크립션 14 12 10
타이틀 2줄 + 디스크립션 13 11 9

MMS 슬라이드형 Medium (Carousel Medium) — 글자 수: 타이틀 13 / 디스크립션 14 / 버튼명 13

줄 수 — Media 없음 (RCS A2P 단말 기준) 버튼 0개 버튼 1개 버튼 2개
디스크립션 only 28 26 23
타이틀 1줄 + 디스크립션 27 25 23
타이틀 2줄 + 디스크립션 26 23 21
타이틀 3줄 + 디스크립션 24 22 20
줄 수 — Media Medium (RCS A2P 단말 기준) 버튼 0개 버튼 1개 버튼 2개
디스크립션 only 17 15 13
타이틀 1줄 + 디스크립션 16 14 12
타이틀 2줄 + 디스크립션 15 13 11
타이틀 3줄 + 디스크립션 14 12 10

MMS 슬라이드형 Small (Carousel Small) — 글자 수: 타이틀 5 / 디스크립션 6 / 버튼명 5

줄 수 — Media Short (RCS A2P 단말 기준) 버튼 0개 버튼 1개 버튼 2개
디스크립션 only 20 18 16
타이틀 1줄 + 디스크립션 19 17 15
타이틀 2줄 + 디스크립션 18 16 14
타이틀 3줄 + 디스크립션 17 15 13
타이틀 4줄 + 디스크립션 16 14 12
타이틀 5줄 + 디스크립션 15 13 11

통합 RCS

통합 RCS는 단말 제조사와 무관하게 국내 이통 3사에서 제공하는 RCS 표준 규격입니다.

MESSAGEBASE ID 상품 유형명 최대 버튼 수 최대 본문 글자 수
RPSSAXX001 RCS SMS 통합 SMS 카드 1 100
RPLSAXX001 RCS LMS 통합 LMS 카드 3 1,300
RPMSMMX001 RCS MMS 통합 MMS 카드 M 2 1,300
RPMSMTX001 RCS MMS 통합 MMS 카드 T 2 1,300
브랜드별 자동 발급* 텍스트 템플릿 통합 프리 템플릿 — 90
템플릿 등록 필요 텍스트 템플릿 통합 정보성 템플릿 — 90
템플릿 등록 필요 이미지 템플릿 통합 이미지 템플릿 M — 1,000
템플릿 등록 필요 이미지 템플릿 통합 이미지 템플릿 T — 1,000

* 통합 프리 템플릿: 브랜드마다 1개 자동 발급되는 정보성 템플릿으로, 사전 등록 없이 사용합니다. messagebase ID는 RBC 템플릿 목록에서 확인하세요. 기존 발급된 프리 템플릿은 2026-07-31까지 병행 이용 가능합니다.

MESSAGE

메시지 베이스에서 치환할 본문 객체입니다. messagebaseid에 따라 필드 구성이 달라집니다.

  • 단일 카드: title, description, media
  • 캐러셀: title1/description1/media1, title2/… (카드 순서대로 넘버링)
  • 신규 MMS / 통합 RCS: subTitle1/subDesc1, subMedia1/subMediaUrl1 등
  • 텍스트 템플릿(UBR.~): 템플릿 변수 키/값 자유 형태

이미지 첨부 media

maapfile://{fileId} 형식으로 입력합니다 (예: maapfile://BR.i6dOpSm8N8.20200302150000.001). 이미지는 비즈뿌리오 사이트의 [메시지관리 → RCS 관리 → RCS 이미지 관리]에서 등록하며, 등록일로부터 365일간 발송 가능합니다 (이후 자동 삭제).

동영상 스트리밍 첨부 media

RCS MMS는 media 필드에 이미지 대신 YouTube 스트리밍 URL을 입력해 동영상을 첨부할 수 있습니다. 아래 3가지 형태의 YouTube URL만 지원하며, 정확한 형식을 준수해야 합니다 (일부만 일치해도 실패).

  • https://www.youtube.com/watch?v=[videoId]
  • https://youtu.be/[videoId]
  • https://m.youtube.com/watch?v=[videoId]

썸네일은 등록된 이미지(maapfile://{fileId})만 사용 가능하며, YouTube URL 뒤에 콤마(,)로 이어서 입력합니다. 콤마 외 공백이 포함되면 실패합니다.

"media": "https://www.youtube.com/watch?v=[videoId],maapfile://{썸네일용 fileId}"

동영상 발송 시 Footer에 '동영상 재생 시 데이터 요금제가 적용됩니다.' 문구가 자동 삽입됩니다.

BUTTON

button 은 버튼 배열입니다(캐러셀은 카드별 객체, 버튼 없는 카드는 {}로 순서 유지). 각 suggestions[].action 은 아래 7종 중 정확히 1개만 포함하며, displayText(출력 텍스트)와 선택적 postback.data(챗봇 콜백)를 가집니다.

# Action 동작 중첩 필드
1 urlAction URL 연결 openUrl → url
2 dialerAction 전화 걸기 dialPhoneNumber → phoneNumber
3 mapAction 지도 보여주기 showLocation → location(latitude/longitude/label)
4 mapAction 위치 공유 requestLocationPush
5 composeAction 메시지 전송 composeTextMessage → phoneNumber/text
6 calendarAction 캘린더 등록 createCalendarEvent → startTime/endTime/title/description
7 clipboardAction 복사 copyToClipboard → text

필드 레벨 스키마·예시는 RCS 발송의 요청 본문을 참고하세요.

카카오 연동 규격

참고
알림톡과 브랜드메시지는 사용 가능한 버튼 타입이 다릅니다. 각 발송 페이지에서 이 규격을 참조합니다.

알림톡 버튼

type설명사용 가능 파라미터필수 파라미터
WL지정한 웹 링크로 이동name
type
url_mobile
url_pc		name
type
url_mobile
AL지정한 앱 스킴 또는 웹 링크로 이동name
type
scheme_android
scheme_ios
url_mobile
url_pc		name
type
(다음 중 2가지 이상)
scheme_android
scheme_ios
url_mobile
DS버튼 클릭 시 배송조회 페이지로 이동name
type		name
type
BK해당 버튼 텍스트 발송name
type		name
type
MD해당 버튼 텍스트 + 메시지 본문 발송name
type		name
type
BC상담톡을 이용하는 카카오톡 채널만 이용 가능name
type
chat_extra		name
type
BT카카오 i 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용 가능name
type
chat_extra
chat_event		name
type
AC버튼 클릭 시 카카오톡 채널 추가name
type		name
type
P1이미지 보안 전송 플러그인name
type		name
type
P2개인정보이용 플러그인name
type		name
type
P3원클릭 결제 플러그인name
type		name
type
(다음 중 1가지 이상)
oneclick_id
product_id
BF카카오 비즈니스폼을 실행name
type
biz_form_id		name
type
biz_form_id
TN전화 앱 실행
모바일 환경에서만 이용 가능		name
type
tel_number		name
type
tel_number
MP버튼 클릭 시 지도 보기name
type
map_address
map_coordinates		name
type
(다음 중 1가지 이상)
map_address
map_coordinates

알림톡 바로연결

바로연결은 WL·AL·BK·BC·BT·BF 6종만 지원합니다.

type설명사용 가능 파라미터필수 파라미터
WL지정한 웹 링크로 이동name
type
url_mobile
url_pc		name
type
url_mobile
AL지정한 앱 스킴 또는 웹 링크로 이동name
type
scheme_android
scheme_ios
url_mobile
url_pc		name
type
(다음 중 2가지 이상)
scheme_android
scheme_ios
url_mobile
BK해당 버튼 텍스트 발송name
type		name
type
BC상담톡을 이용하는 카카오톡 채널만 이용 가능name
type
chat_extra		name
type
BT카카오 i 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용 가능name
type
chat_extra
chat_event		name
type
BF카카오 비즈니스폼을 실행name
type
biz_form_id		name
type
biz_form_id

브랜드메시지 선택 가이드

브랜드메시지 8종 타입(UT/UI/UW/UL/UC/UM/UP/UA)은 동일한 페이로드 구조를 사용하며, 4가지만 정하면 발송할 수 있습니다.

STEP 1. 누구에게?
대상sendtargettargeting사전 준비
고객사 회원(광고 수신동의)marketing필수 (M/N/O)발송 권한 신청
채널 친구friend미사용발신프로필 등록
STEP 2. 템플릿을 쓰나?
형태brandmessagetypetemplatecode다음
기본형(템플릿 O)BASIC필수STEP 3
자유형(템플릿 X)FREE없음STEP 4 (본문 직접)
STEP 3. (기본형) 변수·본문 작성 방식

발송 페이지 스키마 탭에서 선택합니다.
· 변수 미사용(BASIC): 변수 필드 생략
· 변수 분리(BASIC): *variable(messagevariable / buttonvariable / couponvariable / imagevariable / videovariable / commercevariable / carouselvariable) 사용
· 전문 방식(BASIC): message / button / coupon / image / header / item / carousel / commerce / video / additionalcontent 직접 구성

STEP 4. 자유형(FREE)

템플릿·templatecode 없이 본문을 직접 구성합니다(본문 필드는 전문 방식과 동일).

브랜드메시지 타겟팅

고객사 회원 대상

고객사 회원 대상은 사전 발송 권한 신청이 필요합니다. targeting 값(M/N/O)으로 광고 수신동의 회원과 채널 친구의 교집합 범위를 지정합니다.

고객사발송 대상채널친구M고객사발송 대상채널친구N고객사발송 대상채널친구O

M — 고객사의 광고성 정보 수신동의 회원: 광고성 정보 수신동의 회원(카카오톡 수신 동의) 전체에 발송합니다. 무료수신거부 정보는 발송 채널의 발신프로필에서 등록·관리합니다.
N — 수신동의 회원 − 채널 친구: 수신동의 회원에서 채널 친구를 제외하고 발송합니다.
O — 수신동의 회원 ∩ 채널 친구: 수신동의 회원 중 채널 친구인 경우에만 발송합니다. 채널의 수신거부 방법으로 080 무료수신거부 번호를 안내합니다.

채널 친구 대상

채널 친구 대상은 발신프로필 등록 후 바로 발송할 수 있습니다. 채널 친구 중 고객사의 발송 요청 대상에만 발송하며, 채널의 수신거부 방법으로 채널 차단 정보를 안내합니다.

브랜드메시지 타입별 구성

타입별로 실제 메시지에 그려지는 구성 요소와 배치입니다(고객사 회원 대상·채널 친구 대상 동일). 각 박스의 이름은 전문 방식 본문 필드명입니다. 이미지·동영상은 발송 전 사전 등록이 필요합니다.

텍스트 UT · TEXT
message
attachment.button
attachment.coupon
  • 메시지 필수 (최대 1,300자)
  • 버튼·쿠폰 선택
이미지 UI · IMAGE
attachment.image
message
attachment.button
attachment.coupon
  • 이미지·메시지 필수 (메시지 최대 1,300자)
  • 버튼·쿠폰 선택
  • KAPI 이미지 사전 등록
와이드 이미지 UW · WIDE
attachment.image
(와이드)
message
attachment.button
attachment.coupon
  • 와이드 이미지·메시지 필수 (메시지 최대 76자)
  • 버튼·쿠폰 선택
  • KAPI 이미지 사전 등록
와이드 아이템 리스트 UL · WIDE_ITEM_LIST
header
1번
attachment.item.list
2번 · item.list
3번 · item.list
4번 · item.list
attachment.button
attachment.coupon
  • 헤더·아이템 리스트(최소 3, 최대 4) 필수
  • 버튼·쿠폰 선택
  • KAPI 이미지 사전 등록
커머스 UM · COMMERCE
attachment.image
attachment.commerce
additional_content
attachment.button
attachment.coupon
  • 커머스 이미지·커머스 요소 필수
  • (커머스 요소 중 title·regular_price 필수)
  • 부가 정보·버튼·쿠폰 선택
  • KAPI 이미지 사전 등록
프리미엄 동영상 UP · PREMIUM_VIDEO
attachment.video
header
message
attachment.button
attachment.coupon
  • 비디오 필수
  • 헤더·메시지·버튼·쿠폰 선택
  • 비즈뿌리오 웹 또는 KAPI에서 비디오 사전 등록
캐러셀 피드 UC · CAROUSEL_FEED
1번
carousel
.list
2번
carousel
.list
···
더보기
carousel
.tail
  • 캐러셀 리스트(최소 2, 최대 6) 필수
  • 더보기 선택
  • KAPI 이미지 사전 등록
캐러셀 커머스 UA · CAROUSEL_COMMERCE
인트로
carousel
.head
1번
carousel
.list
···
더보기
carousel
.tail
  • 캐러셀 리스트 필수 · 인트로·더보기 선택
  • 인트로 사용 시 리스트 1~5개, 미사용 시 2~6개
  • KAPI 이미지 사전 등록

브랜드메시지 버튼

알림톡과 달리 AC·WL·AL·BK·MD·BC·BT·BF 8종만 지원하며, 비즈니스폼은 biz_form_key(알림톡은 biz_form_id)를 사용합니다.

type설명사용 가능 파라미터필수 파라미터
AC버튼 클릭 시 카카오톡 채널 추가
강조형 버튼(노란색)으로 표기
name은 '채널 추가' 고정
캐러셀형은 전체 1개만 가능
타겟팅 M·N만 사용 가능		name
type		name
type
WL지정한 웹 링크로 이동name
type
url_mobile
url_pc		name
type
url_mobile
AL지정한 앱 스킴 또는 웹 링크로 이동name
type
scheme_android
scheme_ios
url_mobile
url_pc		name
type
(다음 중 2가지 이상)
scheme_android
scheme_ios
url_mobile
BK해당 버튼 텍스트 발송name
type		name
type
MD해당 버튼 텍스트 + 메시지 본문 발송name
type		name
type
BC상담톡을 이용하는 카카오톡 채널만 이용 가능name
type
chat_extra		name
type
BT카카오 i 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용 가능name
type
chat_extra
chat_event		name
type
BF카카오 비즈니스폼을 실행
강조형 버튼(노란색)
name은 '톡에서 예약/설문/응모하기' 중 사용		name
type
biz_form_key		name
type
biz_form_key

브랜드메시지 타입별 사용 필드

기본형(BASIC) 메시지에서 변수 영역을 채우는 방식은 변수 분리 방식과 전문 방식 두 가지입니다. 변수가 존재하는 영역의 정보만 전달하며, 고객사 회원 대상·채널 친구 대상이 동일합니다.

메시지 타입변수 분리 방식전문 방식
TEXTmessagevariable
buttonvariable
couponvariable		message
button
coupon
IMAGEmessagevariable
buttonvariable
couponvariable
imagevariable		message
button
coupon
image
WIDEmessagevariable
buttonvariable
couponvariable
imagevariable		message
button
coupon
image
WIDE_ITEM_LISTmessagevariable
buttonvariable
couponvariable
imagevariable		header
item.list
button
coupon
CAROUSEL_FEEDcarouselvariable[]
(내부: message/button/coupon/image variable)		carousel.list[].header
carousel.list[].message
carousel.list[].attachment
PREMIUM_VIDEOmessagevariable
buttonvariable
couponvariable
videovariable		header
message
video
button
coupon
COMMERCEmessagevariable
buttonvariable
couponvariable
commercevariable
imagevariable		additionalcontent
button
coupon
commerce
image
CAROUSEL_COMMERCEcarouselvariable
(인트로/리스트 각 variable)		carousel.head
carousel.list[].additional_content
carousel.list[].attachment
변수 분리 방식 vs 전문 방식 — 예시 비교 (COMMERCE)

같은 COMMERCE 메시지를 두 방식으로 작성한 예시입니다. 공통 envelope와 brandmessagetype: BASIC·templatecode는 동일하며, content.<type> 안의 변수 영역 작성 방식만 다릅니다.

① 변수 분리 방식 — *variable 맵에 "템플릿 변수명": "치환값" 형태로 변수 영역만 전달합니다.

① 변수 분리 방식
{
  "account": "test",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "test",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "template",
      "targeting": "M",
      "messagevariable": {
        "부가정보": "부가정보"
      },
      "commercevariable": {
        "정상가격": "30000",
        "할인가격": "20000",
        "할인율": "10",
        "정액할인가격": "10"
      },
      "buttonvariable": {
        "모바일링크": "www.bizppurio.com"
      },
      "couponvariable": {
        "할인금액": "10",
        "모바일링크": "www.bizppurio.com"
      }
    }
  }
}

② 전문 방식 — 변수명 대신 실제 본문 필드(additionalcontent/image/commerce/button/coupon)를 직접 구성합니다.

② 전문 방식
{
  "account": "test",
  "refkey": "test1234",
  "type": "um",
  "from": "07000000000",
  "to": "01012345678",
  "content": {
    "um": {
      "senderkey": "test",
      "brandmessagetype": "BASIC",
      "sendtarget": "marketing",
      "templatecode": "template",
      "targeting": "M",
      "additionalcontent": "부가정보",
      "image": {
        "img_url": "{img_url}"
      },
      "commerce": {
        "regular_price": 30000,
        "discount_price": 20000,
        "discount_rate": 10
      },
      "button": [
        {
          "type": "WL",
          "url_mobile": "https://www.bizppurio.com"
        }
      ],
      "coupon": {
        "title": "10원 할인 쿠폰",
        "url_mobile": "https://www.bizppurio.com"
      }
    }
  }
}
TIP
언제 무엇을? — 사전 등록한 템플릿의 변수만 치환할 때는 변수 분리 방식(키가 곧 템플릿 변수명)이 간결합니다. 본문 구성요소를 직접 제어해야 할 때는 전문 방식을 사용합니다.