SDKAPI
시작하기
Menu Close
API

그룹 메시지 목록 조회

작성일 2026.03.05 | 수정일 2026.08.17
GET/messages/v4/groups/:groupId/messages
Parameters
groupId*— 메시지 목록을 조회할 그룹의 아이디
Query
limit— 한 번에 조회할 메시지 수입니다.
startKey— 이전 응답의 nextKey 값을 넣으면 해당 위치부터 이어서 조회합니다.

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

GET/messages/v4/groups/fast/:groupId/messages
Parameters
groupId*— 메시지 목록을 조회할 그룹의 아이디
Query
limit— 한 번에 조회할 메시지 수입니다.
startKey— 이전 응답의 nextKey 값을 넣으면 해당 위치부터 이어서 조회합니다.

고속 접수 그룹의 메시지 목록을 조회합니다. 페이지네이션 방식과 응답 형식은 기존 그룹 메시지 목록 조회 API와 동일합니다.

Response

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

NameTypemustDescription
startKeystring|null*현재 페이지의 시작 키
nextKeystring다음 페이지를 불러오기 위한 키. 다음 페이지가 없으면 미포함
limitnumber*요청 시 지정한 조회 개수
messageListobject*메시지 목록. messageId를 키로 사용하는 객체
<messageId>object*메시지 객체
messageIdstring*메시지 고유 아이디. M4V로 시작하는 32자 문자열
groupIdstring*메시지가 속한 그룹 아이디
accountIdstring*계정 아이디
tostring*수신번호
fromstring|null*발신번호
textstring*메시지 본문 내용
typestring|null*메시지 타입
countrystring*수신 국가 코드
subjectstring|null*메시지 제목 (LMS, MMS 등)
imageIdstring|null*이미지 아이디
customFieldsobject*사용자 정의 메타 데이터
statusstring*메시지 상태. PENDING(대기), SENDING(전송중), COMPLETE(완료)
statusCodestring|null*상태 코드. 2000은 정상 접수, 4000은 정상 발송 완료
reasonstring|null*상태 코드에 대한 설명
networkCodestring|null*통신사 코드
networkNamestring*통신사 이름 (예: SK Telecom, KT, LG U+)
replacementboolean*대체 발송 여부 (예: 카카오 실패 → SMS 대체)
replacementsarray*대체 발송 정보 목록
tostring*대체 발송 수신번호
fromstring*대체 발송 발신번호
textstring*대체 발송 메시지 내용
autoTypeDetectboolean*자동 타입 감지 사용 여부
unavailableSenderNumberboolean*발신번호 사용 불가 여부
faxPageCountnumber*팩스 페이지 수. 팩스가 아닌 경우 0
resendCountnumber*재발송 횟수
voiceRepliednumber*음성 메시지 응답 횟수
voiceDurationnumber*음성 메시지 재생 시간 (초)
queuesarray*발송 큐 이력. 메시지가 거친 발송 채널 및 결과
namestring*큐 이름 (예: kakaoAlimtalk, sms)
statusCodestring*해당 큐에서의 상태 코드
uniqIdstring해당 채널에서의 고유 아이디
currentQueuestring|null*현재 처리 중인 큐 이름
dateProcessedstring|null*발송 처리 일시 (ISO 8601)
dateReportedstring|null*결과 보고 수신 일시 (ISO 8601)
dateReceivedstring|null*단말기 수신 확인 일시 (ISO 8601)
dateCreatedstring|null*메시지 생성 일시 (ISO 8601)
dateUpdatedstring|null*메시지 정보 갱신 일시 (ISO 8601)
logarray*메시지 이벤트 로그
createAtstring*이벤트 발생 일시 (ISO 8601)
messagestring*이벤트 내용
kakaoOptionsobject|null카카오 알림톡/친구톡 옵션. 메시지 추가 요청 Body의 kakaoOptions 구조 참조
naverOptionsobject|null네이버 톡톡 옵션. 메시지 추가 요청 Body의 naverOptions 구조 참조
rcsOptionsobject|nullRCS 옵션. 메시지 추가 요청 Body의 rcsOptions 구조 참조
faxOptionsobject|null팩스 옵션. 메시지 추가 요청 Body의 faxOptions 구조 참조
voiceOptionsobject|null음성 메시지 옵션. 메시지 추가 요청 Body의 voiceOptions 구조 참조

Structure

Response
{ "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": "메시지가 생성되었습니다." } ] } } }