Agent Board 메시지 리스트 조회 API (GET)
개요
Agent Board 메시지 리스트 조회 API는 사용자의 모든 에이전트 보드 메시지를 페이지네이션과 함께 조회하는 기능을 제공합니다. 이 API는 사용자의 모든 메시지 이력을 시간순으로 정렬하여 반환하며, 페이지네이션을 통해 효율적인 데이터 조회를 지원합니다.
주요 특징
- 페이지네이션 지원: page/limit 기반 페이지네이션으로 효율적인 데이터 조회
- 전체 이력 조회: 만료된 메시지를 포함한 모든 메시지 이력 제공
- 시간순 정렬: 생성일 기준 내림차순(최신순) 정렬
- 상세 페이지네이션 정보: 총 항목 수, 페이지 수, 다음/이전 페이지 존재 여부 제공
데이터 활용
조회된 메시지 리스트 데이터는 다음과 같은 용도로 활용됩니다:
- 메시지 이력 관리: 사용자의 모든 메시지 기록 조회 및 관리
- 페이지네이션 UI: 무한 스크롤 또는 페이지 네비게이션 구현
- 메시지 추적: 과거 메시지 재확인 및 추적
- 사용 패턴 분석: 메시지 조회 패턴 분석 및 개선
제약사항
- 유효한 액세스 토큰 필요 (JWT 인증)
- 인증된 사용자만 해당 사용자의 메시지 조회 가능
- 페이지 번호는 1 이상이어야 함
- 페이지당 항목 수는 1 이상 100 이하로 제한
메시지 리스트 조회
사용자의 모든 에이전트 보드 메시지를 페이지네이션과 함께 조회합니다.
- HTTP Method:
GET - Path:
/v1/agent-board/messages - 인증: 액세스 토큰 (
accessToken) 필요
Headers
| Header | Type | Description | Required |
|---|---|---|---|
Authorization | Bearer {accessToken} | 사용자 인증을 통해 발급받은 액세스 토큰입니다. | Yes |
Accept | application/json | JSON 형식의 응답을 요청합니다. | Yes |
Accept-Language | de-DE, en-US, ko-KR | 오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다. | No |
Parameters
Query Parameters
| Parameter | Type | Description | Default | Required | Constraints |
|---|---|---|---|---|---|
page | number | 조회할 페이지 번호 (1부터 시작, Kotlin: Int, Swift: Int) | 1 | No | 1 이상 |
limit | number | 페이지당 조회할 메시지 수 (Kotlin: Int, Swift: Int) | 10 | No | 1 이상 100 이하 |
Responses
| HTTP Status Code | 설명 | Error Code(s) |
|---|---|---|
| 200 | 메시지 리스트 조회 성공 | - |
| 400 | 잘못된 요청 파라미터 | INVALID_PAGE_NUMBER |
| 400 | 잘못된 limit 값 | INVALID_LIMIT_VALUE |
| 401 | 인증되지 않은 액세스 | UNAUTHORIZED |
| 500 | 내부 서버 오류 | INTERNAL_ERROR |
200 OK
에이전트 보드 메시지 리스트가 성공적으로 조회되었습니다.
Response Schema
{
"messages": [
{
"id": "string",
"title": "string",
"priority": "number",
"boardType": "string",
"status": "string",
"createdAt": "number",
"orderIndex": "number",
"actions": [
{
"id": "string",
"label": "string",
"priority": "number",
"target": "string",
"type": "string",
"chatData": {
"url": "string",
"body": "string"
}
}
]
}
],
"unreadMessageCount": 10,
"pagination": {
"page": "number",
"limit": "number",
"total": "number",
"totalPages": "number",
"hasNext": "boolean",
"hasPrev": "boolean"
}
}
Response Fields
| 필드 | 타입 | 설명 | 예시값 | 필수 |
|---|---|---|---|---|
messages | array | 메시지 객체 배열 | [...] | Yes |
unreadMessageCount | number | 읽지 않은 메시지 수 (PENDING, DELIVERED 상태 메시지 개수, Kotlin: Int, Swift: Int) | 10 | Yes |
pagination | object | 페이지네이션 정보 객체 | {...} | Yes |
Message Object Fields
메시지 객체의 구조는 최신 메시지 조회 API와 동일합니다.
| 필드 | 타입 | 설명 | 예시값 | 필수 |
|---|---|---|---|---|
id | string | 메시지의 고유 식별자 | "msg-123" | Yes |
title | string | 메시지 제목 | "슬립큐에 오신 것을 환영합니다." | Yes |
priority | number | 메시지 우선순위 (높을수록 우선, Kotlin: Int, Swift: Int) | 1000 | Yes |
boardType | string | 보드 메시지 타입 - BoardType 참조 | "GUIDANCE" | Yes |
status | string | 메시지 상태 - MessageStatus 참조 | "DELIVERED" | Yes |
createdAt | number | 메시지 생성 일시 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64) | 1716393600000 | Yes |
orderIndex | number | 메시지의 정렬 인덱스 (Kotlin: Long, Swift: Int64) | 100 | Yes |
actions | array | 사용자가 수행할 수 있는 액션 목록 | [...] | Yes |
Pagination Object Fields
| 필드 | 타입 | 설명 | 예시값 | 필수 |
|---|---|---|---|---|
page | number | 현재 페이지 번호 | 1 | Yes |
limit | number | 페이지당 항목 수 | 10 | Yes |
total | number | 전체 메시지 수 | 45 | Yes |
totalPages | number | 전체 페이지 수 | 5 | Yes |
hasNext | boolean | 다음 페이지 존재 여부 | true | Yes |
hasPrev | boolean | 이전 페이지 존재 여부 | false | Yes |
Success Response Example
{
"messages": [
{
"id": "msg-456789",
"title": "슬립큐에 오신 것을 환영합니다.",
"priority": 1000,
"boardType": "GUIDANCE",
"status": "DELIVERED",
"createdAt": 1716393600000,
"orderIndex": 1000,
"actions": [
{
"id": "action-001",
"label": "변경된 수면 처방 확인하기",
"priority": 1,
"target": "sleepGoal",
"type": "NAVIGATE"
},
{
"id": "action-002",
"label": "슬립큐 소개",
"priority": 2,
"target": "STREAM_MESSAGE",
"type": "NAVIGATE",
"chatData": {
"url": "https://example.com",
"body": "{\"userId\": \"a667fedb-e561-4ac1-afba-ea8d22b33ba6\", \"streaming\": true}"
}
}
]
},
{
"id": "msg-123456",
"title": "수면 기록을 입력해 주세요",
"priority": 500,
"boardType": "ACTION_REQUIRED",
"status": "VIEWED",
"createdAt": 1716392415320,
"orderIndex": 999,
"actions": [
{
"id": "action-003",
"label": "수면 기록 입력",
"priority": 1,
"target": "SLEEP_LOG",
"type": "NAVIGATE"
}
]
}
],
"unreadMessageCount": 12,
"pagination": {
"page": 1,
"limit": 10,
"total": 45,
"totalPages": 5,
"hasNext": true,
"hasPrev": false
}
}
400 Bad Request (잘못된 페이지 번호)
페이지 번호가 1보다 작은 경우 발생합니다.
{
"statusCode": 400,
"message": "INVALID_PAGE_NUMBER",
"error": "페이지 번호는 1 이상이어야 합니다."
}
400 Bad Request (잘못된 limit 값)
limit 값이 1보다 작거나 100보다 큰 경우 발생합니다.
{
"statusCode": 400,
"message": "INVALID_LIMIT_VALUE",
"error": "페이지당 항목 수는 1 이상 100 이하여야 합니다."
}
401 Unauthorized
인증되지 않은 요청입니다.
{
"statusCode": 401,
"message": "Unauthorized access",
"error": "Unauthorized"
}
500 Internal Server Error
서버 내부 오류가 발생했습니다.
{
"statusCode": 500,
"message": "Internal server error",
"error": "Internal Server Error"
}
데이터 타입 정의
메시지 객체의 데이터 타입은 최신 메시지 조회 API와 동일합니다.
BoardType
메시지의 종류를 나타내는 보드 타입입니다.
| 값 | 설명 | 사용 예시 |
|---|---|---|
GUIDANCE | 사용자 안내 및 가이드 메시지 | 앱 소개, 기능 안내, 사용법 설명 |
ACTION_REQUIRED | 사용자의 즉각적인 행동이 필요한 메시지 | 설문 응답 요청, 수면 기록 입력 요청 |
INSIGHT | 데이터 분석 결과 또는 개인화된 인사이트 제공 | 수면 패턴 분석, 개선 제안, 진행 상황 |
NOTIFICATION | 알림 및 공지사항 | 시스템 업데이트, 중요 공지, 이벤트 알림 |
ActionType
사용자가 수행할 수 있는 액션의 종류를 정의합니다.
| 값 | 설명 | 동작 방식 |
|---|---|---|
NAVIGATE | 특정 화면이나 기능으로 이동 | 앱 내 화면 전환, 외부 링크 열기 |
FOCUS | 같은 화면 내에서 특정 카드로 이동 | 같은 화면 내에서 추천 카드로 이동 |
ActionTarget
액션이 연결되는 대상 화면이나 기능을 지정합니다.
| 값 | 설명 | 연결 화면/기능 |
|---|---|---|
STREAM_MESSAGE | 스트림 메시지 화면 | 실시간 메시지 스트림, 채팅 화면 |
SLEEP_LOG | 수면 기록 화면 | 수면 기록 작성 |
SLEEP_GOAL | 수면 목표 설정 화면 | 수면 목표 관리, 처방 확인 |
DAILY_CONTENT | 오늘의 치료프로그램 | 같은 화면 내 추천 카드 확인 |
CHAT | 채팅 화면 | 상담사 채팅, AI 어시스턴트 대화 |
MessageStatus
메시지의 현재 상태를 나타내는 상태 값입니다.
| 값 | 설명 | 사용 시점 | 읽음 여부 | 조회 API 응답 포함 여부 |
|---|---|---|---|---|
QUEUED | 전달 대기 | 메시지가 생성되었지만 아직 사용자에게 전달되지 않은 상태 | N | N |
DELIVERED | 전달됨 | 메시지가 사용자에게 성공적으로 전달된 상태 | N | Y |
VIEWED | 조회됨 | 사용자가 메시지를 화면에서 확인한 상태 | Y | Y |
INTERACTED | 상호작용 발생 | 사용자가 메시지의 액션 버튼을 클릭하거나 상호작용한 상태 | Y | Y |
EXTERNALLY_COMPLETED | 외부 완료 | 다른 곳에서 관련 인터랙션 발생으로 완료 처리된 상태 | Y | Y |
EXPIRED | 만료됨 | 메시지의 유효 기간이 지나 더 이상 표시되지 않는 상태 | Y | N |
ARCHIVED | 아카이빙됨 | 시스템에 의해 보관 처리되었거나, 사용자가 보관 처리한 상태 | Y | N |
사용 예시
기본 조회 (첫 페이지)
GET /v1/agent-board/messages
Authorization: Bearer {accessToken}
Accept: application/json
특정 페이지 조회
GET /v1/agent-board/messages?page=2&limit=20
Authorization: Bearer {accessToken}
Accept: application/json
관련 API
- Agent Board 최신 메시지 조회 API (GET): 사용자의 가장 최근 메시지만 조회
- MCP 세션 초기화 API (POST): MCP 세션을 초기화하여 실시간 메시지 수신 준비
- MCP SSE 스트림 연결 API (GET): 실시간 메시지 스트림 연결