캐러셀

서비스를 이용하시려면 API PLEX 에서 [서비스 콘솔 / 발신번호]에서 발신번호 등록을 수행해야 합니다.

RCS biz center 에서 브랜드를 등록한 후, [대화방] > [대화방 등록] 메뉴를 통하여 사용할 발신번호와 브랜드를 연동 해야 합니다.

RCS biz center 에서 [내 브랜드 관리] > [브랜드 운영 관리] > [대행사 운영권한 부여] 버튼을 통하여 'CJ올리브네트웍스'에 대행사 운영권한을 부여 해 주셔야 합니다.

해당 API는 메세지 발송 결과(WebHook)으로 결과를 전달할 수 있습니다.

SMS API

사용 전 체크 사항

캐릭터 인코딩은 UTF-8 을 기본으로 합니다.

Path variable

Path variable(각 URI 내 중괄호({}) 로 묶인 경로 변수)는 아래 내용을 참고하여 호출 시 누락되지 않도록 해주세요.

code	설명
service_id	서비스 유형 id rcs-carousel-std : 스탠다드 RCS 캐러셀 rcs-carousel-bulk : 대량 RCS 캐러셀 rcs-carousel-finance : 금융 RCS 캐러셀

RCS 캐러셀API

POST https://cium0wvo4a.apigw.ntruss.com/rcs/v2/{service_id}

RCS SMS 발송용 API

Headers

Name	Value
Content-Type	application/json; charset=utf8
Authorization	사용자ID;secret_key

Body

Name	Type	Description	Required
msg_type	string	RCS 메시지 타입 - RMC : RCS MMS Carousel - RMS : RCS MMS Carousel Small
msg_data	array	메시지 발송 상세 데이터
msg_key	string	메시지 고유 키(발송 시 unique 하게 설정 하여 발송)
sender_number	string	발신자 전화번호(발신번호 등록이 된 번호)
receiver_number	string	수신자 휴대폰 번호
msg_base_id	string	메시지포맷의고유식별값 (message base ID 참조)
brand_id	string	브랜드 아이디 (RCS Biz Center '브랜드 관리' - '브랜드 홈' 에서 확인 가능 합니다.)
brand_key	string	브랜드 키 (RCS Biz Center '브랜드 관리' - '브랜드 홈' 에서 확인 가능 합니다.)
header	string	광고성 메시지 여부 (0 : 정보성메시지, 1: 광고성메시지)
footer	string	무료수신거부 번호 (해당 파라미터 설정 시 ‘무료수신거부’ 문구가 자동으로 설정되어 발송) (header 값이 광고성 일 때 footer 값을 포함하지 않으면실패 처리)
copy_allowed	boolean	복사 기능 허용 여부 (해당 메시지에 대해 단말기 내에서의 복사 기능 허용 여부)
msg	object	메시지 내용
body	object	메시지 body (메시지 타입에 따라 다르므로 메세지 타입별 Msg Body 참조)
buttons	array	버튼 속성 데이터 (버튼이 포함된 메시지 전송 시 상세 데이터를 포함) (버튼 설정 방법 참조)

Response

200

{
    "results": [
        {
            "code": "C100",
            "msg_key": "user_key_1",
            "desc": "success"
        },
        {
            "code": "C341",
            "msg_key": "4b68ca16-7aa8-4a17-b74c-2b8e4adb13f8",
            "desc": "success"
        }
    ]
}

400

{
  "code": "G120",
  "desc": "유효한 사용자가 존재하지 않습니다."
}

메세지타입별 Msg Body

템플릿 타입	키	타입	필수	설명
MMS_Carousel Medium	title1	string	N	첫번째카드제목 (최대30자) * 카드 최소 3 개 ~ 최대 6 개 가능 * 카드 수만큼 title, description, media 전달 * 카드마다 title, description, media 중에 한 개 항목 필수 입력 * 값이 없는 key 값은 전송하지 않음 (null 허용하지 않음)
	description1	string	N	첫번째카드본문 (최대1300자)
	media1	string	N	첫번째카드이미지MaaP URL
	title2	string	N	두번째카드제목 (최대30자)
	description2	string	N	두번째카드본문 (최대1300자)
	media2	string	N	두번째카드이미지MaaP URL
	title3	string	N	세번째카드제목 (최대30자)
	description3	string	N	세번째카드본문 (최대1300자)
	media3	string	N	세번째카드이미지MaaP URL
	title4	string	N	네번째카드제목 (최대30자)
	description4	string	N	네번째카드본문 (최대1300자)
	media4	string	N	네번째카드이미지MaaP URL
	title5	string	N	다섯번째카드제목 (최대30자)
	description5	string	N	다섯번째카드본문 (최대1300자)
	media5	string	N	다섯번째카드이미지MaaP URL
	title6	string	N	여섯번째카드제목 (최대30자)
	description6	string	N	여섯번째카드본문 (최대1300자)
	media6	string	N	여섯번째카드이미지MaaP URL
