RCS

RCS 발송 #

RCS 발송 API이며, 최대 10건 까지 한번에 발송 가능합니다.
메시지는 사전에 등록된 메시지베이스의 가변데이터만을 이용하여 전송합니다.
이미지 등 파일이 포함된 경우, 사전에 등록된 fileId를 가변데이터에 포함하여 전송합니다.
ex) maapfile://{fileId}
※ cliKey 참고 사항
-. 최대 길이는 30자이며 영문 대, 소문자, 숫자, 특수 문자(“-“, “_”, “.”, “@”) 네 가지 허용
-. 중복 체크 요건 : 당일 10분 내 동일 cliKey로 발송 할 경우 중복

Request #

URL

POST /msg/v1/rcs HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: api.msghub.uplus.co.kr

Header

Name	Type	Required	Description
Authorization	String	true	사용자 인증 토큰

Request body

Name	Type	Required	Description
messagebaseId	String	true	메시지베이스 ID (^[a-zA-Z0-9-_]{0,20}$)
callback	String	true	발신번호
header	String	false	0=정보성 메시지, 1=광고성 메시지
footer	String	true	무료수신거부 번호 (*header의 값이 광고성일 때 footer 값을 포함하지 않고 발송하면 실패 처리)
copyAllowed	Boolean	true	사용자의 복사/공유 허용여부
expiryOption	String	false	expire 옵션(1:24시간, 2:30초, 3:3분, 4:1시간)
campaignId	String	false	캠페인 ID
agency	Object<Agency>	false	대행사/재판매 사업자 발송정보 (일반사업자는 미사용)
`resvYn`	String	false	예약발송 여부
resvReqDt	String	false	예약발송 일시(yyyy-MM-dd hh:mm)
deptCode	String	false	부서코드
buttons	Object	false	버튼
recvInfoLst	List<RecvInfo>	true	발송 정보 목록(최대 10건 발송가능)
fbInfoLst	List<FbInfo>	false	fallback 정보 목록
clickUrlYn	String	false	단축URL 사용여부

Response #

스키마를 참조하세요.

Sample #

Curl

curl -X POST "https://api.msghub.uplus.co.kr/msg/v1/rcs"
-H  "accept: */*"
-H  "Authorization: Bearer eyJhbGciOiJIUzI1NiJ..."
-H  "Content-Type: application/json"
-d '
  {
    "messagebaseId": "AA012345",
    "callback": "0212341234",
    "header": "0",
    "footer": "080-123-1234",
    "copyAllowed": true,
    "expiryOption": "1",
   "agency":{
                   "kisaOrigCode": "재판매사 KISA 최초식별코드",
                   "rcsAgencyId": "재판매사 RCS Agency ID",
                   "rcsAgencyKey": "재판매사 RCS Agency Key"
    },
    "campaignId": "캠페인ID",
    "resvYn": "Y",
    "resvReqDt": "2023-01-13 13:15",
    "deptCode": "부서코드",
   "clickUrlYn": "Y", // 클릭 URL 사용시 "Y" 로 처리
    "buttons": [
    {
      "suggestions": [
        {
          "action": {
            "postback": {
              "data": "set_by_chatbot_open_url"
            },
            "urlAction": {
              "openUrl": {
                "url": "https://m-hub.kr/{{URL_반응형 URL ID}}"   // 예) https://m-hub.kr/{{URL_abcdef}}
              }
            },
            "displayText": "다음 링크 바로가기" // 버튼 명
          }
        }
      ]
    }
  ],
    "recvInfoLst": [
        {
            "cliKey": "cliKey1",
            "phone": "01012341234",
            "mergeData": {
                "name": "이름",
                "description": "{{name}}님 안녕하세요."
            }
        },
        {
            "cliKey": "cliKey2",
            "phone": "01012341235",
            "mergeData": {
               // 머지할 데이터
               "name": "이름",

               // 일반 발송 시
               "title" : "제목",
               "description": "{{name}}님 안녕하세요."
               
               // 케로셀 형태일 경우
               "title1" : "제목",
               "description1" : "본문 텍스트",
               "media1" : "maapfile://{fileId_1}",
               "title2" : "제목 2번째 카드",
               "description2" : "본문 텍스트",
               "media2" : "maapfile://{fileId_2}",
               "title3" : "제목 3번째 카드",
               "description3" : "본문 텍스트",
               "media3" : "maapfile://{fileId_3}",

               // 신규포맷 mms 전용
               "media" : "maapfile://{fileId_main}",      > 상단 main 이미지
               "title" : "제목 텍스트",                   > 상단 main 제목
               "description" : "본문 텍스트",             > 상단 main 본문
               "subMedia1" : "maapfile://{fileId_sub1}",  > 선택 옵션 서브 이미지 1
               "subMediaUrl1" : "URL",                    > 선택 옵션 서브 이미지 1 클릭 시 랜딩 URL
               "subTitle1" : "제목 텍스트",               > 선택 옵션 소제목 1
               "subDesc1" : "본문 텍스트",                > 선택 옵션 소본문 1
               "subMedia2" : "maapfile://{fileId_sub2}",  > 선택 옵션 서브 이미지 2
               "subMediaUrl2" : "URL",                    > 선택 옵션 서브 이미지 2 클릭 시 랜딩 URL
               "subTitle2" : "제목 텍스트",               > 선택 옵션 소제목 2
               "subDesc2" : "본문 텍스트",                > 선택 옵션 소본문 2
               "subMedia3" : "maapfile://{fileId_sub3}",  > 선택 옵션 서브 이미지 3
               "subMediaUrl3" : "URL",                    > 선택 옵션 서브 이미지 3 클릭 시 랜딩 URL
               "subTitle3" : "제목 텍스트",               > 선택 옵션 소제목 3
               "subDesc3" : "본문 텍스트",                > 선택 옵션 소본문 3 
            }
        }
    ],
    "fbInfoLst": [
        {
            "ch": "SMS",
            "title": "제목",
            "msg": "SMS 메시지 내용",
            "fileId": "test01"
        }
    ]
  }'

