Only this pageAll pages
Powered by GitBook
1 of 7

중계사-통신사 RCS 발송규격

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

About

중계사에 제공되는 이통 공통 연동 규격서입니다.

버전 정책

  • URL에 사용되는 버전은 2 depth로 한다. 예) 1.x

  • 버그 픽스, 마이너한 업데이트는 swagger version의 3 depth를 counting함 예) 1.x.x, URL에서는 2 depth를 사용.

  • 중요한 업데이트는 1, 2 depth를 counting함. 예) 2.x 또는 1.9

  • MaaP FE는 버전 업데이트를 고려하여 URL을 처리 할 수 있다

참여자

  • SKT 강정원, KT 백석문, LGU 정인정

참고문서

  • 링크 : RCS A2P(단방향) 포맷 리스트 (24.02.07 공유버전)

  • 링크 : RCS 양방향 포맷 리스트 (22.10.28 공유 버전)

  • 링크 : 신규 포맷 MMS (신규 메시징) 발송 규격서 (22.10.28 공유 버전)

  • 링크 : 신규 포맷 MMS (신규 메시징) 기획서 (22.10.28 공유 버전)

수정이력

1.2.0 (이미지 클릭시 동작, itmpl 상품 추가, 보안성 강화) (박기남, 20221014)

  • 메시지내 이미지 클릭시 동작 관련 /message.body - example 업데이트

  • /message - productCode : 이미지 템플릿 itmpl 상품 추가

  • 보안성 강화 관련 /message 에 agencyKey, brandKey 추가 : '23년 8월부터 필수

  • 보안성 강화 관련 /message 의 Success response 내 reason 추가 (2022.11.10)

  • 보안성 강화 관련 전송 URL 버전 1.2로 수정, 버전 1.1은 '23년 6월 decomm 예정 (2022.11.24)

  • /momsg 설명 수정: 각 통신사 MaaP FE 가 moMsgWebhookUrl 에 {SKT|KT|LGU} 추가 (2022.11.24)

1.1.9 (신규 메시징 규격, expiryOption3/4, 참고문서 추가)

  • /file - messagebaseId 추가 (박지범, 20220419)

  • /message - 신규 메시징 관련 파라미터 example 추가 (박지범, 20220419)

  • FileInfo - messagebaseId 추가 (박기남, 20220701)

  • /message.expiryOption 1 수정(3일 -> 1일), 3/4 추가 (박기남, 20220824)

  • /message.chupList - '세션 메시지' -> '양방향 대화방' 으로 수정 (박기남, 20221018)

  • /message.body - description 및 example 수정, 참고문서 추가 (박기남, 20221028)

1.1.8 (동영상 스트리밍 전송을 위한 규격 추가)

  • TTA iframeplayB 규격, 현재는 YouTube URL 주소만 전송 가능

  • /message - body, footer 에 전송 예제 추가 (고병현, 박기남 20220128)

1.1.7 (양방향 서비스 지원하는 규격으로의 개정)

양방향 서비스는 중계사 발송 관점에서 아래 3가지 시나리오의 신규 스펙이 추가 됨.

  • MO(mobile-originated) Message 에 대한 웹훅 스펙

  • MO Message 에 대한 응답으로써 세션 메시지 발송 스펙

  • 자동 응답 메시지(autoReplyMsg)를 포함한 세션 메시지 발송 결과에 대한 웹훅 스펙

(박기남, 20210908)

  • /momsg 에 userLocation 추가

  • /message replyId 세션 유효시간 변경, ceiling 정책 삭제

  • /message chiplist reply/action postback data 정책 삭제

  • /file API usageType 발송가능기간 변경 (발송가능기간 D+365일 00:00, 파일유효기간 D+456일 00:00)

  • /msgstatus(webhook) 세션 메시지의 경우 설명 추가

