2.2 문자 메시지 (SMS/MMS)

베이스 URL

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

1. SMS 발송

SMS(Short Message Service) 메시지를 발송합니다. 일반적인 텍스트 메시지를 전송할 때 사용합니다.

📌 주의사항

동보발송이란, 같은 내용의 메시지를 다수에게 동시에 보내는 발송 방식
메시지허브는 동보발송을 지원하며, 1건의 메시지에 최대 10명의 수신자를 추가하여 발송할 수 있습니다.
TPS는 수신자 수 기준으로 처리됩니다. 예시) SMS 1건에 수신자 5명을 추가하여 발송시, TPS는 5입니다.
발신번호는 사전에 등록된 번호만 사용 가능합니다.
예약발송은 현재 시점으로부터 최대 30일까지 가능합니다.
단축URL 사용 시 메시지 길이가 제한될 수 있습니다.
fbInfoLst는 발송실패시, 대체발송에 대한 객체입니다. 대체발송 채널은 SMS, MMS만 지원하며, 메인 채널과 동일할 수 없습니다.

1) 요청 (Request)

URL

POST /xms/sms/v1 HTTP/1.1

Headers

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

Request Body

Name	Type	필수	설명	크기
clickUrlYn	String	-	단축URL 사용여부 (Y/N)	1자
resvYn	String	-	예약발송 여부 (Y/N)	1자
resvReqDt	String	-	예약발송 시간 (ex. 2025-07-13 13:15)	-
agency	Object	-	대행사 정보	-
callback	String	●	발신번호	20자
campaignId	String	-	캠페인 ID	20자
deptCode	String	-	부서 코드	20자
msg	String	●	메시지 내용	90 byte
recvInfoLst	Array	●	수신자 정보 리스트	10개
fbInfoLst	Array	-	fallback 정보 리스트	-

2) 응답 (Response)

Response Body

Name	Type	설명
code	String	결과 코드
message	String	결과 메시지
data	Array	결과 데이터 목록
data[].cliKey	String	클라이언트 키
data[].msgKey	String	메시지 키
data[].phone	String	수신번호
data[].code	String	결과 코드
data[].message	String	결과 메시지

3) 요청 예시 (Sample)

Curl

curl -X POST "https://api-send.msghub-qa.uplus.co.kr/xms/sms/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
  "clickUrlYn": "N",
  "resvYn": "N",
  "resvReqDt": "2025-07-13 13:15",
  "agency": {
    "kisaOrigCode": "123456789"
  },
  "callback": "0212345678",
  "msg": "안녕하세요. 메시지허브입니다.\n문자메시지 테스트입니다. #{이름}고객님 #{나이}",
  "recvInfoLst": [
    {
      "cliKey": "test001",
      "phone": "01012341234",
      "mergeData": {
        "이름": "홍길동",
        "나이": "10"
      },
      "userCustomFields": {
        "key1": "value1",
        "key2": 123
      }
    },
    {
      "cliKey": "test002",
      "phone": "01056785678",
      "mergeData": {
        "이름": "김철수",
        "나이": "15"
      },
      "userCustomFields": {
        "key1": "value2",
        "key2": 123
      }
    }
  ],
  "fbInfoLst": [
    {
      "ch": "MMS",
      "title": "제목",
      "msg": "MMS 메시지 내용"
    }
  ]
}'

Response

{
  "code": "10000",
  "message": "성공",
  "data": [
    {
      "cliKey": "test001",
      "msgKey": "3jVnyk0m8U.6fKG1w",
      "phone": "01012341234",
      "code": "10000",
      "message": "성공"
    },
    ...
  ]
}

예약발송 응답

{
  "code": "10000",
  "message": "성공",
  "data": {
    "regDt": "2026-04-08T11:16:55",
    "webReqId": "RRR...b5jv"
   }
  ]
}

2. MMS 발송

MMS(Multimedia Message Service) 메시지를 발송합니다. 제목, 내용, 첨부파일을 포함한 멀티미디어 메시지를 전송할 때 사용합니다.

📌 주의사항

