중계사-통신사 RCS 발송규격
  • About
  • API reference
    • Token
    • Message
    • File
    • Msgstatus (webhook)
    • Momsg (webhook)
  • Specification
Powered by GitBook
On this page
Export as PDF
  1. API reference

Message

PreviousTokenNextFile

메시지 전송 요청

post

/message

Authorizations
Body
clientMsgIdstring · max: 40required
Example: client_id_1
chatbotIdstring · max: 40required
Example: 15440000
messagebaseIdstring · max: 40required

특정 발신번호(chatbotId)에만 사용 가능한 messagebaseId를 관계없는 발신번호에 사용 시 실패 리턴된다.

Example: MMS001
productCodestring · enum

상품종류, messagebaseId에 등록된 productCode를 사용해야 하며 그렇지 않으면 실패처리된다. MaaP FE에서는 해당 필드가 있으면 validation을 체크하고 없으면 체크하지 않는다. 추후, 필수 필드로 변경한다. (미정)

Options: sms, lms, mms, tmplt, itmpl, chat
userContactstring · max: 40required
Example: 01000000000
agencyIdstring · max: 20required

최초 메시지 발송 대행사의 agencyId.대행사 ID로 발신번호(chatbotId)에 대한 발송 권한이 대행사에 있는지 체크하여 권한 없을 시 실패 리턴된다.

Example: agency01
agencyKeystring · max: 64required

