API

그룹 메시지

작성일 2026.03.05 | 수정일 2026.03.05

SOLAPI에서 메시지 그룹은 하나 이상의 메시지 발송 요청을 논리적으로 묶어 관리하는 단위입니다.

개발자가 여러 메시지의 발송을 요청하면, SOLAPI 시스템은 이를 하나의 그룹으로 묶어 처리합니다. 메시지가 그룹에 추가되는 과정과 실제 통신사 또는 메시지 서비스사로 발송되는 과정은 완전히 분리되어 독립적으로 동작합니다.

이러한 구조 덕분에 대량 발송 시에도 안정적인 처리가 가능하며, 각 메시지는 고유한 메시지 ID를 통해 개별적으로 상태를 추적하고 관리할 수 있습니다.

공통 사항

인증

항목	값
인증	API Key(HMAC) / Bearer Token
읽기 권한	`message:read`
쓰기 권한	`message:write`

그룹 상태

status	Description
PENDING	대기 중 (메시지 추가 가능)
SENDING	발송 중
PROCESSING	처리 중
SCHEDULED	예약 대기 중
COMPLETE	발송 완료
FAILED	발송 실패
DELETED	삭제됨
SYSTEM-ERROR	시스템 오류

Response

Name	Type	Required	Description
groupId	string	*	그룹 고유 아이디. G4V로 시작하는 32자 문자열
accountId	string	*	그룹을 생성한 계정의 아이디
apiVersion	string	*	API 버전
serviceMethod	string	*	서비스 방식. MT(일반 발송) 또는 AUTH(본인인증용 발송)
status	string	*	그룹의 현재 상태. PENDING, SENDING, PROCESSING, SCHEDULED, COMPLETE, FAILED, DELETED, SYSTEM-ERROR 중 하나
sdkVersion	string\|null	*	사용 중인 SDK의 버전 정보
osPlatform	string\|null	*	호출 환경의 OS 플랫폼 정보
strict	boolean	*	엄격 모드 여부
prepaid	boolean	*	선불 결제 여부
allowDuplicates	boolean	*	같은 수신번호로 중복 발송 허용 여부
isRefunded	boolean	*	환불 처리 여부
flagUpdated	boolean	*	그룹 정보 갱신 플래그
customFields	object	*	사용자 정의 메타 데이터
hint	object\|null	*	발송 시 참고할 힌트 정보
masterAccountId	string\|null	*	서브 계정으로 발송한 경우, 마스터 계정의 아이디
dateSent	string\|null	*	실제 발송이 시작된 일시 (ISO 8601)
scheduledDate	string\|null	*	예약 발송 일시 (ISO 8601)
dateCompleted	string\|null	*	발송이 완료된 일시 (ISO 8601)
dateCreated	string	*	그룹이 생성된 일시 (ISO 8601)
dateUpdated	string	*	그룹 정보가 마지막으로 갱신된 일시 (ISO 8601)
count	object	*	메시지 건수 통계
total	number	*	그룹에 등록된 전체 메시지 건수
sentTotal	number	*	이통사로 실제 발송 요청된 건수
sentFailed	number	*	발송 후 실패로 확인된 건수
sentSuccess	number	*	발송 후 성공으로 확인된 건수
sentPending	number	*	발송 후 아직 결과를 수신하지 못한 건수
sentReplacement	number	*	대체 발송된 건수
refund	number	*	환불 처리된 건수
registeredFailed	number	*	등록 시 유효성 검증에 실패한 건수
registeredSuccess	number	*	정상 등록된 건수
countForCharge	object	*	메시지 타입별, 국가별 과금 건수. 각 타입 하위에 국가코드를 키로 건수 기록. 예: { "sms": { "82": 50 } }
balance	object	*	잔액(캐시) 차감 내역
requested	number	*	발송 요청 시 차감된 금액
replacement	number	*	대체 발송에 사용된 금액
additional	number	*	추가 과금 금액
refund	number	*	환불된 금액
sum	number	*	총 차감 금액 합계
point	object	*	포인트 차감 내역
requested	number	*	발송 요청 시 차감된 포인트
replacement	number	*	대체 발송에 사용된 포인트
additional	number	*	추가 과금 포인트
refund	number	*	환불된 포인트
sum	number	*	총 차감 포인트 합계
app	object	*	앱 연동 정보
appId	string\|null	*	솔라피 앱스토어에 등록된 앱 아이디
version	string\|null	*	앱 버전
profit	object	*	메시지 타입별 앱 수익. sms, lms, mms, ata, cta, cti, nsa, rcs_sms, rcs_lms, rcs_mms, rcs_tpl, rcs_itpl, rcs_ltpl, fax, voice 각각 number
log	array	*	그룹의 주요 이벤트 이력
createAt	string	*	이벤트 발생 일시 (ISO 8601)
message	string	*	이벤트 내용
price	object	*	국가 코드별, 메시지 타입별 단가 정보. 예: { "82": { "sms": 20 } }