(고병현, 20210818)

  • 양방향 메시지 발송을 위해 replyId, chipList 필드 추가

  • MO Msg Webhook 스펙 추가

  • StatusInfo 에 autoReplyMsgId, postbackId 필드 추가

  • /message productCode 필드 값 chat 추가

1.1.6 (양혜림, 20200702)

  • /file API usageType 설명 변경 : 발송가능기간 변경 (D+1일 24:00 -> D+6일 24:00, 유효기간 변경 D+4일 24:00 -> D+9일 24:00)

1.1.5 (이재영, 20200313)

  • /message에 productCode 옵션으로 추가

1.1.4 (고병현, 20200226)

  • /message API 상세 설명 업데이트

  • FileInfo expiryDate 상세설명 추가

  • footer : 최대 길이 수정

1.1.3 (이재영, 20190925)

  • 에러코드 관련 수정 : Error 객체 생성, StatusInfo에 error 항목 추가

  • header : 필수 항목으로 변경

  • footer : 설명 및 샘플 추가

Message

File

Momsg (webhook)

API reference

Msgstatus (webhook)

Token

Response

Body

Name
Type
Description

name

string

Name of the user

age

number

Age of the user

{
  "id": 1,
  "name": "John",
  "age": 30
}
{
  "error": "Invalid request"
}

메시지 전송 요청

post
Authorizations
Body
clientMsgIdstring · max: 40RequiredExample: client_id_1
chatbotIdstring · max: 40RequiredExample: 15440000
messagebaseIdstring · max: 40Required

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

Example: MMS001
productCodestring · enumOptional

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

Possible values:
userContactstring · max: 40RequiredExample: 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: 1Optional

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

Example: 1
groupIdstring · max: 20Optional

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

Example: groupdId_0001
headerstring · enumRequired

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

Example: 0Possible values:
footerstring · max: 20Optional

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

Example: 080-0000-0000
copyAllowedbooleanOptional

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

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[]Optional
  • 버튼(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: 20Optional
  • 중계사가 /momsg (webhook) 으로 받은 replyId 를 포함해서 발송 시에만 F/E에서 유효한 세션 메시지로 처리됨. * 전달받은 replyId 는 24시간 유효함.
chipListobjectOptional
  • 양방향 대화방에서만 허용하고 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
200
success
application/json
default
fail
application/json
post
POST /ag/1.2/message HTTP/1.1
Host: maapdomain.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 3322

{
  "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"
        }
      }
    }
  ]
}
{
  "code": "4xxxx",
  "message": "error message"
}

중계사 파일 등록 요청

post
Authorizations
Body
fileIdstring · max: 64Required

사전등록할 file ID로 유니크하게 생성되어야 한다. 생성가이드 {brandId}.{userCode} 또는 {chatbotId}.{userCode}

Example: brandId.FDSAF.432153214
usageTypestring · enum · max: 10Required

사용타입 별 설명.

  • send : 메시지 발송에 사용할 파일 (발송가능기간 D+365일 00:00, 파일유효기간 D+456일 00:00)
Default: sendPossible values:
mimeTypestringRequired

mime type. 예) image/jpeg, image/png, MimeType 설명

Example: image/jpeg
filestring · binaryRequired
messagebaseIdstring · max: 40Optional

(신규포맷 mms 전용) 이미지 파일이 사용될 messagebase 템플릿 ID. 등록하고자 하는 이미지의 width, height가 해당하는 템플릿에 적합한 지 validation check를 수행한다.

