콘텐츠로 이동
U+ 메시지허브

2.4 카카오톡 메시지

목차

섹션 제목: “목차”

베이스 URL

섹션 제목: “베이스 URL”
구분접속 URL
상용https://api-send.msghub.uplus.co.kr
검수https://api-send.msghub-qa.uplus.co.kr

1. 알림톡 발송 V1.2

섹션 제목: “1. 알림톡 발송 V1.2”

카카오 알림톡을 발송합니다. 알림톡은 기업이 카카오톡을 통해 고객에게 중요한 정보를 전달할 수 있는 비대면 알림 서비스입니다.

📌 주의사항

섹션 제목: “📌 주의사항”
  1. 동보발송이란, 같은 내용의 메시지를 다수에게 동시에 보내는 발송 방식
  2. 메시지허브는 동보발송을 지원하며, 1건의 메시지에 최대 10명의 수신자를 추가하여 발송할 수 있습니다.
  3. TPS는 수신자 수 기준으로 처리됩니다. 예시) SMS 1건에 수신자 5명을 추가하여 발송시, TPS는 5입니다.
  4. 발신번호는 사전에 등록된 번호만 사용 가능합니다.
  5. 예약발송은 현재 시점으로부터 최대 30일까지 가능합니다.
  6. 템플릿 코드는 사전에 승인된 것만 사용 가능합니다.
  7. 버튼은 최대 5개까지 추가 가능합니다.
  8. 단축URL 사용 시 메시지 길이가 제한될 수 있습니다.
  9. fbInfoLst는 발송실패시, 대체발송에 대한 객체입니다. 대체발송 채널은 SMS, MMS만 지원하며, 메인 채널과 동일할 수 없습니다.

📌 버튼 타입 설명

섹션 제목: “📌 버튼 타입 설명”
타입설명필수 입력
WL웹링크url_mobile 필수, url_pc 선택
AL앱링크linkIos, linkAnd, linkMo 중 2개 이상 필수
BK봇 키워드해당 버튼 텍스트 전송
MD메시지 전달해당 버튼 텍스트 + 메시지 본문 전송
BC상담톡 전환상담톡 서비스를 이용하고 있을 경우 상담톡으로 전환
BT봇 전환채널 봇으로 전환
DS배송조회메시지 내 송장번호로 배송조회 페이지 연결 (quickReplies 사용 불가)
AC채널추가광고추가형/복합형 템플릿에서만 사용 가능, 버튼단톡 또는 첫번째 버튼에만 추가 가능 (quickReplies 사용 불가)

1) 요청 (Request)

섹션 제목: “1) 요청 (Request)”

URL

섹션 제목: “URL”
POST /kko/alimtalk/v1.2 HTTP/1.1

Headers

섹션 제목: “Headers”
NameType필수설명
AuthorizationString●사용자 인증 토큰
Content-TypeString●application/json

Request Body

섹션 제목: “Request Body”
NameType필수설명크기
clickUrlYnString-단축URL 사용여부 (Y/N)1자
resvYnString-예약발송 여부 (Y/N)1자
resvReqDtString-예약발송 시간 (ex. 2025-07-13 13:15)-
agencyObject-대행사 정보-
callbackString●발신번호20자
campaignIdString-캠페인 ID20자
deptCodeString-부서 코드20자
titleString-강조표기 메시지-
itemHeaderString-헤더-
itemHighlightTitleString-요약정보-
itemHighlightDescriptionString-요약내용-
msgString●메시지 내용1,000자
itemObject-아이템리스트 정보-
kkoChIdString●카카오채널 ID61자
tmpltCodeString●템플릿 코드-
serviceInteger-서비스 번호-
recvInfoLstArray●수신자 정보 목록10개
fbInfoLstArray-대체 발송 정보-
buttonsArray-버튼 리스트-
groupKeyString-알림톡 그룹키200자
item 객체
섹션 제목: “item 객체”
NameType필수설명크기
listArray●아이템리스트, 최소 2개, 최대 10개까지 가능-
list[].titleString●아이템리스트 타이틀6자
list[].descriptionString●아이템리스트 설명23자
summaryObject-아이템리스트 설명-
summary.titleString●타이틀6자
summary.descriptionString-설명 (변수 및 화폐 단위, 숫자, 쉼표, 마침표만 사용 가능)14자
buttons 객체
섹션 제목: “buttons 객체”
NameType필수설명크기
nameString●버튼이름14자
typeString●버튼타입2자
linkMoString-mobile 환경에서 버튼 클릭 시 이동할 url-
linkPcString-pc 환경에서 버튼 클릭 시 이동할 url-
linkAndString-mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme-
linkIosString-mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme-
orderingInteger-버튼 노출 순서-
varUrlYnString-URL 가변 값 포함 여부-
kkoBtnOutbrowserYnboolean-WL 버튼타입의 경우, 버튼 클릭시 url 이 열리는 브라우저 설정(true/false)-
chat_extraString-봇관련 정보(type:BC,BT)64자
chat_eventString-봇관련 이벤트정보(type:BT)64자