동보발송이란, 같은 내용의 메시지를 다수에게 동시에 보내는 발송 방식
메시지허브는 동보발송을 지원하며, 1건의 메시지에 최대 10명의 수신자를 추가하여 발송할 수 있습니다.
TPS는 수신자 수 기준으로 처리됩니다. 예시) SMS 1건에 수신자 5명을 추가하여 발송시, TPS는 5입니다.
발신번호는 사전에 등록된 번호만 사용 가능합니다.
예약발송은 현재 시점으로부터 최대 30일까지 가능합니다.
첨부파일은 사전에 업로드된 파일만 사용 가능합니다.
첨부파일은 3개까지 발송 가능합니다.
단축URL 사용 시 메시지 길이가 제한될 수 있습니다.
fbInfoLst는 발송실패시, 대체발송에 대한 객체입니다. 대체발송 채널은 SMS, MMS만 지원하며, 메인 채널과 동일할 수 없습니다.

1) 요청 (Request)

URL

LMS, MMS(파일ID 사용시)

POST /xms/mms/v1 HTTP/1.1

MMS(파일 첨부 사용시)

POST /xms/mms/file/v1 HTTP/1.1

Headers

Name	Type	필수	설명
Authorization	String	●	사용자 인증 토큰
Content-Type	String	●	`application/json` 또는 `multipart/form-data`

Request Body

Name	Type	필수	설명	크기
clickUrlYn	String	-	단축URL 사용여부 (Y/N)	1자
resvYn	String	-	예약발송 여부 (Y/N)	1자
resvReqDt	String	-	예약발송 시간 (ex. 2025-07-13 13:15)	-
agency	Object	-	대행사 정보	-
callback	String	●	발신번호	20자
campaignId	String	-	캠페인 ID	20자
deptCode	String	-	부서 코드	20자
title	String	-	MMS 제목	40 byte
msg	String	●	메시지 내용	2000 byte
fileIdLst	Array	-	파일 아이디 목록	최대 3개
recvInfoLst	Array	●	수신자 정보 리스트	10개
fbInfoLst	Array	-	fallback 정보 리스트	-

2) 응답 (Response)

Response Body

Name	Type	설명
code	String	결과 코드
message	String	결과 메시지
data	Array	결과 데이터 목록
data[].cliKey	String	클라이언트 키
data[].msgKey	String	메시지 키
data[].phone	String	수신번호
data[].code	String	결과 코드
data[].message	String	결과 메시지

3) 요청 예시 (Sample)

Curl

MMS 파일첨부 예시

curl -X POST "https://api-send.msghub-qa.uplus.co.kr/xms/mms/file/v1" \
  -H "accept: */*" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer {token}" \
  -F "reqMsg={
    "clickUrlYn": "N",
    "resvYn": "N",
    "resvReqDt": "2025-07-13 13:15",
    "agency": {
      "kisaOrigCode": "123456789"
    },
    "callback": "0212345678",
    "title": "MMS 테스트 제목",
    "msg": "안녕하세요. 메시지허브입니다.\nMMS 테스트 메시지입니다. #{이름}고객님, #{나이}",
    "recvInfoLst": [
      {
        "cliKey": "test001",
        "phone": "01012341234",
        "mergeData": {
            "이름": "홍길동",
            "나이": "10"
          },
        "userCustomFields": {
            "key1": "value1",
            "key2": 123
          }
      },
      {
        "cliKey": "test002",
        "phone": "01056785678",
        "mergeData": {
            "이름": "홍길동",
            "나이": "10"
          },
        "userCustomFields": {
            "key1": "value1",
            "key2": 123
          }
      }
    ],
    "fbInfoLst": [
      {
        "ch": "SMS",
        "msg": "SMS 메시지 내용"
      }
    ]
  }" -F "parts=@87-300x300.jpg;type=image/jpeg"

MMS 파일ID첨부 예