Responses
200
success
application/json
default
fail
application/json
post
POST /ag/1.2/file HTTP/1.1
Host: maapdomain.com
Authorization: Bearer JWT
Content-Type: multipart/form-data
Accept: */*
Content-Length: 118

{
  "fileId": "brandId.FDSAF.432153214",
  "usageType": "send",
  "mimeType": "image/jpeg",
  "file": "binary",
  "messagebaseId": "text"
}
{
  "status": "200",
  "data": {
    "fileInfo": {
      "fileId": "brandId.FDSAF.432153214",
      "usageType": "send",
      "mimeType": "image/jpeg",
      "status": "ready",
      "expiryDate": "2019-08-06T07:08:38.426+09"
    }
  }
}

파일 상태 조회 요청

get
Authorizations
Path parameters
fileIdstringRequired

file ID

Responses
200
success
application/json
default
fail
application/json
get
GET /ag/1.2/file/{fileId} HTTP/1.1
Host: maapdomain.com
Authorization: Bearer JWT
Accept: */*
{
  "status": "200",
  "data": {
    "fileInfo": {
      "fileId": "brandId.FDSAF.432153214",
      "usageType": "send",
      "mimeType": "image/jpeg",
      "status": "ready",
      "expiryDate": "2019-08-06T07:08:38.426+09"
    }
  }
}

MO 메시지 이벤트를 중계사로 전달한다.

post

등록된 양방향 서비스를 사용하는 챗봇의 moMsgWebhookUrl 를 RBC 가 MaaP FE 로 전달하고, MaaP FE 는 전달받은 moMsgWebhookUrl 의 마지막 부분에 각 통신사 구분자URL {SKT|KT|LGU} 을 추가하여 이벤트를 전달된다. 예> RBC 가 MaaP FE 로 전달한 moMsgWebhookUrl 이 http://clientservice/momsg 인 경우, KT MaaP FE 는 http://clientservice/momsg/KT 로 전달. 규격은 array 형태이나, 실제 통신사 Maap FE 는 단건(1건) 단위로 전송한다.

Authorizations
Bodyobject[]
replyIdstring · max: 40Required

F/E 에서 제공하는 고유 id 로 이후에 중계사가 세션 메시지를 발송하려면 이 값을 /message API의 replyId로 포함해야 함. replyId는 24시간 유효함.