2) 응답 (Response)

섹션 제목: “2) 응답 (Response)”

Response Body

섹션 제목: “Response Body”
NameType설명
codeString결과 코드
messageString결과 메시지
dataArray결과 데이터 목록
data[].cliKeyString클라이언트 키
data[].msgKeyString메시지 키
data[].phoneString수신번호
data[].codeString결과 코드
data[].messageString결과 메시지

3) 요청 예시 (Sample)

섹션 제목: “3) 요청 예시 (Sample)”

Curl

섹션 제목: “Curl”
아이템리스트형 이외의 템플릿
섹션 제목: “아이템리스트형 이외의 템플릿”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/alimtalk/v1.2" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
        "clickUrlYn": "N",
        "resvYn": "N",
        "resvReqDt": "2025-07-13 13:15",
        "agency": {
          "kisaOrigCode": "123456789"
        },
        "callback": "0212341234",
        "title": "U+ Cloud 서비스 알림",
        "msg": "안녕하세요. #{name} 고객님.\n\nU+ Cloud서비스에서 설정하신 일일 사용량(1,000건) 초과 사용을 알려드립니다.\n\n※ 사용량 제한 및 기타 자세한 사항은 홈페이지 참조",
        "kkoChId": "@myservice",
        "tmpltCode": "TPnJhpG82k",
        "recvInfoLst": [
          {
            "cliKey": "test001",
            "phone": "01012341234",
             "mergeData": {
                "name": "홍길동"
             },
             "userCustomFields": {
                "key1": "value1",
                "key2": 123
             }
          },
          {
            "cliKey": "test002",
            "phone": "01056785678",
             "mergeData": {
                "name": "김철수"
             },
             "userCustomFields": {
                "key1": "value1",
                "key2": 123
             }
          }
        ],
        "buttons": [
          {
            "name": "사용량 제한 이용안내",
            "type": "WL",
            "url_mobile": "https://m.uplus.co.kr/cloud/usage",
            "url_pc": "https://www.uplus.co.kr/cloud/usage",
            "kkoBtnOutbrowserYn": true 또는 "true"
          },
          {
            "name": "포인트 전환하기",
            "type": "AL",
            "linkMo": "https://m.uplus.co.kr/point",
            "linkAnd": "upluscloud://point/convert",
            "linkIos": "upluscloud://point/convert"
          }
        ],
        "fbInfoLst": [
          {
            "ch": "MMS",
            "title": "제목",
            "msg": "MMS 메시지 내용",
            "fileId": "testFileId001"
          }
        ]
  }'
아이템리스트형 템플릿
섹션 제목: “아이템리스트형 템플릿”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/alimtalk/v1.2" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
        "clickUrlYn": "N",
        "resvYn": "N",
        "resvReqDt": "2025-07-13 13:15",
        "agency": {
          "kisaOrigCode": "123456789"
        },
        "callback": "0212341234",
        "title": "U+ Cloud 서비스 알림",
        "msg": "안녕하세요. #{name} 고객님.\n\nU+ Cloud서비스에서 설정하신 일일 사용량(1,000건) 초과 사용을 알려드립니다.\n\n※ 사용량 제한 및 기타 자세한 사항은 홈페이지 참조",
        "kkoChId": "@myservice",
        "tmpltCode": "TPnJhpG82k",
        "recvInfoLst": [
          {
            "cliKey": "test001",
            "phone": "01012341234",
             "mergeData": {
                "name": "홍길동"
             },
             "userCustomFields": {
                "key1": "value1",
                "key2": 123
             }
          },
          {
            "cliKey": "test002",
            "phone": "01056785678",
             "mergeData": {
                "name": "김철수"
             }
          }
        ],
        "item": {
            "list": [
              {
                "title": "test01",
                "description": "test01"
              },
              {
                "title": "test02",
                "description": "test02"
              }
            ],
            "summary": {
              "title": "테스트",
              "description": "1,000,000원"
            }
         },
        "itemHeader":"헤더",
        "itemHighlightTitle": "타이틀",
        "itemHighlightDescription": "설명",
        "buttons": [
          {
            "name": "사용량 제한 이용안내",
            "type": "WL",
            "url_mobile": "https://m.uplus.co.kr/cloud/usage",
            "url_pc": "https://www.uplus.co.kr/cloud/usage",
            "kkoBtnOutbrowserYn": true 또는 "true"
          },
          {
            "name": "포인트 전환하기",
            "type": "AL",
            "linkMo": "https://m.uplus.co.kr/point",
            "linkAnd": "upluscloud://point/convert",
            "linkIos": "upluscloud://point/convert"
          }
        ],
        "fbInfoLst": [
          {
            "ch": "MMS",
            "title": "제목",
            "msg": "MMS 메시지 내용",
            "fileId": "testFileId001"
          }
        ]
  }'

Response