Structures

{
  "groupId": "G4V20240525163506ABCDEFGHIJKLMNO",
  "accountId": "24010100001234",
  "apiVersion": "4",
  "serviceMethod": "MT",
  "status": "PENDING",
  "sdkVersion": "node/5.0.0",
  "osPlatform": "linux",
  "strict": false,
  "prepaid": true,
  "allowDuplicates": false,
  "isRefunded": false,
  "flagUpdated": false,
  "customFields": {
    "myKey": "myValue"
  },
  "hint": {
    "key": "value"
  },
  "masterAccountId": null,
  "workspaceId": null,
  "dateSent": null,
  "scheduledDate": null,
  "dateCompleted": null,
  "dateCreated": "2024-05-25T07:35:06.000Z",
  "dateUpdated": "2024-05-25T07:35:06.000Z",
  "count": {
    "total": 100,
    "sentTotal": 100,
    "sentFailed": 2,
    "sentSuccess": 98,
    "sentPending": 0,
    "sentReplacement": 0,
    "refund": 0,
    "registeredFailed": 0,
    "registeredSuccess": 100
  },
  "countForCharge": {
    "sms": {
      "82": 50
    },
    "lms": {
      "82": 30
    },
    "mms": {
      "82": 20
    },
    "ata": {
      "82": 0
    },
    "cta": {
      "82": 0
    },
    "cti": {
      "82": 0
    },
    "nsa": {
      "82": 0
    },
    "rcs_sms": {
      "82": 0
    },
    "rcs_lms": {
      "82": 0
    },
    "rcs_mms": {
      "82": 0
    },
    "rcs_tpl": {
      "82": 0
    },
    "rcs_itpl": {
      "82": 0
    },
    "rcs_ltpl": {
      "82": 0
    },
    "fax": {
      "82": 0
    },
    "voice": {
      "82": 0
    }
  },
  "balance": {
    "requested": 2000,
    "replacement": 0,
    "additional": 0,
    "refund": 0,
    "sum": 2000
  },
  "point": {
    "requested": 0,
    "replacement": 0,
    "additional": 0,
    "refund": 0,
    "sum": 0
  },
  "app": {
    "appId": "myAppId",
    "version": "1.0.0",
    "profit": {
      "sms": 0,
      "lms": 0,
      "mms": 0,
      "ata": 0,
      "cta": 0,
      "cti": 0,
      "nsa": 0,
      "rcs_sms": 0,
      "rcs_lms": 0,
      "rcs_mms": 0,
      "rcs_tpl": 0,
      "rcs_itpl": 0,
      "rcs_ltpl": 0,
      "fax": 0,
      "voice": 0
    }
  },
  "log": [
    {
      "createAt": "2024-05-25T07:35:06.000Z",
      "message": "메시지 그룹이 생성되었습니다."
    }
  ],
  "price": {
    "82": {
      "sms": 20,
      "lms": 50,
      "mms": 100
    }
  }
}