2.8 메시지 리포트

목차

• 1. 리포트 요청 (Polling 방식)
• 2. 리포트 처리 결과 전달 (Polling 방식)
• 3. 리포트 전달 (Webhook 방식)
• 4. 리포트 조회
• Appendix

베이스 URL

구분	접속 URL
상용	https://api.msghub.uplus.co.kr
검수	https://api.msghub-qa.uplus.co.kr

📌 주의사항

1. 2025년까지 브랜드톡의 productCode는 친구톡 상품코드로 표현됩니다.
2. 2026년 이후 브랜드톡의 productCode는 친구/비친구 상품코드로 표현됩니다.

코드	설명
KFRT1	친구톡 Text
KFRM2	친구톡 이미지
KFRM3	친구톡 와이드
KFRM4	친구톡 아이템리스트
KFRM5	친구톡 캐러셀
KFRM6	친구톡 프리미엄
KFRM7	친구톡 커머스
KFRM8	친구톡 캐러셀 커머스
BRDF	브랜드톡 친구
BRDNF	브랜드톡 비친구

1. 리포트 요청 (Polling 방식)

실시간으로 처리가 완료된 메시지의 결과를 전달합니다. 메시지 결과는 한 번만 전달됩니다.

📌 주의사항

1. 리포트 요청 결과가 1건이라도 있으면, 즉시 다음 요청을 시작해야 합니다. 없을 경우 잠시 대기 후 재요청해야 합니다. (한 번에 최대 100개 리포트 수신 가능, 배열 형태로 전달됨)
2. 리포트가 없을 때 무한루프 요청 방지를 위해 최소 10초 간격으로 요청해야 하며, 10초 이내 재요청 시 실패처리됩니다.
3. 리포트 결과에는 report key가 있으며, 처리 완료 후 이를 리포트 처리 결과 전달 API로 전송해야 합니다. 120초 내 전달되지 않으면 동일 리포트가 다시 내려오며, 클라이언트는 중복 수신 방지 처리를 해야 합니다.
4. 리포트를 요청하지 않으면 81시간 후 자동 만료됩니다.

---

1) 요청 (Request)

URL

GET /msg/v1.2/report HTTP/1.1

Headers

Name	Type	필수	설명
Authorization	String	●	사용자 인증 토큰
Content-Type	String	●	application/json

---

2) 응답 (Response)

Response Body

Name	Type	설명
code	String	결과 코드
message	String	결과 코드 설명
data	Object	결과 데이터 정보
data.rptKey	String	리포트 키
data.rptCnt	Integer	리포트 개수
data.rptLst	Array	리포트 목록
data.rptLst[].msgKey	String	메시지 고유 키
data.rptLst[].cliKey	String	클라이언트 키
data.rptLst[].ch	String	채널
data.rptLst[].resultCode	String	발송 결과 코드
data.rptLst[].resultCodeDesc	String	발송 결과 코드 설명
data.rptLst[].fbReasonLst	Array	Fallback 사유
data.rptLst[].fbReasonLst[].ch	String	채널
data.rptLst[].fbReasonLst[].fbResultCode	String	fallback 결과 코드
data.rptLst[].fbReasonLst[].fbResultDesc	String	fallback 결과 설명
data.rptLst[].fbReasonLst[].telco	String	이통사(*xMS, RCS만 해당) 또는 카카오 딜러사(API Key 설정: 결과 딜러사 정보 제공 Y인 경우)
data.rptLst[].telco	String	이통사 (xMS, RCS만 해당)
data.rptLst[].rptDt	String	결과 수신 일시
data.rptLst[].productCode	String	상품 코드

---

3) 요청 예시 (Sample)

Curl

curl -X GET "https://api.msghub.uplus.co.kr/msg/v1.2/report" \
  -H "accept: */*" \
  -H "Authorization: Bearer {token}"

Response