섹션 제목: “Response”
{
  "code": "10000",
  "message": "성공",
  "data": [
    {
      "cliKey": "test001",
      "msgKey": "3jVnyk0m8U.6fKG1w",
      "phone": "01012341234",
      "code": "10000",
      "message": "성공"
    },
    ...
  ]
}
예약발송 응답
섹션 제목: “예약발송 응답”
{
  "code": "10000",
  "message": "성공",
  "data": {
    "regDt": "2026-04-08T11:16:55",
    "webReqId": "RRR...b5jv"
   }
  ]
}

2. 브랜드메시지 템플릿형 발송 V1

섹션 제목: “2. 브랜드메시지 템플릿형 발송 V1”

카카오 브랜드메시지 템플릿형 발송 API이며, 최대 10건 까지 한번에 발송 가능합니다.

📌 주의사항

섹션 제목: “📌 주의사항”
  1. 동보발송이란, 같은 내용의 메시지를 다수에게 동시에 보내는 발송 방식
  2. 메시지허브는 동보발송을 지원하며, 1건의 메시지에 최대 10명의 수신자를 추가하여 발송할 수 있습니다.
  3. TPS는 수신자 수 기준으로 처리됩니다. 예시) SMS 1건에 수신자 5명을 추가하여 발송시, TPS는 5입니다.
  4. 템플릿 코드는 사전에 등록된 것만 사용 가능합니다.
  5. 예약발송은 현재 시점으로부터 최대 30일까지 가능합니다.
  6. fbInfoLst는 발송실패시, 대체발송에 대한 객체입니다. 대체발송 채널은 SMS, MMS만 지원하며, 메인 채널과 동일할 수 없습니다.
  7. unsubscribePhoneNumber와 unsubscribeAuthNumber 을 둘 다 입력하지 않은 경우 카카오채널에 등록된 무료수신거부 정보로 발송됩니다.
  8. unsubscribeAuthNumber는 080 수신거부번호의 내선번호 개념으로 옵션값입니다. unsubscribePhoneNumber 없이 입력할 수 없습니다.
  9. unsubscribePhoneNumber는 ‘080-000-0000’의 하이픈(-) 을 포함한 포맷으로 사용합니다.
  10. 캐러셀커머스형의 경우 commerce 객체 내에 변수를 사용하는 경우, mergeData의 key 값에 변수+’_‘+캐러셀번호 를 붙여 입력해야합니다.
    • 예시 1 ))
    • 캐러셀커머스 1번째 캐러셀에 #{정상가격}, #{할인가격}, #{할인율} 을 사용하고
    • 캐러셀커머스 2번째 캐러셀에 #{정상가격}, #{할인가격}, #{정액할인가격} 을 사용하는 경우
    • 발송 예시))
{
"recvInfoLst": [
  {
    "cliKey": "text_test",
    "phone": "01000010001",
    "mergeData": {
      "정상가격_1": "10000",
      "할인가격_1": "8000",
      "할인율_1": "20",
      "정상가격_2": "15000",
      "할인가격_2": "10000",
      "정액할인가격_2": "5000"
    }
  }
]
}
  • 예시 2 ))
  • 캐러셀커머스 1번째 캐러셀은 변수 사용 하지않고,
  • 캐러셀커머스 2번째 캐러셀에 #{정상가격}, #{할인가격}, #{정액할인가격} 을 사용하는 경우
  • 발송 예시))
{
"recvInfoLst": [
  {
    "cliKey": "text_test",
    "phone": "01000010001",
    "mergeData": {
      "정상가격_2": "15000",
      "할인가격_2": "10000",
      "정액할인가격_2": "5000"
    }
  }
]
}

1) 요청 (Request)

섹션 제목: “1) 요청 (Request)”

URL

섹션 제목: “URL”
POST /kko/brandtalk/tmplt/v1 HTTP/1.1

Headers

섹션 제목: “Headers”
NameType필수설명
AuthorizationString●사용자 인증 토큰

Request Body

섹션 제목: “Request Body”
NameType필수설명크기
targetingString●마수동 타입 : M(I+N: I타입 실패 시 N타입으로 발송), N(일반), I(정보)1자
resvYnString-예약발송 여부 (Y/N)1자
resvReqDtString-예약발송 시간 (ex. 2025-07-13 13:15)-
agencyObject-대행사 정보-
pushAlarmString-푸시 알람 설정 (Y/N) default: Y1자
kkoChIdString●카카오채널 ID61자
tmpltCodeString●템플릿 코드-
chatBubbleTypeString●메시지 타입 (TEXT, IMAGE, WIDE, WIDE_ITEM_LIST, CAROUSEL_FEED, CAROUSEL_COMMERCE, COMMERCE, PREMIUM_VIDEO)-
callbackString●발신번호20자
recvInfoLstRecvInfo[]●수신자 정보 목록10개
fbInfoLstFbInfo[]-대체 발송 정보-
unsubscribePhoneNumberString-무료수신거부 전화번호, ‘080-000-0000’ 포맷, unsubscribePhoneNumber과 unsubscribeAuthNumber 둘 다 미입력시 카카오채널에 등록된 무료수신거부 정보로 발송됨.13자
unsubscribeAuthNumberString-무료수신거부 인증번호, unsubscribePhoneNumber 없이 사용불가10자

