API

그룹 목록 조회

작성일 2026.03.05 | 수정일 2026.03.05

GET/messages/v4/groups

Query

limit— 한 번에 조회할 그룹 수입니다. 최대 500까지 지정할 수 있습니다.

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

startDate— 조회 시작 일시. 이 시간 이후의 그룹만 포함됩니다.

endDate— 조회 종료 일시. 이 시간 이전의 그룹만 포함됩니다.

dateType— 날짜 필터의 기준 필드. CREATED(생성일 기준) 또는 UPDATED(수정일 기준).

message:read 권한이 필요합니다

내 계정에서 생성한 그룹 목록을 조회합니다. 날짜 범위, 상태 등 다양한 조건으로 필터링할 수 있으며, 커서 기반 페이지네이션을 지원합니다.

고급 검색 (criteria / cond / value)

세 파라미터를 세트로 사용하여 복합 조건 검색이 가능합니다. 각 값은 콤마(,)로 구분하며, 세 파라미터의 항목 수가 반드시 동일해야 합니다.

?criteria=status,count.total&cond=eq,gte&value=COMPLETE,100

Name	Type	Description
criteria	String	검색 대상 필드명 (콤마 구분)
cond	String	비교 연산자 (콤마 구분)
value	String	검색 값 (콤마 구분)

criteria 허용 필드 및 지원 연산자

Name	Description	Operator
messageId	메시지 아이디	eq, ne
groupId	그룹 아이디	eq, ne
to	수신번호	eq, ne
from	발신번호	eq, ne
type	메시지 타입	eq, ne
statusCode	상태 코드	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`
status	메시지 상태	`eq`, `ne`
dateCreated	생성 일시	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`
dateUpdated	수정 일시	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`
replacement	대체 발송 여부	`eq`, `ne`
kakaoTemplateId	카카오 템플릿 ID	`eq`, `ne`

cond 연산자

Name	Description
eq	같음 (=)
ne	같지 않음 (!=)
gt	초과 (>)
gte	이상 (>=)
lt	미만 (<)
lte	이하 (<=)

요청 예시

GET /messages/v4/groups?limit=10

GET /messages/v4/groups?criteria=status&cond=eq&value=COMPLETE

GET /messages/v4/groups?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z

GET /messages/v4/groups?startKey=G4V20240525163506XXXXXXXXXXXXXXX&limit=20

Response

groupList는 배열이 아닌 groupId를 key로 하는 객체 형태입니다. 각 그룹에 groupList["G4V..."] 형태로 접근할 수 있습니다.
nextKey가 미포함이면 마지막 페이지입니다. 값이 있다면 다음 페이지가 존재하므로 startKey에 해당 값을 넣어 추가 조회할 수 있습니다.

Name	Type	Required	Description
startKey	string\|null	*	현재 페이지의 시작 키
nextKey	string		다음 페이지를 불러오기 위한 키. 다음 페이지가 없으면 미포함
limit	number	*	요청 시 지정한 조회 개수
groupList	object	*	그룹 목록. groupId를 키로 사용하는 객체. 각 값은 그룹 객체이며, 전체 필드는 그룹 객체 응답 스키마 참조

Structure

Response

{
  "startKey": null,
  "nextKey": "G4V20260302143000XXXXXXXXXXXXXXX",
  "limit": 20,
  "groupList": {
    "G4V20260302143025ABCDEFGHIJKLMNO": {
      "groupId": "G4V20260302143025ABCDEFGHIJKLMNO",
      "accountId": "23010100000001",
      "status": "COMPLETE",
      "count": {
        "total": 100,
        "sentTotal": 100,
        "sentFailed": 2,
        "sentSuccess": 98,
        "sentPending": 0,
        "sentReplacement": 3,
        "refund": 2,
        "registeredFailed": 0,
        "registeredSuccess": 100
      },
      "dateCreated": "2026-03-02T05:30:25.000Z",
      "dateUpdated": "2026-03-02T05:31:00.000Z"
    }
  }
}

chat

그룹 객체의 전체 필드는 공통 그룹 객체 구조를 참조하세요.