{
  "code": "10000",
  "message": "성공",
  "data": {
    "rptKey": "RPUvazue5K",
    "rptCnt": 2,
    "rptLst": [
      {
        "msgKey": "qWAr0xnmOt.6fL0d",
        "cliKey": "test001",
        "ch": "MMS",
        "resultCode": "10000",
        "resultCodeDesc": "성공",
        "fbReasonLst": [
          {
            "ch": "RCS",
            "fbResultCode": "54002",
            "fbResultDesc": "No Rcs Capability",
            "telco": "KT"
          }
        ],
        "telco": "SKT",
        "rptDt": "2025-07-15T16:51:43",
        "productCode": "LMS"
      },
      ...
    ]
  }
}

---

2. 리포트 처리 결과 전달 (Polling 방식)

요청된 리포트 키를 완료 처리할 때 이 API를 사용합니다.

📌 주의사항

120초 내 미전달 시, 리포트가 다시 전달되며 클라이언트는 중복 방지를 위한 확인 처리를 해야 합니다.

---

1) 요청 (Request)

URL

POST /msg/v1.2/report/result HTTP/1.1

Headers

Name	Type	필수	설명
Authorization	String	●	사용자 인증 토큰
Content-Type	String	●	application/json

Request Body

Name	Type	설명
rptKeyLst	Array	리포트 키 목록

---

2) 응답 (Response)

Response Body

Name	Type	설명
code	String	결과 코드
message	String	결과 코드 설명

---

3) 요청 예시 (Sample)

Curl

curl -X POST "https://api.msghub.uplus.co.kr/msg/v1.2/report/result" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"rptKeyLst": ["RPsEOqHAhA","RPsQOqHAhB","RPsEOqHAhC"...]}'

Response

{
  "code": "10000",
  "message": "성공"
}

---

3. 리포트 전달 (Webhook 방식)

처리 완료된 메시지를 고객사의 웹훅 URL로 실시간 전달합니다. 메시지는 단 1회만 전달되며, 실패 시 재시도합니다 (기본 10초, 추후 변경 가능). 리포트는 72시간 보관됩니다.

📌 주의사항

1. userCustomFields - 사용자 정의 필드를 사용하기 위해서는, 콘솔에서 설정이 필요합니다.

• 메시지허브 관리자콘솔 > 프로젝트 > 프로젝트 상세 > API KEY > apiKey 선택 > 수정
• 결과수신 방법 Webhook 선택 > 추가 필드 사용 선택

---

1) 요청 (Request from Msghub to Client)

URL

POST {WEBHOOK_URL}

(고객사에서 Msghub에 등록한 Webhook URL)

Headers

Name	Type	설명
Content-Type	String	application/json

Request Body

Name	Type	설명
rptCnt	Integer	리포트 개수 (최대 100개)
rptLst	Array	리포트 목록
rptLst[].isBi	Boolean	RCS 양방향 메시지 여부
rptLst[].msgKey	String	메시지 고유 키
rptLst[].cliKey	String	클라이언트 키
rptLst[].ch	String	채널
rptLst[].resultCode	String	발송 결과 코드
rptLst[].resultCodeDesc	String	결과 코드 설명
rptLst[].productCode	String	상품 코드
rptLst[].fbReasonLst	Array	Fallback 사유
rptLst[].fbReasonLst[].ch	String	채널
rptLst[].fbReasonLst[].fbResultCode	String	fallback 결과 코드
rptLst[].fbReasonLst[].fbResultDesc	String	fallback 결과 설명
rptLst[].fbReasonLst[].telco	String	이통사(*xMS, RCS만 해당) 또는 카카오 딜러사(API Key 설정: 결과 딜러사 정보 제공 Y인 경우)
rptLst[].rptDt	String	결과 수신 일시
rptLst[].rptRegDt	String	결과 등록 일시
rptLst[].phone	String	수신번호
rptLst[].userCustomFields	Object	사용자 정의 필드
rptLst[].recvDt	String	발송 요청 일시

2) 응답 (Response from Client to Msghub)

Msghub로 성공적인 수신을 알리기 위해 HTTP 200 OK 응답을 보내야 합니다.

HTTP	Description	비고
200	성공	-
204	성공	응답 혹은 처리 할 리포트가 없음
400	실패	실패로 전달시 재처리 가능함

---

3) 수신 예시 (Sample Payload to Webhook)

JSON Body