2) 응답 (Response)

섹션 제목: “2) 응답 (Response)”

Response Body

섹션 제목: “Response Body”
NameType설명
codeString결과 코드
messageString결과 메시지
dataArray결과 데이터 목록
data[].cliKeyString클라이언트 키
data[].msgKeyString메시지 키
data[].phoneString수신번호
data[].codeString결과 코드
data[].messageString결과 메시지

3) 요청 예시 (Sample)

섹션 제목: “3) 요청 예시 (Sample)”

Curl 텍스트형

섹션 제목: “Curl 텍스트형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/tmplt/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "I",
          "tmpltCode": "TEST_TXT",
          "kkoChId": "@메시지허브",
          "chatBubbleType": "TEXT",
          "callback": "020010001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
}'

Curl 와이드형

섹션 제목: “Curl 와이드형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/tmplt/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "M",
          "kkoChId": "@메시지허브",
          "tmpltCode": "TEST_WIDE",
          "chatBubbleType": "WIDE",
          "callback": "020000001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "wide_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 캐러셀피드형

섹션 제목: “Curl 캐러셀피드형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/tmplt/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "N",
          "kkoChId": "@메시지허브",
          "tmpltCode": "TEST_CAROUSEL_FEED",
          "chatBubbleType": "CAROUSEL_FEED",
          "callback": "020000001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "CAROUSEL_FEED_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Response

섹션 제목: “Response”
예약발송
섹션 제목: “예약발송”
{
  "code": "10000",
  "message": "성공",
  "data": {
    "regDt": "2025-10-22T17:43:32",
    "webReqId": "BJ....pT"
  }
}
즉시발송
섹션 제목: “즉시발송”
{
  "code": "10000",
  "message": "성공",
  "data": [
    {
      "cliKey": "text_test",
      "msgKey": "A....2J",
      "phone": "010.....",
      "code": "10000",
      "message": "성공"
    }
  ]
}

3. 브랜드메시지 자유형 발송 V1

섹션 제목: “3. 브랜드메시지 자유형 발송 V1”

카카오 브랜드메시지 자유형 발송 API이며, 최대 10건 까지 한번에 발송 가능합니다.

📌 주의사항

섹션 제목: “📌 주의사항”
  1. 동보발송이란, 같은 내용의 메시지를 다수에게 동시에 보내는 발송 방식
  2. 메시지허브는 동보발송을 지원하며, 1건의 메시지에 최대 10명의 수신자를 추가하여 발송할 수 있습니다.
  3. TPS는 수신자 수 기준으로 처리됩니다. 예시) SMS 1건에 수신자 5명을 추가하여 발송시, TPS는 5입니다.
  4. 발신번호는 사전에 등록된 번호만 사용 가능합니다.
  5. 예약발송은 현재 시점으로부터 최대 30일까지 가능합니다.
  6. 버튼은 최대 5개까지 추가 가능합니다.
  7. fbInfoLst는 발송실패시, 대체발송에 대한 객체입니다. 대체발송 채널은 SMS, MMS만 지원하며, 메인 채널과 동일할 수 없습니다.
  8. 메시지 길이 체크
    TEXT, IMAGE형 경우: 최대 1300자 WIDE, PREMIUM_VIDEO형 경우 : 최대 76자
  9. unsubscribePhoneNumber와 unsubscribeAuthNumber 을 둘 다 입력하지 않은 경우 카카오채널에 등록된 무료수신거부 정보로 발송됩니다.
  10. unsubscribeAuthNumber는 080 수신거부번호의 내선번호 개념으로 옵션값입니다. unsubscribePhoneNumber 없이 입력할 수 없습니다.
  11. unsubscribePhoneNumber는 ‘080-000-0000’의 하이픈(-) 을 포함한 포맷으로 사용합니다.

📌 버튼 타입 설명

섹션 제목: “📌 버튼 타입 설명”
타입설명필수 입력
WL웹링크linkMobile 필수, linkPc선택
AL앱링크linkIos, linkAndroid, linkMobile 중 2개 이상 필수
BK봇 키워드해당 버튼 텍스트 전송
MD메시지 전달해당 버튼 텍스트 + 메시지 본문 전송
AC채널추가TEXT, IMAGE 형은 첫번째 버튼으로, 그 외 템플릿 유형의 경우 마지막 버튼에만 추가 가능, name은 “채널 추가”로 고정값 사용
BF비즈니스폼bizFormId 필수, 버튼명은 비즈니스폼 유형에 따라 “톡에서 설문하기”, “톡에서 응모하기”, “톡에서 예약하기” 중 한가지 사용

1) 요청 (Request)

섹션 제목: “1) 요청 (Request)”

URL

섹션 제목: “URL”
POST https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1 HTTP/1.1

Headers

섹션 제목: “Headers”
NameType필수설명
AuthorizationString●사용자 인증 토큰

Request Body

