2.8 메시지 리포트

목차

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

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) 요청 (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	수신번호

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": "2022-04-19T15:01:40"
        "rptDt": "2025-04-19T15:01:40",
        "rptRegDt": "2025-04-19T15:01:40",
        "phone": "01012341234"
    ],
      ...
}

---

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	키 오류