최초 메시지 발송 대행사의 agencyKey. agencyId 의 agencyKey 가 맞는지 비교하여 서로 다른 경우 실패 리턴된다 ('23.8월부터 필수)

Example: AK.Ti53fRiKmBV9OPu
brandKeystring · max: 64required

챗봇(발신번호) 이 속한 브랜드의 brandKey. brandId 의 brandKey 가 맞는지 비교하여 서로 다른 경우 실패 리턴된다 ('23.8월부터 필수)

Example: BK.Ti53fRiKmBV9OPu
expiryOptioninteger · max: 1

1 - 1일 동안 시도 후 revoke 되고 결과 리턴(기본값). 2 - 30초 동안 시도 후 revoke 되고 결과 리턴. 3 - 180초(3분) 동안 시도 후 revoke 되고 결과 리턴. 4 - 3600초(1시간) 동안 시도 후 revoke 되고 결과 리턴.

Example: 1
groupIdstring · max: 20

발송 캠페인 단위의 구분을 위해 사용하는 ID이다. 중계사는 캠페인 대량 발송 등에서 groupId 값 사용을 권장한다.

Example: groupdId_0001
headerstring · enumrequired

0 - 정보성 메시지. 1 - 광고성 메시지. 특정 messagebase는 광고성 메시지를 허용하지 않음.

Example: 0
Options: 0, 1
footerstring · max: 20

무료수신거부 번호, MaaP FE에서 '무료수신거부:'를 string 앞에 자동으로 붙여서 단말에 내려가게 한다. header의 값이 광고성일 때 footer 값을 포함하지 않고 발송하면 실패 처리된다. 단, iframeplayB 동영상 스트리밍 메시지 발송시에는 다음와 같이 동작한다. header의 값이 광고성일 때는 무료수신거부 번호 아래 줄에 '동영상 재생시 데이터 요금제가 적용됩니다' 라는 문구가 자동으로 붙어서 단말로 내려가고, header의 값이 정보성일 때는 '동영상 재생시 데이터 요금제가 적용됩니다' 라는 문구만 자동으로 붙어서 단말로 내려간다.

Example: 080-0000-0000
copyAllowedboolean

해당 메시지에 대한 단말의 메시지 복사 기능을 허용할지 여부를 지정한다.

Example: false
bodyobjectrequired
  • body 구성시 # 참고문서 RCS A2P(단방향) 및 양방향 포맷리스트, 신규 포맷 MMS (신규 메시징) 발송 규격서 및 기획서 링크 참조
  • 동영상 스트리밍 메시지 전송
    • RCS 동영상 스트리밍(iframeplayB) 메시지를 전송하고자 할 때는 mediamedia(n) 의 값을 아래 3가지 형태의 YouTube URL 주소로 지정하여 전송 가능 (YouTube URL 주소는 정확한 형식을 준수해야 하며, 일부분만 일치하는 경우는 실패됨. submediasubmedia(n) 으로 동영상 스트리밍 발송은 불가)
      • “media1” : “https://www.youtube.com/watch?v=[videoId],maapfile://{thumbnail용 fileId_1}”
      • “media2” : “https://youtu.be/[VideoId],maapfile://{thumbnail용 fileId_2}”
      • “media3” : “https://m.youtube.com/watch?v=[videoId],maapfile://{thumbnail용 fileId_3}”
    • 이때 YouTube URL 에 이어서 콤마(,) 구분자와 함께 thumbnail 에 표시될 send 용 fileId 를 지정해야 함. thumbnail 은 maapfile:// 스키마를 사용하며, 동영상 스트리밍 메시지 썸네일의 이미지임.(썸네일 이미지가 유효하지 않을 경우는 실패됨)
    • footer 영역에는 동영상 실행시 과금됨을 알리는 문구가 자동으로 들어감
Example: {"title1":"제목","description1":"본문 텍스트","media1":"maapfile://{fileId_1}","mediaUrl1":"URL > 이미지(media1) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기","title2":"제목 2번째 카드","description2":"본문 텍스트","media2":"maapfile://{fileId_2}","mediaUrl2":"URL > 이미지(media2) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기","title3":"제목 3번째 카드","description3":"본문 텍스트","media3":"maapfile://{fileId_3}","mediaUrl3":"URL > 이미지(media3) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기","media":"maapfile://{fileId_main} > main 이미지","mediaUrl":"URL > main 이미지(media) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기","title":"제목 텍스트 > main 제목","description":"본문 텍스트 > main 본문","subMedia1":"maapfile://{fileId_sub1} > (신규포맷 mms 전용) 서브 이미지 1","subMediaUrl1":"URL > (신규포맷 mms 전용) 서브 이미지 1 클릭 시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기","subTitle1":"제목 텍스트 > (신규포맷 mms 전용) 소제목 1","subDesc1":"본문 텍스트 > (신규포맷 mms 전용) 소본문 1","subMedia2":"maapfile://{fileId_sub2} > (신규포맷 mms 전용) 서브 이미지 2","subMediaUrl2":"URL > (신규포맷 mms 전용) 서브 이미지 2 클릭 시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기","subTitle2":"제목 텍스트 > (신규포맷 mms 전용) 소제목 2","subDesc2":"본문 텍스트 > (신규포맷 mms 전용) 소본문 2","subMedia3":"maapfile://{fileId_sub3} > (신규포맷 mms 전용) 서브 이미지 3","subMediaUrl3":"URL > (신규포맷 mms 전용) 서브 이미지 3 클릭 시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기","subTitle3":"제목 텍스트 > (신규포맷 mms 전용) 소제목 3","subDesc3":"본문 텍스트 > (신규포맷 mms 전용) 소본문 3"}
buttonsobject[]
  • 버튼(suggestions)의 구성은 GSMA RCC.07 스펙 - 3.6.10.4 의 JSON schema 를 참고한다. (https://www.gsma.com/newsroom/wp-content/uploads//RCC.07-v12.0-4.pdf)
  • A2P 메시지의 경우 action 만 사용 가능함
  • 세션 메시지의 경우 action, reply 모두 사용 가능함
  • 버튼부 구성 예시 - Carousel에서 3장의 카드가 있고 각각 2, 0, 1개의 버튼이 있다고 가정하면 buttons는 아래와 같이 구성 할 수 있다.
Example: [{"suggestions":[{"action":{"urlAction":{"openUrl":{"url":"https://www.google.com"}},"displayText":"Open website or deep link","postback":{"data":"set_by_chatbot_open_url"}}},{"action":{"urlAction":{"openUrl":{"url":"https://www.google2.com"}},"displayText":"Open website or deep link","postback":{"data":"set_by_chatbot_open_url_2"}}}]},{},{"suggestions":[{"action":{"urlAction":{"openUrl":{"url":"https://www.google2.com"}},"displayText":"Open website or deep link","postback":{"data":"set_by_chatbot_open_url_2"}}}]}]
replyIdstring · max: 20
  • 중계사가 /momsg (webhook) 으로 받은 replyId 를 포함해서 발송 시에만 F/E에서 유효한 세션 메시지로 처리됨. * 전달받은 replyId 는 24시간 유효함.
chipListobject
  • 양방향 대화방에서만 허용하고 RCC.07 스펙의 Suggested Chip Lists 참고. (https://www.gsma.com/newsroom/wp-content/uploads//RCC.07-v12.0-4.pdf)
  • 칩리스트 버튼 중 reply 에서 포함한 postbackData 는 유저 클릭 이벤트 발생 시 webhook - postbackData 필드로 요청한 값 그대로 전달 됨.
Example: [{"reply":{"displayText":"Yes","postback":{"data":"returned as postbackData on webhook"}}},{"action":{"urlAction":{"openUrl":{"url":"https://www.google.com"}},"displayText":"Open website or deep link","postback":{"data":"dummy_data"}}}]
Responses
application/json
application/json
cURL
JavaScript
Python
HTTP
curl -L \
  --request POST \
  --url 'https://maapdomain.com/ag/1.2/message' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientMsgId": "client_id_1",
    "chatbotId": "15440000",
    "messagebaseId": "MMS001",
    "productCode": "sms",
    "userContact": "01000000000",
    "agencyId": "agency01",
    "agencyKey": "AK.Ti53fRiKmBV9OPu",
    "brandKey": "BK.Ti53fRiKmBV9OPu",
    "expiryOption": 1,
    "groupId": "groupdId_0001",
    "header": "0",
    "footer": "080-0000-0000",
    "copyAllowed": false,
    "body": {
      "title1": "제목",
      "description1": "본문 텍스트",
      "media1": "maapfile://{fileId_1}",
      "mediaUrl1": "URL                      > 이미지(media1) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기",
      "title2": "제목 2번째 카드",
      "description2": "본문 텍스트",
      "media2": "maapfile://{fileId_2}",
      "mediaUrl2": "URL                      > 이미지(media2) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기",
      "title3": "제목 3번째 카드",
      "description3": "본문 텍스트",
      "media3": "maapfile://{fileId_3}",
      "mediaUrl3": "URL                      > 이미지(media3) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기",
      "media": "maapfile://{fileId_main}      > main 이미지",
      "mediaUrl": "URL                       > main 이미지(media) 클릭시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기",
      "title": "제목 텍스트                   > main 제목",
      "description": "본문 텍스트             > main 본문",
      "subMedia1": "maapfile://{fileId_sub1}  > (신규포맷 mms 전용) 서브 이미지 1",
      "subMediaUrl1": "URL                    > (신규포맷 mms 전용) 서브 이미지 1 클릭 시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기",
      "subTitle1": "제목 텍스트               > (신규포맷 mms 전용) 소제목 1",
      "subDesc1": "본문 텍스트                > (신규포맷 mms 전용) 소본문 1",
      "subMedia2": "maapfile://{fileId_sub2}  > (신규포맷 mms 전용) 서브 이미지 2",
      "subMediaUrl2": "URL                    > (신규포맷 mms 전용) 서브 이미지 2 클릭 시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기",
      "subTitle2": "제목 텍스트               > (신규포맷 mms 전용) 소제목 2",
      "subDesc2": "본문 텍스트                > (신규포맷 mms 전용) 소본문 2",
      "subMedia3": "maapfile://{fileId_sub3}  > (신규포맷 mms 전용) 서브 이미지 3",
      "subMediaUrl3": "URL                    > (신규포맷 mms 전용) 서브 이미지 3 클릭 시 랜딩 URL, 값이 \"\"인 경우 이미지 전체보기",
      "subTitle3": "제목 텍스트               > (신규포맷 mms 전용) 소제목 3",
      "subDesc3": "본문 텍스트                > (신규포맷 mms 전용) 소본문 3"
    },
    "buttons": [
      {
        "suggestions": [
          {
            "action": {
              "urlAction": {
                "openUrl": {
                  "url": "https://www.google.com"
                }
              },
              "displayText": "Open website or deep link",
              "postback": {
                "data": "set_by_chatbot_open_url"
              }
            }
          },
          {
            "action": {
              "urlAction": {
                "openUrl": {
                  "url": "https://www.google2.com"
                }
              },
              "displayText": "Open website or deep link",
              "postback": {
                "data": "set_by_chatbot_open_url_2"
              }
            }
          }
        ]
      },
      {},
      {
        "suggestions": [
          {
            "action": {
              "urlAction": {
                "openUrl": {
                  "url": "https://www.google2.com"
                }
              },
              "displayText": "Open website or deep link",
              "postback": {
                "data": "set_by_chatbot_open_url_2"
              }
            }
          }
        ]
      }
    ],
    "replyId": "text",
    "chipList": [
      {
        "reply": {
          "displayText": "Yes",
          "postback": {
            "data": "returned as postbackData on webhook"
          }
        }
      },
      {
        "action": {
          "urlAction": {
            "openUrl": {
              "url": "https://www.google.com"
            }
          },
          "displayText": "Open website or deep link",
          "postback": {
            "data": "dummy_data"
          }
        }
      }
    ]
  }'
200
default
{
  "code": "4xxxx",
  "message": "error message"
}

success