curl -X POST "https://api-send.msghub-qa.uplus.co.kr/xms/mms/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d "{
    "clickUrlYn": "N",
    "resvYn": "N",
    "resvReqDt": "2025-07-13 13:15",
    "agency": {
      "kisaOrigCode": "123456789"
    },
    "callback": "0212345678",
    "title": "MMS 테스트 제목",
    "msg": "안녕하세요. 메시지허브입니다.\nMMS 테스트 메시지입니다. #{이름}고객님, #{나이}",
    "fileIdLst": ["mms0812"],
    "recvInfoLst": [
      {
        "cliKey": "test001",
        "phone": "01012341234",
        "mergeData": {
            "이름": "홍길동",
            "나이": "10"
          },
        "userCustomFields": {
            "key1": "value1",
            "key2": 123
          }
      },
      {
        "cliKey": "test002",
        "phone": "01056785678",
        "mergeData": {
            "이름": "홍길동",
            "나이": "10"
          },
        "userCustomFields": {
            "key1": "value1",
            "key2": 123
          }
      }
    ],
    "fbInfoLst": [
      {
        "ch": "SMS",
        "msg": "SMS 메시지 내용"
      }
    ]
  }"

LMS

curl -X POST "https://api-send.msghub-qa.uplus.co.kr/xms/mms/v1" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d "{
    "clickUrlYn": "N",
    "resvYn": "N",
    "resvReqDt": "2025-07-13 13:15",
    "agency": {
      "kisaOrigCode": "123456789"
    },
    "callback": "0212345678",
    "title": "MMS 테스트 제목",
    "msg": "안녕하세요. 메시지허브입니다.\nLMS 테스트 메시지입니다. #{이름}고객님, #{나이}",
    "recvInfoLst": [
      {
        "cliKey": "test001",
        "phone": "01012341234",
        "mergeData": {
            "이름": "홍길동",
            "나이": "10"
          },
        "userCustomFields": {
            "key1": "value1",
            "key2": 123
          }
      },
      {
        "cliKey": "test002",
        "phone": "01056785678",
        "mergeData": {
            "이름": "홍길동",
            "나이": "10"
          },
        "userCustomFields": {
            "key1": "value1",
            "key2": 123
          }
      }
    ],
    "fbInfoLst": [
      {
        "ch": "SMS",
        "msg": "SMS 메시지 내용"
      }
    ]
  }"

Response

{
  "code": "10000",
  "message": "성공",
  "data": [
    {
      "cliKey": "test001",
      "msgKey": "3jVnyk0m8U.6fKG1w",
      "phone": "01012341234",
      "code": "10000",
      "message": "성공"
    },
    ...
  ]
}

예약발송 응답

{
  "code": "10000",
  "message": "성공",
  "data": {
    "regDt": "2026-04-08T11:16:55",
    "webReqId": "RRR...b5jv"
   }
  ]
}

Appendix

Agency 객체

대행사 정보를 포함하는 객체입니다.

필드명	타입	필수	설명
kisaOrigCode	String	-	재판매사 KISA 최초식별코드

recvInfoLst 객체

Name	Type	필수	설명	크기
cliKey	String	●	클라이언트키	30자
phone	String	●	수신번호(국제문자 발송 시 맨 앞에 ‘0’이 없어야함)	20자
mergeData	Object	-	채널별 개별화메시지 머지데이터	-
userCustomFields	Object	-	사용자 정의 필드	-

fbInfoLst 객체

Name	Type	필수	설명
ch	String	●	채널
title	String	-	제목(MMS의 경우 필수)
msg	String	●	메시지
fileId	String	-	파일아이디 (파일 아이디와 파일 아이디 목록 중 1개만 사용 가능)
fileIdLst	Array	-	파일 아이디 목록 (최대 3개)

결과코드

결과 코드

2.2 문자 메시지 (SMS/MMS)

목차

베이스 URL

1. SMS 발송

📌 주의사항

1) 요청 (Request)

URL

Headers

Request Body

2) 응답 (Response)

Response Body

3) 요청 예시 (Sample)

Curl

Response

예약발송 응답

2. MMS 발송

📌 주의사항

1) 요청 (Request)

URL

LMS, MMS(파일ID 사용시)

MMS(파일 첨부 사용시)

Headers

Request Body

2) 응답 (Response)

Response Body

3) 요청 예시 (Sample)

Curl

MMS 파일첨부 예시

MMS 파일ID첨부 예

LMS

Response

예약발송 응답

Appendix

Agency 객체

recvInfoLst 객체

fbInfoLst 객체

결과코드