{
    "rptCnt": 1,
    "rptLst": 2
     {

        "isBi": false, "msgKey": "lXXYpOIuCd.6cGlYN",
        "msgKey": "lAXYpOIuDd.1cGlYD",
        "ch": "SMS",001
        "resultCode": "10000",
        "resultCodeDesc": "성공",
        "productCode": "SMS",
        "fbReasonLst": [
          {
            "ch": "RCS",
            "fbResultCode": "54002",
            "fbResultDesc": "No Rcs Capability",
            "telco": "KT"
          }
        ],
        "rptDt": "2025-04-19T15:01:40",
        "rptRegDt": "2025-04-19T15:01:40",
        "phone": "01012341234",
        "userCustomFields": {
           "key1": "value1",
           "key2": 123
         },
        "recvDt": "2025-04-18T15:01:40"
    ],
      ...
}

---

4. 리포트 조회

cliKey와 발송일을 기준으로 최대 90일 이내 메시지 상태를 조회합니다.

---

1) 요청 (Request)

URL

POST /msg/v1/sent HTTP/1.1

Headers

Name	Type	필수	설명
Authorization	String	●	사용자 인증 토큰
Content-Type	String	●	application/json

Request Body

Name	Type	설명	비고
cliKeyLst	Array	조회할 cliKey 목록	최대 10건

cliKeyLst 객체 상세

Name	Type	필수	설명
cliKey	String	●	고객이 부여한 메시지 키
reqDt	String	●	발송일자 (YYYY-MM-DD)

---

2) 응답 (Response)

Response Body

Name	Type	설명
code	String	결과 코드
message	String	설명
data.cliKeyLst	Array	클라이언트키 목록
data.cliKeyLst[].msgKey	String	메시지 고유 키
data.cliKeyLst[].cliKey	String	클라이언트 키
data.cliKeyLst[].ch	String	채널
data.cliKeyLst[].status	String	상태 (REG, ING, DONE, OVER_DATE, INVALID_KEY)
data.cliKeyLst[].resultCode	String	결과 코드
data.cliKeyLst[].resultCodeDesc	String	설명
data.cliKeyLst[].telco	String	이통사(*xMS, RCS만 해당) 또는 카카오 딜러사(API Key 설정: 결과 딜러사 정보 제공 Y인 경우)
data.cliKeyLst[].fbReasonLst	Array	Fallback 사유
data.cliKeyLst[].fbReasonLst[].ch	String	채널
data.cliKeyLst[].fbReasonLst[].fbResultCode	String	fallback 결과 코드
data.cliKeyLst[].fbReasonLst[].fbResultDesc	String	fallback 결과 설명
data.cliKeyLst[].fbReasonLst[].telco	String	이통사(*xMS, RCS만 해당) 또는 카카오 딜러사(API Key 설정: 결과 딜러사 정보 제공 Y인 경우)
data.cliKeyLst[].rptDt	String	결과 수신 일시
data.cliKeyLst[].productCode	String	상품 코드

3) 요청 예시 (Sample)

Curl

curl -X POST "https://api.msghub.uplus.co.kr/msg/v1/sent" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "cliKeyLst": [
      {
        "cliKey": "cliKey",
        "reqDt": "2025-07-02"
      }
    ]
  }'

Response

{
{
  "code": "10000",
  "message": "성공",
  "data": {
    "cliKeyLst": [
      {
        "msgKey": "lABCCdzcmw.1fLTAb",
        "cliKey": "cliKey",
        "ch": "SMS",
        "status": "DONE",
        "resultCode": "10000",
        "resultCodeDesc": "성공",
        "telco": "LGU",
        "fbReasonLst": [
          {
            "ch": "RCS",
            "fbResultCode": "54002",
            "fbResultDesc": "No Rcs Capability",
            "telco": "KT"
          }
        ],
        "rptDt": "2025-07-02T13:46:03",
        "productCode": "SMS"
      },
      ...
    ]
  }
}

---

Appendix

메시지 상태 코드

코드	설명
REG	접수완료
ING	처리중
DONE	완료
OVER_DATE	조회기간 초과 (90일)
INVALID_KEY	키 오류