Response

{
    "code": "10000",
    "message": "성공",
    "data": [
        {
            "cliKey": "cliKey1",
            "msgKey": "tw9Tomlcen.6bTb0O",
            "phone": "01012341234",
            "code": "10000",
            "message": "성공"
        },
        {
            "cliKey": "cliKey2",
            "msgKey": "tw9Tomlcen.6bTb0O",
            "phone": "01012341234",
            "code": "10000",
            "message": "성공"
        }
    ]
}

참고

결과 코드 참고

RCS 양방향 메시지 전달(Webhook 방식) #

양방향 메시지를 수신할 수 있는 웹 훅 URL 정보를 사전에 등록해서 사용해야 합니다.
양방향 대화방 사용 시 웹 훅 수신에 사용 할 apiKey를 지정하셔야 합니다.
apiKey에 사용자에게서 수신 받은 문자를 수신하실 webhook url을 저장하여 주시기 바랍니다.

참고 사항
1. webhook url을 지정하지 않을 경우, 일정 시간이 지난 후 고객으로부터 수신 받은 문자는 삭제됩니다.
2. 후불 고객사만 가능합니다.
3. 자동 응답 기능의 경우, 수신 받은 고객이 메뉴를 클릭 할 경우, 자동으로 설정된 답변을 응답합니다.
4. 자동 응답 메뉴 등록은 챗봇 등록 시 등록 가능합니다.

Request #

URL

POST /msg/v1/rcs HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: #{WEBHOOK_URL}

Response #

Name	Type	Description
rcsBiCnt	long	양방향 메시지 개수
rcsBiLst	Array	rcs 양방향 리스트
rcsBiaLst	Array	rcs 자동응답 리스트
rcsBirLst	Array	rcs 양방향 응답 메시지 발송 리스트

rcsBiLst