eventTypestring · enumRequired
  • FNW.11 스펙 2.15 - WebhookPayload 참고 (https://www.gsma.com/futurenetworks/wp-content/uploads/2017/11/FNW.11_v1.0.pdf)
  • MoMsgInfo 웹훅에 포함하는 이벤트 타입은 아래 3종류임.
    • message:유저가 직접 작성한 메시지 (text, file, userLocation message)
    • response:(persistent menu 혹은 메시지의 reply 버튼, chip list 의 reply 누를 때)
    • newUser:대화방 최초 진입 후 단말에서 자동 발신되는 메시지
Possible values:
postbackIdstring · max: 40Optional

response 이벤트 only - 대화방메뉴내 reply 클릭 시에, 속성으로 포함된 postbackId 값을 전달

postbackDataobjectOptional

newUser, response 이벤트 only - 칩리스트/리치카드 버튼 중 reply 클릭 시에, 발송 요청시 포함되었던 postbackData 값을 그대로 전달

displayTextstring · max: 100Optional

response - 발송 요청시 포함되었던 버튼의 텍스트를 그대로 전달, newUser 인 경우 '안녕'

messageBodyobjectOptional

message 이벤트 only

  • 텍스트 메시지의 경우: {"textMessage": "hello world"}
  • 파일 메시지의 경우: {"fileMessage":{"fileUrl": "https://maap-example.com/file.jpeg","fileMIMEType": "image/jpeg"}}
  • userLocation 메시지의 경우: {"geolocationPushMessage": {"label": "meeting location","timestamp": "2021-08-10T09:19:44Z","timeOffset": -540,"pos": "37.3587121 127.1151084","radius": 0}}
userContactstring · max: 40Required

유저 번호

chatbotIdstring · max: 40Required

대화방 chatbotId

timestampstring · date-timeRequired

응답한 시간

Responses
200
아래 예는 4가지 케이스에 대한 예시이다. * A: 유저가 직접 입력한 메시지 발송 * B: 대화방메뉴 중 reply 눌렀을 때 * C: 칩리스트/리치카드 버튼 중 reply 눌렀을 때 * D: 유저가 딥링크 등을 통해 신규로 대화방 진입하여 단말에서 자동으로 메시지 발송
default
fail
application/json
post
POST /ag/1.2/momsg (webhook) HTTP/1.1
Host: maapdomain.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 726

[
  {
    "replyId": "A",
    "eventType": "message",
    "messageBody": {
      "textMessage": "hello world"
    },
    "userContact": "01012341234",
    "chatbotId": "bot_1",
    "timestamp": "2019-08-19T04:43:55.867+09"
  },
  {
    "replyId": "B",
    "eventType": "response",
    "postbackId": "pid_1",
    "displayText": "대화방메뉴 버튼 텍스트",
    "userContact": "01012341234",
    "chatbotId": "bot_1",
    "timestamp": "2019-08-19T04:43:55.867+09"
  },
  {
    "replyId": "C",
    "eventType": "response",
    "postbackData": "발송 시 지정한 값",
    "displayText": "칩리스트 버튼",
    "userContact": "01012341234",
    "chatbotId": "bot_1",
    "timestamp": "2019-08-19T04:43:55.867+09"
  },
  {
    "replyId": "D",
    "eventType": "newUser",
    "displayText": "안녕",
    "userContact": "01012341234",
    "chatbotId": "bot_1",
    "timestamp": "2019-08-19T04:43:55.867+09"
  }
]

No content

메시지 전송 결과를 중계사로 전달한다.

post

MaaP FE에서 중계사에서 제공한 webhook 주소 하위의 /msgstatus로 데이터를 전달한다.예) http://clientservice/message/{SKT|KT|LGU}/msgstatus MaaP FE는 주기적(예, 100ms)으로, 혹은 최대 100건까지 array로 전송 결과를 전달한다. 최대 건수로 전달한 경우 즉시 다음 작업을 진행한다. 중계사는 MaaP FE의 IP를 방화벽 등록하여 정상적인 이통사 데이터만 받을 수 있도록 한다. 아래 예는 다음 케이스에 대한 예시임. 세션 메시지의 발송 실패의 경우 항상 비과금 처리됨.

  • A: A2P 발송 성공
  • B: A2P 발송 실패
  • C: AutoReplyMsg 발송 성공 (과금)
  • D: AutoReplyMsg 발송 성공 (비과금)
  • E: AutoReplyMsg 발송 실패
  • F: 중계사 발송 세션 메시지 발송 성공 (과금)
  • G: 중계사 발송 세션 메시지 발송 성공 (비과금)
  • H: 중계사 발송 세션 메시지 발송 실패
Authorizations
Bodyobject[]
clientMsgIdstring · max: 40Required
  • 중계사에서 전달한 메시지 Id.
  • autoReplyMsg 값이 존재할 경우 이통 MaaP 에서 자동으로 발송된 메시지로 clientMsgId 도 이통에서 생성한 값이 됨.
statusstring · enum · max: 10Required

success:단말전달성공, fail:단말전달실패

Possible values:
timestampstring · date-timeRequired

메시지 상태 업데이트 시간. MaaP Core에서 전달하는 경우만 포함

autoReplyMsgIdstring · max: 40Optional

사전 정의된 autoReplyMsg 가 발송되었을 경우 포함함.

postbackIdstring · max: 40Optional

사전 정의된 autoReplyMsg 가 발송되었을 경우 trigger 시킨 persistentMenu - reply 의 postbackId를 포함함.

userContactstring · max: 40Optional

사전 정의된 autoReplyMsg 가 발송되었을 경우 발송된 유저 번호를 포함함.

chatbotIdstring · max: 40Optional

사전 정의된 autoReplyMsg 가 발송되었을 경우 chatbot Id 포함함.

billinteger · enumOptional