섹션 제목: “Request Body”
NameType필수설명크기
targetingString●마수동 타입 : M(I+N: I타입 실패 시 N타입으로 발송), N(일반), I(정보)1자
agencyObject-대행사 정보-
resvYnString-예약발송 여부 (Y/N)1자
resvReqDtString-예약발송 시간 (ex. 2025-07-13 13:15)-
campaignIdString-캠페인 ID20자
deptCodeString-부서 코드20자
callbackString●발신번호20자
recvInfoLstRecvInfo[]●수신자 정보 목록10개
fbInfoLstFbInfo[]-대체 발송 정보-
pushAlarmString-푸시 알람 설정 (Y/N) default: Y1자
unsubscribePhoneNumberString-무료수신거부 전화번호, ‘080-000-0000’ 포맷, unsubscribePhoneNumber과 unsubscribeAuthNumber 둘 다 미입력시 카카오채널에 등록된 무료수신거부 정보로 발송됨.13자
unsubscribeAuthNumberString-무료수신거부 인증번호, unsubscribePhoneNumber 없이 사용불가10자
kkoChIdString●카카오채널 ID61자
chatBubbleTypeString●메시지 타입 (TEXT, IMAGE, WIDE, WIDE_ITEM_LIST, CAROUSEL_FEED, CAROUSEL_COMMERCE, COMMERCE, PREMIUM_VIDEO)-
adultboolean-성인용 템플릿 여부최대 5자
contentString-템플릿 내용 TEXT, IMAGE: 최대 1,300자 (줄 바꿈: 최대 99개, URL 형식 입력 가능), WIDE, PREMIUM_VIDEO: 최대 76자 (줄 바꿈: 최대 1개)-
공통 CAROUSEL_COMMERCE , CAROUSEL_FEED 는 buttons, coupon 사용 불가
buttonsButton[]-버튼요소 (TEXT, IMAGE - coupon 사용할 경우 최대 4개, 그 외 최대 5개 WIDE, WIDE_ITEM_LIST - 최대 2개 PREMIUM_VIDEO - 최대 1개 COMMERCE - 최소1개 최대 2개)-
couponCoupon-쿠폰요소-
챗버블 IMAGE 이미지형, WIDE 와이드형 일 경우
imageUrlString●파일 업로드 API로 등록한 이미지 URL최대 500자
imageLinkString-이미지 클릭 시 이동할 URL최대 500자
챗버블 WIDE_ITEM_LIST 와이드 아이템 리스트형 일 경우
headerString●템플릿 헤더최대 20자
wideItemListWideItem[]●와이드 리스트, 리스트 3개 필수
챗버블 PREMIUM_VIDEO 프리미엄 동영상 형 일 경우
headerString-템플릿 헤더최대 20자
videoObject●--
video.videoUrlString●카카오TV 동영상 url-
video.thumbnailUrlString-이미지업로드 API로 등록한 아이템 이미지 url-
챗버블 COMMERCE 커머스 형 일 경우
additionalContentString-템플릿 부가정보, 줄바꿈 최대 1개최대 34자
imageUrlString●파일 업로드 API로 등록한 이미지 URL최대 500자
commerceObject●--
commerce.titleString●상품 제목30자
commerce.regularPriceNumber●정상가격 (0 ~ 99,999,999)
commerce.discountPriceNumber●할인 후 가격 (0 ~ 99,999,999)
commerce.discountRateNumber-할인율 (0 ~ 100) 할인율과 정액 할인 가격 둘중 하나만 입력
commerce.discountFixedNumber-정액 할인 가격 (0 ~ 999,999) 할인율과 정액 할인 가격 둘중 하나만 입력
챗버블 CAROUSEL_COMMERCE 캐러셀 커머스 형 일 경우
carouselObject●--
carousel.headObject-캐러셀 인트로(head) - CAROUSEL_COMMERCE에서만 선택적 사용 가능-
carousel.head.headerString●캐러셀 인트로 헤더 (CAROUSEL_COMMERCE head 사용시 필수)-
carousel.head.contentString●mobile 환경에서 버튼 클릭 시 이동할 url
carousel.head.imageUrlString●파일업로드 API로 등록한 캐러셀 인트로 이미지 url
carousel.head.linkMobileString-mobile 환경에서 버튼 클릭 시 이동할 url , 링크를 하나라도 입력하는 경우 linkMobile 필수
carousel.head.linkPcString-pc 환경에서 버튼 클릭 시 이동할 url
carousel.head.linkAndString-mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme
carousel.head.linkIosString-mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme
carousel.listjson[]●캐러셀 리스트, 캐러셀인트로(head) 사용시 15개, 그 외 26개
carousel.list.additionalContentString-캐러셀 리스트 부가정보최대 34자
carousel.list.imageUrlString●파일업로드 API로 등록한 캐러셀 인트로 이미지 url
carousel.list.imageLinkString-이미지 클릭 시 이동할 url
carousel.list.commerceCommerce●커머스요소
carousel.list.buttonsButton[]●버튼 목록 (캐러셀 당 최소 1개, 최대 2개)
carousel.list.couponCoupon-쿠폰 요소
carousel.tailjson-더보기 버튼
carousel.tail.linkMobileString-mobile 환경에서 버튼 클릭 시 이동할 url , 링크를 하나라도 입력하는 경우 linkMobile 필수
carousel.tail.linkPcString-pc 환경에서 버튼 클릭 시 이동할 url
carousel.tail.linkAndString-mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme
carousel.tail.linkIosString-mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme
챗버블 챗버블 CAROUSEL_FEED캐러셀 피드 형 일 경우
carouselObject●--
carousel.listjson[]●캐러셀 리스트, 캐러셀인트로(head) 사용시 15개, 그 외 26개
carousel.list .headerString●캐러셀 인트로 헤더최대 20자
carousel.list.contentString●캐러셀 리스트 내용최대 180자
carousel.list.imageUrlString●파일업로드 API로 등록한 캐러셀 인트로 이미지 url
carousel.list.imageLinkString-이미지 클릭 시 이동할 url
carousel.list.buttonsButton[]●버튼 목록 (캐러셀 당 최소 1개, 최대 2개)
carousel.list.couponCoupon-쿠폰 요소
carousel.tailjson-더보기 버튼
carousel.tail.linkMobileString-mobile 환경에서 버튼 클릭 시 이동할 url , 링크를 하나라도 입력하는 경우 linkMobile 필수
carousel.tail.linkPcString-pc 환경에서 버튼 클릭 시 이동할 url
carousel.tail.linkAndString-mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme
carousel.tail.linkIosString-mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme
buttons 객체
섹션 제목: “buttons 객체”
NameType필수설명크기
nameString●버튼이름14자
linkTypeString●버튼타입2자
linkMobileString-mobile 환경에서 버튼 클릭 시 이동할 url-
linkPcString-pc 환경에서 버튼 클릭 시 이동할 url-
linkAndroidString-mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme-
linkIosString-mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme-
Coupon 객체
섹션 제목: “Coupon 객체”
📌 주의사항
섹션 제목: “📌 주의사항”
  1. 쿠폰 제목에는 변수와 고정값을 사용할 수 있습니다.
  2. 쿠폰 제목에 변수를 사용하는 경우, 고정 변수명 5개 중 사용
    고정 변수 :
    1. #{할인금액}원 할인 쿠폰
    2. #{할인율}% 할인 쿠폰
    3. 배송비 할인 쿠폰
    4. #{상품명} 무료 쿠폰
    5. #{상품명} UP 쿠폰

