API

그룹 메시지 목록 조회

작성일 2026.03.05 | 수정일 2026.03.05

GET/messages/v4/groups/:groupId/messages

Parameters

groupId*— 메시지 목록을 조회할 그룹의 아이디

Query

limit— 한 번에 조회할 메시지 수입니다.

startKey— 이전 응답의 nextKey 값을 넣으면 해당 위치부터 이어서 조회합니다.

그룹에 추가된 메시지 목록을 조회합니다. 발송 전에 어떤 메시지가 등록되어 있는지 확인하거나, 발송 후 개별 메시지의 상태를 확인할 때 사용합니다.

Response

messageList는 그룹 목록과 마찬가지로 messageId를 key로 하는 객체 형태입니다.

Name	Type	Required	Description
startKey	string\|null	*	현재 페이지의 시작 키
nextKey	string		다음 페이지를 불러오기 위한 키. 다음 페이지가 없으면 미포함
limit	number	*	요청 시 지정한 조회 개수
messageList	object	*	메시지 목록. messageId를 키로 사용하는 객체
<messageId>	object	*	메시지 객체
messageId	string	*	메시지 고유 아이디. M4V로 시작하는 32자 문자열
groupId	string	*	메시지가 속한 그룹 아이디
accountId	string	*	계정 아이디
to	string	*	수신번호
from	string\|null	*	발신번호
text	string	*	메시지 본문 내용
type	string\|null	*	메시지 타입
country	string	*	수신 국가 코드
subject	string\|null	*	메시지 제목 (LMS, MMS 등)
imageId	string\|null	*	이미지 아이디
customFields	object	*	사용자 정의 메타 데이터
status	string	*	메시지 상태. PENDING(대기), SENDING(전송중), COMPLETE(완료)
statusCode	string\|null	*	상태 코드. 2000은 정상 접수, 4000은 정상 발송 완료
reason	string\|null	*	상태 코드에 대한 설명
networkCode	string\|null	*	통신사 코드
networkName	string	*	통신사 이름 (예: SK Telecom, KT, LG U+)
replacement	boolean	*	대체 발송 여부 (예: 카카오 실패 → SMS 대체)
replacements	array	*	대체 발송 정보 목록
to	string	*	대체 발송 수신번호
from	string	*	대체 발송 발신번호
text	string	*	대체 발송 메시지 내용
autoTypeDetect	boolean	*	자동 타입 감지 사용 여부
unavailableSenderNumber	boolean	*	발신번호 사용 불가 여부
faxPageCount	number	*	팩스 페이지 수. 팩스가 아닌 경우 0
resendCount	number	*	재발송 횟수
voiceReplied	number	*	음성 메시지 응답 횟수
voiceDuration	number	*	음성 메시지 재생 시간 (초)
queues	array	*	발송 큐 이력. 메시지가 거친 발송 채널 및 결과
name	string	*	큐 이름 (예: kakaoAlimtalk, sms)
statusCode	string	*	해당 큐에서의 상태 코드
uniqId	string		해당 채널에서의 고유 아이디
currentQueue	string\|null	*	현재 처리 중인 큐 이름
dateProcessed	string\|null	*	발송 처리 일시 (ISO 8601)
dateReported	string\|null	*	결과 보고 수신 일시 (ISO 8601)
dateReceived	string\|null	*	단말기 수신 확인 일시 (ISO 8601)
dateCreated	string\|null	*	메시지 생성 일시 (ISO 8601)
dateUpdated	string\|null	*	메시지 정보 갱신 일시 (ISO 8601)
log	array	*	메시지 이벤트 로그
createAt	string	*	이벤트 발생 일시 (ISO 8601)
message	string	*	이벤트 내용
kakaoOptions	object\|null		카카오 알림톡/친구톡 옵션. 메시지 추가 요청 Body의 kakaoOptions 구조 참조
naverOptions	object\|null		네이버 톡톡 옵션. 메시지 추가 요청 Body의 naverOptions 구조 참조
rcsOptions	object\|null		RCS 옵션. 메시지 추가 요청 Body의 rcsOptions 구조 참조
faxOptions	object\|null		팩스 옵션. 메시지 추가 요청 Body의 faxOptions 구조 참조
voiceOptions	object\|null		음성 메시지 옵션. 메시지 추가 요청 Body의 voiceOptions 구조 참조

Structure

{
  "startKey": null,
  "nextKey": "M4V20260302143500XXXXXXXXXXXXXXX",
  "limit": 20,
  "messageList": {
    "M4V20260302143506CQKNPHTPCX4P5E": {
      "messageId": "M4V20260302143506CQKNPHTPCX4P5E",
      "groupId": "G4V20260302143025ABCDEFGHIJKLMNO",
      "accountId": "23010100000001",
      "to": "01012345678",
      "from": "0212345678",
      "text": "테스트 메시지입니다.",
      "type": "SMS",
      "country": "82",
      "subject": null,
      "imageId": null,
      "customFields": {},
      "status": "COMPLETE",
      "statusCode": "4000",
      "reason": "정상 처리",
      "networkCode": "10001",
      "networkName": "SKT",
      "replacement": false,
      "replacements": [],
      "autoTypeDetect": true,
      "unavailableSenderNumber": false,
      "faxPageCount": 0,
      "resendCount": 0,
      "voiceReplied": 0,
      "voiceDuration": 0,
      "queues": [
        {
          "name": "sms",
          "statusCode": "4000"
        }
      ],
      "currentQueue": null,
      "dateProcessed": "2026-03-02T05:35:08.000Z",
      "dateReported": "2026-03-02T05:35:09.000Z",
      "dateReceived": "2026-03-02T05:35:10.000Z",
      "dateCreated": "2026-03-02T05:35:06.000Z",
      "dateUpdated": "2026-03-02T05:35:10.000Z",
      "log": [
        {
          "createAt": "2026-03-02T05:35:06.000Z",
          "message": "메시지가 생성되었습니다."
        }
      ]
    }
  }
}