Name	Type	Description
msgKey	String	메시지고유키
ymd	String	발송일자
hm	String	시분
chatbotId	String	챗봇 ID
replyId	String	고객메시지ID(자동응답메시지 ID)
postbackId	String	대화방 메뉴 내 reply 클릭 시, 속성으로 포함된 postbackId 값
postbackData	Object	칩리스트/리치카드 버튼 중 reply 클릭 시에, 발송 요청 시 포함되었던 postbackData 값
eventType	String	이벤트 유형 message:유저가 직접 작성한 메시지 (text, file, userLocation message) response:(persistent menu 혹은 메시지의 reply 버튼, chip list 의 reply 누를 때) newUser:대화방 최초 진입 후 단말에서 자동 발신되는 메시지
contentInfo	Object	메시지 내용
moRecvDt	String	메시지 수신 일자 ex) 2021-01-29T09:22:55
phone	String	고객 전화번호

contentInfo

Name	Type	Description
textMessage	String	텍스트 메시지
fileMessage	Object	파일 메시지
fileMessage.fileUrl	String	파일 url
fileMessage.fileMIMEType	String	파일 MIME Type
geolocationPushMessage	Object	userLocation 메시지
geolocationPushMessage.label	String
geolocationPushMessage.timestamp	String
geolocationPushMessage.timeOffset	Integer
geolocationPushMessage.pos	String
geolocationPushMessage.radius	Integer

rcsBiaLst

Name	Type	Description
chatbotId	String	챗봇 아이디
autoReplyMsgId	String	양방향 대화방 자동응답 메시지 ID
postbackId	String	대화방 메뉴 내 reply 클릭 시에, 속성으로 포함된 postbackId 값
postbackData	Object	칩리스트/리치카드 버튼 중 reply 클릭 시에, 발송 요청시 포함되었던 postbackData 값
moRecvDt	String	고객 메시지 수신 일시 ex) 2021-01-29T09:22:55
bill	Integer	양방향 대화방 과금 여부(1 : 과금, 0 : 비과금)
phone	String	고객 전화번호

BirLst

Name	Type	Description
ymd	String	발송 일자
hm	String	발송 시간
apiKey	String	api key
cliKey	String	클라이언트 key
chatbotId	String	챗봇 ID
replyId	String	고객 메시지 ID
cliResultCode	String	클라이언트 결과코드
bill	Integer	양방향대화방 과금여부 : 1-과금, 0-비과금

Sample #

Curl

curl -X POST “https://{WEBHOOK_URL}”
-H “accept: */*”
-H “Content-Type: application/json”
-d {
“rcsBiCnt”:2,
“rcsBiLst”:[
{
“msgKey”:”pcNUC3QGVk.6cDbSU”,
“ymd”:”2024-07-04″,
“hm”:”1200″,
“chatbotId”:”01012340000″,
“replyId”:”3daf377efjmdmduddjdjflsk”,
“postbackId”:”QEjID4ja5bzN2j2″,
“postbackData”:{“칩리스트/리치카드 버튼 중 reply 클릭 시에, 발송 요청시 포함되었던 postbackData 값”},
“contentInfo”:{
“textMessage”: “”,
“fileMessage”: {
“fileUrl”:””,
“fileMIMEType”:””
},
“GeolocationPushMessage”:{
“label”:””,
“timestamp”:””,
“timeOffset”:””,
“pos”:””,
“radius”:””
}
“moRecvDt”:”2024-0704 13:48:00″,
“phone”:”01012341234″
}
],
“rcsBiaLst”:[
{
“chatbotId”: “chatbotId”,
“postbackId”:”postbackId”,
“postbackData”:{“postbackData”},
“moRecvDt”:”2021-01-29T09:22:55″,
“bill”:”0″,
“phone”:”01012341234″
}
],
“rcsBirLst” : [
{
“ymd”: “2024-07-04”,
“hm”: “1508”,
“apiKey”: “apiKey”,
“cliKey”: “cliKey”,
“chatbotId”: “chatbotId”,
“replyId”: “replyId”,
“cliResultCode”: “2009”,
“bill”:”0″
}
]
]
}

결과 코드 참고

Updated on 2025년 2월 26일

Quick Guide

서비스 개요

계정 안내

관리자 콘솔

사용자 콘솔

API 가이드

Push 앱개발 가이드

Agent 가이드

서비스 정보

RCS

RCS 발송 #

Request #

Response #

Sample #

RCS 양방향 메시지 전달(Webhook 방식) #

Request #

Response #

Sample #