세션 메시지 (replyId 를 포함하여 발송된 메시지) 의 과금 여부. 세션 메시지에 대한 통신3사 과금 정책에 따른 세션시간(ex. 24시간) 기준, 최대 과금건수 N건 까지 과금되고 이후부터 과금되지 않음. 0 - 과금 안 된 메시지 1 - 과금 된 메시지

Possible values:
Responses
200
중계사는 webhook 을 정상적으로 받을 시 200 OK를 응답해야 함
default
fail
application/json
post
POST /ag/1.2/msgstatus (webhook) HTTP/1.1
Host: maapdomain.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 1098

[
  {
    "clientMsgId": "A",
    "status": "success",
    "timestamp": "2019-08-19T04:43:55.867+09"
  },
  {
    "clientMsgId": "B",
    "status": "fail",
    "error": {
      "code": "40000",
      "message": "error reasone"
    },
    "timestamp": "2019-08-19T04:43:55.867+09"
  },
  {
    "clientMsgId": "C",
    "status": "success",
    "timestamp": "2019-08-19T04:43:55.867+09",
    "autoReplyMsgId": "auto_1",
    "postbackId": "pid_1",
    "userContact": "01012341234",
    "chatbotId": "bot_1",
    "bill": 1
  },
  {
    "clientMsgId": "D",
    "status": "success",
    "timestamp": "2019-08-19T04:43:55.867+09",
    "autoReplyMsgId": "auto_1",
    "postbackId": "pid_1",
    "userContact": "01012341234",
    "chatbotId": "bot_1",
    "bill": 0
  },
  {
    "clientMsgId": "E",
    "status": "fail",
    "error": {
      "code": "40000",
      "message": "error reasone"
    },
    "timestamp": "2019-08-19T04:43:55.867+09",
    "autoReplyMsgId": "auto_1",
    "postbackId": "pid_1",
    "userContact": "01012341234",
    "chatbotId": "bot_1",
    "bill": 0
  },
  {
    "clientMsgId": "F",
    "status": "success",
    "timestamp": "2019-08-19T04:43:55.867+09",
    "bill": 1
  },
  {
    "clientMsgId": "G",
    "status": "success",
    "timestamp": "2019-08-19T04:43:55.867+09",
    "bill": 0
  },
  {
    "clientMsgId": "H",
    "status": "fail",
    "error": {
      "code": "40000"
    },
    "timestamp": "2019-08-19T04:43:55.867+09",
    "bill": 0
  }
]

No content

Access 토큰을 발급

post

JWT token을 발행한다. 발행 시 클라이언트 ID가 claim에 저장된다. (아래내용은 SKT에서 ID 관리정책에 대한 명기를 요청하여 기술함 ) 한 중계사는 용도에 따라 다수의 클라이언트 ID를 할당 받을 수 있다. MaaP FE는 클라이언트 ID 마다 아래 속성을 부여하여 처리할 수 있다. - 우선순위 : 실시간, 일반, 배치 - 속도제어(TPS) : 초당 메시지 발송 최대 건수. 보안을 위해 accessToken에 client의 outbound IP를 저장하여 접속을 제한 할 수 있다. 중계사는 oubbound IP가 고정되지 않을 경우 이통사와 별도 협의를 진행하여야 한다.

Body
clientIdstring · max: 20RequiredExample: clientId001
clientSecretstring · max: 255RequiredExample: secretString
grantTypestring · enumRequired

명시적인 요청을 위해 사용되는 필드로 clientCredentials 값을 입력한다

Example: clientCredentialsPossible values:
Responses
200
success
application/json
default
fail
application/json
post
POST /ag/1.2/token HTTP/1.1
Host: maapdomain.com
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "clientId": "clientId001",
  "clientSecret": "secretString",
  "grantType": "clientCredentials"
}
{
  "status": "200",
  "data": {
    "tokenInfo": {
      "accessToken": "xxxx",
      "expiresIn": "6000"
    }
  }
}