2.5 Push 메시지

목차

• 1. Push 발송
• Appendix

1. Push 발송

모바일 앱 푸시 메시지를 발송합니다. iOS와 Android 플랫폼 모두 지원하며, 앱 사용자에게 실시간 알림을 전달할 수 있습니다.

📌 주의사항

1. 한 번에 최대 10명의 수신자에게 발송할 수 있습니다.
2. 예약발송은 현재 시점으로부터 최대 30일까지 가능합니다.
3. 단축URL 사용 시 메시지 길이가 제한될 수 있습니다.
4. fallback 발송 시 발신번호(callback) 필수 입력이 필요합니다.
5. 전체 발송(serviceCode=A)의 경우 recvInfoLst는 생략 가능합니다.
6. ext 필드는 앱에서 처리할 커스텀 데이터를 포함할 수 있습니다.

---

1) 요청 (Request)

URL

POST /msg/v1/push 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	-	예약발송 시간	-
agency	Object	-	대행사 정보	-
callback	String	-	발신번호(fallback용)	20자
campaignId	String	-	캠페인 ID	20자
deptCode	String	-	부서 코드	20자
msg	Object	●	메시지 내용	-
appId	String	●	앱 아이디	255자
ext	Object	-	확장 커스텀 메시지	1000B
fileId	String	-	파일 아이디	20자
serviceCode	String	-	PUSH 발송타입	-
recvInfoLst	Array	●	수신자 정보 목록	10개
fbInfoLst	Array	-	fallback 정보 목록	-

msg 객체

Name	Type	필수	설명
title	String	●	푸시 메시지 제목
body	String	●	푸시 메시지 내용

ext 객체

Name	Type	필수	설명
key	String	-	커스텀 데이터 키
value	String	-	커스텀 데이터 값

---

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.msghub.uplus.co.kr/msg/v1/push" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "callback": "020000003"
    "resvReqDt": "2025-07-13 13:15",
    "agency": {
      "kisaOrigCode": "123456789"
    },
    "msg": {
      "title": "U+ Cloud 서비스 알림",
      "body": "안녕하세요. #{name} 고객님.\n\nU+ Cloud서비스에서 설정하신 일일 사용량(#{usage}건) 초과 사용을 알려드립니다."
    },
    "appId": "LGU-SAMPLEAPP-00001",
    "ext": {
      "type": "usage_alert",
      "usage": "1000",
      "limit": "1000",
      "service": "cloud"
    },
    "recvInfoLst": [
      {
        "cliKey": "test001",
        "cuid": "user123",
        "phone": "01012341234",
        "mergeData": {
          "name": "홍길동",
          "usage": "1,000건"
        }
      },
      {
        "cliKey": "test002",
        "cuid": "user456",
        "phone": "01056785678",
        "mergeData": {
          "name": "김철수",
          "usage": "1,200건"
        }
      }
    ],
    "fbInfoLst": [
      {
        "ch": "SMS",
        "msg": "U+ Cloud 서비스 알림\n\n안녕하세요. 홍길동 고객님.\nU+ Cloud서비스에서 설정하신 일일 사용량(1,000건) 초과 사용을 알려드립니다."
      }
    ]
  }'

Response

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

Appendix

Agency 객체

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

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

recvInfoLst 객체

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

fbInfoLst 객체

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

결과 코드

• 결과 코드