MMS_Carousel Small	title1	string	N	첫번째카드제목 (최대30자) * 카드 최소 3 개 ~ 최대 6 개 가능 * 카드 수만큼 title, description, media 전달 * 카드마다 media 필수 입력 * 값이 없는 key 값은 전송하지 않음 (null 허용하지 않음)
	description1	string	N	첫번째카드본문 (최대1300자)
	media1	string	N	첫번째카드이미지MaaP URL
	title2	string	N	두번째카드제목 (최대30자)
	description2	string	N	두번째카드본문 (최대1300자)
	media2	string	N	두번째카드이미지MaaP URL
	title3	string	N	세번째카드제목 (최대30자)
	description3	string	N	세번째카드본문 (최대1300자)
	media3	string	N	세번째카드이미지MaaP URL
	title4	string	N	네번째카드제목 (최대30자)
	description4	string	N	네번째카드본문 (최대1300자)
	media4	string	N	네번째카드이미지MaaP URL
	title5	string	N	다섯번째카드제목 (최대30자)
	description5	string	N	다섯번째카드본문 (최대1300자)
	media5	string	N	다섯번째카드이미지MaaP URL
	title6	string	N	여섯번째카드제목 (최대30자)
	description6	string	N	여섯번째카드본문 (최대1300자)
	media6	string	N	여섯번째카드이미지MaaP URL

버튼 설정 방법

Key 1 : suggestions

첨부된 메시지의 개수만큼 반복한다 . 만약 버튼이 없는 메시지가 포함되어 있다면 ‘{}’ 의 형태로 기입한다.

예를들어 3개의 캐로셀 중 첫번째, 세번째 메시지만 버튼이 있는 경우

"buttons": [
    {
        "suggestions": {……..
        }
    },
    {},
    {
        "suggestions": {……..
        }
    }
]

Key 2 : action

버튼 클릭 시 수행할 액션. 버튼의 개수만큼 해당 오브젝트를 작성 한다.

"buttons": [
    {
        "actions":{
            "urlAction":{ //URL 연결
                "openUrl":{ //버튼 클릭 시 연결할 URL
                    "url": "string" //상세 URL
                }        
            },
            "dialerAction":{ //전화 걸기
                "dialPhoneNumber":{ //버튼 클릭 시 연결할 전화번호
                    "phoneNumber": "string" //상세 전화번호
                }
            },
            "composeAction":{ //메시지 전송
                "composeTextMessage":{  //버튼 클릭 시 메시지 전송
                    "phoneNumber": "string", //수신자 전화번호
                    "text": "string" //메시지 본문내용
                }
            },
            "mapAction":{ //지도 보여주기, 현재 위치 공유
                "showLocation":{ //버튼 클릭 시 지도 표기 할 지역
                    "location":{ //버튼 클릭 시 지도 표기 할 지역
                        "query": "string", //맵 검색 키워드 (쿼리 방식 시)
                        "latitude": "double", //위도 (좌표 방식 시)
                        "longitude": "double", //경도 (좌표 방식 시)
                        "label": "string" //표기 라벨 (좌표 방식 시)
                    }
                }
            },
            "calendarAction":{ //캘린더 등록
                "createCalendarEvent":{ //버튼 클릭 시 캘린더에 등록할 내용
                    "startTime": "string", //시작 시간
                    "endTime": "string", //종료 시간
                    "title": "string", //제목
                    "description": "string" //상세 설명
                }
            },
            "clipboardAction":{ //복사하기
                "copyToClipboard":{ //버튼 클릭 시 클립보드에 복사
                    "text": "string" //복사할 내용
                }
            },
            "displayText": "string" //버튼에 표기될 text 
            "postback":{ //현재 미사용
                "data": "" //현재 미사용 빈 문자열로 요청
            }
        }
    }
]

타입별 버튼 구성 예시

1. MMS_ Carousel Medium : 버튼 최대 2개까지 사용가능

2. MMS_ Carousel Small : 버튼 최대 2개까지 사용가능

Request Body 예시

{
  "msg_type": "RMC",
  "msg_data": [
    {
      "msg_key": "RCS 캐로셀 미디엄",
      "sender_number": "{{send_no_rcs}}",
      "receiver_number": "{{receive_no}}",
      "msg_base_id": "CMwMhM0600",
      "header": "1",
      "footer": "{{footer}}",
      "copy_allowed": true,
      "msg": {
        "body": {
          "title1": "title1",
          "description1": "description1",
          "media1": "{{url1}}",
          "title2": "title2",
          "description2": "description2",
          "media2": "{{url2}}",
          "title3": "title3",
          "description3": "description3",
          "media3": "{{url3}}",
          "title4": "title4",
          "description4": "description4",
          "media4": "{{url4}}",
          "title5": "title5",
          "description5": "description5",
          "media5": "{{url5}}",
          "title6": "title6",
          "description6": "description6",
          "media6": "{{url6}}"
        }
      },
      "brand_key": "{{brand_key_rcs}}",
      "brand_id": "{{brand_id_rcs}}"
    }
  ]
}

Response Body

키		타입	설명
results		array	메시지 수신 데이터
	msg_key	string	메시지고유 키
	code	string	접수 결과 코드
	desc	string	접수 결과 코드 상세

{
    "results": [
        {
            "code": "string",
            "msg_key": "string",
            "desc": "string"
        }
    ]
}