예시) 고정 변수 문자 그대로 입력하여 등록

      "coupon": {
        "title": "#{상품명} 무료 쿠폰"
      }


    "coupon": {
        "title": "#{할인율}% 할인 쿠폰"
      }


    "coupon": {
        "title": "배송비 할인 쿠폰"
      }
  1. 쿠폰 제목에 고정 값 사용을 원할 경우, 변수 자리에 숫자 입력
    #{할인금액} 입력 가능 범위 : 1 ~ 99,999,9999
    #{할인율} 입력 가능 범위 : 1 ~ 100
    #{상품명} : 최대 7자

예시) 변수자리에 숫자 혹은 문자 입력하여 등록

      "coupon": {
        "title": "바나나우유 무료 쿠폰"
      }


    "coupon": {
        "title": "20% 할인 쿠폰"
      }


     "coupon": {
        "title": "50000원 할인 쿠폰"
      }
NameType필수설명
tileString●쿠폰 제목
descriptionString●쿠폰 설명
linkMobileString-mobile 환경에서 쿠폰 클릭 시 이동할 url
linkPcString-pc 환경에서 쿠폰 클릭 시 이동할 url
linkAndroidString-mobile android 환경에서 쿠폰 클릭 시 실행할 application custom scheme
linkIosString-mobile ios 환경에서 쿠폰 클릭 시 실행할 application custom scheme

2) 응답 (Response)

섹션 제목: “2) 응답 (Response)”

Response Body

섹션 제목: “Response Body”
NameType설명
codeString결과 코드
messageString결과 메시지
dataArray결과 데이터 목록
data[].cliKeyString클라이언트 키
data[].msgKeyString메시지 키
data[].phoneString수신번호
data[].codeString결과 코드
data[].messageString결과 메시지

3) 요청 예시 (Sample)

섹션 제목: “3) 요청 예시 (Sample)”

Curl 텍스트형

섹션 제목: “Curl 텍스트형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "I",
          "kkoChId": "@메시지허브",
          "callback": "020010001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "chatBubbleType": "TEXT",
          "adult": false,
          "content": "안녕하세요. 브랜드 메시지 테스트 자유형 발송입니다.",
          "buttons": [
             {
               "name":"채널 추가",
               "linkType": "AC"
            },
            {
              "name": "버튼01",
              "linkType": "WL",
              "linkMobile": "https://m.example.com",
              "linkPc": "https://www.example.com"
            }
          ],
          "coupon": {
            "title": "1000원 할인 쿠폰",
            "description": "설명",
            "linkMobile": "https://m.example.com"
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 이미지형

섹션 제목: “Curl 이미지형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "M",
          "kkoChId": "@메시지허브",
          "chatBubbleType": "IMAGE",
          "callback": "020010001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "adult": false,
          "content": "안녕하세요. 브랜드 메시지 테스트 등록입니다. 02",
          "imageUrl": "https://mud-kage.kakao.com/dn/lvkxE/bts...5XE/vag....30/img_l.jpg",
          "imageLink": "https://www.example.com",
          "buttons": [
             {
               "name":"채널 추가",
               "linkType": "AC"
            },
            {
              "name": "버튼01",
              "linkType": "WL",
              "linkMobile": "https://m.example.com",
              "linkPc": "https://www.example.com"
            }
          ],
          "coupon": {
            "title": "1000원 할인 쿠폰",
            "description": "설명",
            "linkMobile": "https://m.example.com"
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 와이드형

섹션 제목: “Curl 와이드형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "I",
          "kkoChId": "@메시지허브",
          "chatBubbleType": "WIDE",
          "callback": "020010001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "adult": false,
          "content": "안녕하세요. 브랜드 메시지 WIDE 테스트",
          "imageUrl": "https://mud-kage.kakao.com/dn/lvkxE/bt....XE/vag.....30/img_l.jpg",
          "buttons": [
            {
              "name": "버튼01",
              "linkType": "WL",
              "linkMobile": "https://m.example.com",
              "linkPc": "https://www.example.com"
            }
          ],
          "coupon": {
            "title": "1000원 할인 쿠폰",
            "description": "설명",
            "linkMobile": "https://m.example.com"
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 비디오형

섹션 제목: “Curl 비디오형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "I",
          "kkoChId": "@메시지허브",
          "chatBubbleType": "PREMIUM_VIDEO",
          "callback": "020000001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "adult": false,
          "content":"내용",
          "video": {
            "videoUrl": "https://tv.kakao.com/v/4...54",
            "thumbnailUrl": "https://mud-kage.kakao.com/dn/lvkxE/bt.....XE/vagk....pQ30/img_l.jpg"
          },
          "header": "템플릿 비디오형 헤더",
          "buttons": [
            {
              "name": "버튼01",
              "linkType": "WL",
              "linkMobile": "https://m.example.com",
              "linkPc": "https://www.example.com"
            }
          ],
          "coupon": {
            "title": "1000원 할인 쿠폰",
            "description": "설명",
            "linkMobile": "https://m.example.com"
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 와이드아이템리스트형

섹션 제목: “Curl 와이드아이템리스트형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
         "targeting": "I",
          "kkoChId": "@메시지허브",
          "callback": "020000001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "chatBubbleType": "WIDE_ITEM_LIST",
          "adult": false,
          "header": "아이템리스트 헤더",
          "wideItemList": [
            {
              "title": "메인아이템 타이틀",
              "imageUrl": "https://mud-kage.kakao.com/dn/GkEt7/b....6I4/4Vm....dZXbk/img_l.jpg",
              "linkMobile": "https://m.example.com"
            },
            {
              "title": "서브아이템 타이틀1",
              "imageUrl": "https://mud-kage.kakao.com/dn/bx7...Qey06eR5/7V1....0/img_l.jpg",
              "linkMobile": "https://m.example.com"
            },
            {
              "title": "서브아이템 타이틀2",
              "imageUrl": "https://mud-kage.kakao.com/dn/IQTR7/bt...NY/uE....SK/img_l.jpg",
              "linkMobile": "https://m.example.com"
            }
          ],
          "buttons": [
            {
              "name": "버튼01",
              "linkType": "WL",
              "linkMobile": "https://m.example.com",
              "linkPc": "https://www.example.com"
            }
          ],
          "coupon": {
            "title": "1000원 할인 쿠폰",
            "description": "설명",
            "linkMobile": "https://m.example.com"
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 캐러셀피드형

섹션 제목: “Curl 캐러셀피드형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
          "targeting": "I",
          "kkoChId": "@메시지허브",
          "callback": "020000001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "chatBubbleType": "CAROUSEL_FEED",
          "adult": false,
          "carousel": {
            "list": [
              {
                "header": "커머셜리스트 헤더1",
                "content": "커머셜리스트 내용2",
                "imageUrl": "https://mud-kage.kakao.com/dn/bx74y0/b....eR5/7V.....e0/img_l.jpg",
                "buttons": [
                  {
                    "name": "버튼01",
                    "linkType": "WL",
                    "linkMobile": "https://m.example.com",
                    "linkPc": "https://www.example.com"
                  }
                ]
              },
              {
                "header": "커머셜리스트 헤더2",
                "content": "커머셜리스트 내용2",
                "imageUrl": "https://mud-kage.kakao.com/dn/IQTR7/bt....NY/u....4SK/img_l.jpg",
                "buttons": [
                  {
                    "name": "버튼02",
                    "linkType": "WL",
                    "linkMobile": "https://m.example.com",
                    "linkPc": "https://www.example.com"
                  }
                ]
              }
            ]
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 캐러셀커머스형

섹션 제목: “Curl 캐러셀커머스형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
         "targeting": "I",
          "kkoChId": "@메시지허브",
          "chatBubbleType": "CAROUSEL_COMMERCE",
          "callback": "020000001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000000001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "adult": false,
          "imageUrl": "https://mud-kage.kakao.com/dn/lvkxE/bts...XE/vagk....30/img_l.jpg",
          "carousel": {
            "head": {
              "header": "캐러셀커머스헤드 헤더",
              "content": "캐러셀커머스헤드 내용, 헤드는 필수값아님",
              "imageUrl": "https://mud-kage.kakao.com/dn/IQTR7/bts...NY/uEnC....U4SK/img_l.jpg"
            },
            "list": [
              {
                "additionalContent": "캐러셀커머스 부가정보",
                "imageUrl": "https://mud-kage.kakao.com/dn/bx74y0/bt...R5/7V1...ke0/img_l.jpg",
                "commerce": {
                  "title": "캐러셀커머스 제목",
                  "regularPrice": 1000,
                  "discountPrice": 500,
                  "discountRate": 50
                },
                "buttons": [
                  {
                    "name": "버튼01",
                    "linkType": "WL",
                    "linkMobile": "https://m.example.com",
                    "linkPc": "https://www.example.com"
                  }
                ]
              }
            ],
            "tail": {
              "linkMobile": "https://m.example.com",
              "linkPc": "https://www.example.com"
            }
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Curl 커머스형

섹션 제목: “Curl 커머스형”
curl -X POST "https://api-send.msghub-qa.uplus.co.kr/kko/brandtalk/custom/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
         "targeting": "I",
          "kkoChId": "@메시지허브",
          "chatBubbleType": "COMMERCE",
          "callback": "020000001",
          "agency": {
            "kisaOrigCode": "123456789",
            "rcsAgencyId": "agencyId",
            "rcsAgencyKey": "AK.abcd1234"
          },
          "fbInfoLst": [
            {
              "ch": "MMS",
              "title": "제목",
              "msg": "MMS 메시지 내용"
            }
          ],
          "recvInfoLst": [
            {
              "cliKey": "text_test",
              "phone": "01000010001",
              "userCustomFields": {
                 "key1": "value1",
                 "key2": 123
             }
            }
          ],
          "adult": false,
          "imageUrl": "https://mud-kage.kakao.com/dn/lvkxE/bts...XE/vagk....30/img_l.jpg",
            "commerce": {
            "title": "필수",
            "regularPrice": 1000,
            "discountPrice": 500,
            "discountRate": discountRate, discountFixed 중 하나 필수
          "discountFixed" : discountRate, discountFixed 중 하나 필수
          },
          "buttons": [
            {
              "name": "텍스트",
              "linkType": "WL",
              "linkMobile": "https://www.naver.com",
              "linkPc": "https://www.naver.com"
            }
          ],
          "coupon": {
            "title": "배송비 할인 쿠폰",
            "linkPc": "",
            "linkIos": "",
            "linkMobile": "https://naver.com",
            "description": "#{할인금액}원 할인 ",
            "linkAndroid": ""
          },
          "unsubscribePhoneNumber": "080-1234-1234",
          "unsubscribeAuthNumber": "1234"
  }'

Response

섹션 제목: “Response”
예약발송
섹션 제목: “예약발송”
{
  "code": "10000",
  "message": "성공",
  "data": {
    "regDt": "2025-10-22T17:43:32",
    "webReqId": "BJ....pT"
  }
}
즉시발송
섹션 제목: “즉시발송”
{
  "code": "10000",
  "message": "성공",
  "data": [
    {
      "cliKey": "text_test",
      "msgKey": "A....2J",
      "phone": "010.....",
      "code": "10000",
      "message": "성공"
    }
  ]
}

Appendix

섹션 제목: “Appendix”

Agency 객체

섹션 제목: “Agency 객체”

대행사 정보를 포함하는 객체입니다.

필드명타입필수설명
kisaOrigCodeString-재판매사 KISA 최초식별코드
rcsAgencyIdString-RBC에 등록된 대행사ID
rcsAgencyKeyString-RBC에서 발급된 대행사키

recvInfoLst 객체

섹션 제목: “recvInfoLst 객체”
NameType필수설명크기
cliKeyString●클라이언트키30자
phoneString●수신번호(국제문자 발송 시 맨 앞에 ‘0’이 없어야함)20자
mergeDataObject-채널별 개별화메시지 머지데이터-
userCustomFieldsObject-사용자 정의 필드-

fbInfoLst 객체

섹션 제목: “fbInfoLst 객체”
NameType필수설명
chString●채널
titleString-제목(MMS의 경우 필수)
msgString●메시지
fileIdString-파일아이디 (파일 아이디와 파일 아이디 목록 중 1개만 사용 가능)
fileIdLstArray-파일 아이디 목록 (최대 3개)

결과 코드

섹션 제목: “결과 코드”