Agent Board 최신 메시지 조회 API (GET)
개요
Agent Board 최신 메시지 조회 API는 사용자의 가장 최근 에이전트 보드 메시지를 조회하는 기능을 제공합니다. 이 API는 사용자에게 표시할 가장 우선순위가 높은 메시지와 관련된 액션들을 반환하며, 메시지가 없는 경우 기본 안내 메시지를 생성하여 제공합니다.
주요 특징
- 최신 메시지 조회: 사용자의 가장 최근 에이전트 보드 메시지 반환
- 액션 정보 제공: 메시지와 관련된 사용자 액션 리스트 포함
- 기본 메시지 생성: 메시지가 없는 경우 자동으로 기본 안내 메시지 생성
- 우선순위 기반: 메시지 우선순위에 따른 표시 순서 관리
데이터 활용
조회된 메시지 데이터는 다음과 같은 용도로 활용됩니다:
- 사용자 대시보드: 메인 화면에 표시할 주요 메시지 및 알림
- 액션 가이드: 사용자가 수행할 수 있는 다음 단계 안내
- 개인화 콘텐츠: 사용자 상태에 맞춘 맞춤형 메시지 제공
- 워크플로우 관리: 사용자의 현재 진행 상황 추적 및 안내
- 인터랙션 로깅: 메시지 조회 및 사용자 반응 분석
제약사항
- 유효한 액세스 토큰 필요 (JWT 인증)
- 인증된 사용자만 해당 사용자의 메시지 조회 가능
- 반환되는 메시지는 항상 하나 (가장 최신)
- 메시지가 없는 경우에도 기본 메시지 반환으로 빈 응답 없음
최신 메시지 조회
사용자의 가장 최근 에이전트 보드 메시지를 조회합니다.
- HTTP Method:
GET - Path:
/v1/agent-board/latest-message - 인증: 액세스 토큰 (
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
이 API는 별도의 쿼리 파라미터나 경로 파라미터를 요구하지 않습니다. 사용자 ID는 액세스 토큰에서 자동으로 추출됩니다.
Responses
| HTTP Status Code | 설명 | Error Code(s) |
|---|---|---|
| 200 | 최신 메시지 조회 성공 | - |
| 400 | 잘못된 요청 파라미터 | BAD_REQUEST |
| 401 | 인증되지 않은 액세스 | UNAUTHORIZED |
| 500 | 내부 서버 오류 | INTERNAL_ERROR |
200 OK
최신 에이전트 보드 메시지가 성공적으로 조회되었습니다.
Response Schema
{
"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"
},
"ahirUrl": "string"
}
]
}
Response Fields
| 필드 | 타입 | 설명 | 예시값 | 필수 |
|---|---|---|---|---|
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 |
orderIndex | number | 메시지의 정렬 인덱스 (Kotlin: Long, Swift: Int64) | 100 | Yes |
createdAt | number | 메시지 생성 일시 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64) | 1716393600000 | Yes |
actions | array | 사용자가 수행할 수 있는 액션 목록 | [...] | Yes |
Action Object Fields
| 필드 | 타입 | 설명 | 예시값 | 필수 |
|---|---|---|---|---|
id | string | 액션의 고유 식별자 | "action-123" | Yes |
label | string | 사용자에게 표시될 액션 레이블 | "변경된 수면 처방 확인하기" | Yes |
priority | number | 액션 우선순위 (Kotlin: Int, Swift: Int) | 1 | Yes |
target | string | 액션 대상 (화면 또는 기능) - ActionTarget 참조 | "sleepGoal" | Yes |
type | string | 액션 타입 - ActionType 참조 | "NAVIGATE" | Yes |
chatData | object | 액션 관련 채팅 데이터 (선택적) | "{\n \"userId\": \"a667fedb-e561-4ac1-afba-ea8d22b33ba6\",\n \"endDate\": \"2025-08-31\",\n \"startDate\": \"2025-06-02\",\n \"streaming\": true\n}" | No |
ahirUrl | string | AHIR 테스트를 위한 웹뷰 URL | "web-view-url" | No |
ChatData Object Fields
| 필드 | 타입 | 설명 | 예시값 | 필수 |
|---|---|---|---|---|
url | string | 채팅 관련 URL | "https://example.com" | Yes |
body | string | 채팅 메시지 본문 (선택적) | "{\n \"userId\": \"a667fedb-e561-4ac1-afba-ea8d22b33ba6\",\n \"endDate\": \"2025-08-31\",\n \"startDate\": \"2025-06-02\",\n \"streaming\": true\n}" | No |
데이터 타입 정의
BoardType
메시지의 종류를 나타내는 보드 타입입니다.
| 값 | 설명 | 사용 예시 |
|---|---|---|
GUIDANCE | 사용자 안내 및 가이드 메시지 | 앱 소개, 기능 안내, 사용법 설명 |
ACTION_REQUIRED | 사용자의 즉각적인 행동이 필요한 메시지 | 설문 응답 요청, 수면 기록 입력 요청 |
INSIGHT | 데이터 분석 결과 또는 개인화된 인사이트 제공 | 수면 패턴 분석, 개선 제안, 진행 상황 |
NOTIFICATION | 알림 및 공지사항 | 시스템 업데이트, 중요 공지, 이벤트 알림 |
ActionType
사용자가 수행할 수 있는 액션의 종류를 정의합니다.
| 값 | 설명 | 동작 방식 |
|---|---|---|
NAVIGATE | 특정 화면이나 기능으로 이동 | 앱 내 화면 전환, 외부 링크 열기 |
FOCUS | 같은 화면 내에서 특정 카드로 이동 | 같은 화면 내에서 추천 카드로 이동 |
ActionTarget
액션이 연결되는 대상 화면이나 기능을 지정합니다. (BoardTargetType enum 값)
| 값 | 설명 | 연결 화면/기능 |
|---|---|---|
STREAM_MESSAGE | 스트림 메시지 화면 | 실시간 메시지 스트림, 채팅 화면 |
SLEEP_LOG | 수면 기록 화면 | 수면 기록 작성 |
SLEEP_GOAL | 수면 목표 설정 화면 | 수면 목표 관리, 처방 확인 |
DAILY_CONTENT | 오늘의 치료프로그램 | 같은 화면 내 추천 카드 확인 |
CHAT | 채팅 화면 | 상담사 채팅, AI 어시스턴트 대화 |
AHIR_VIEW | WEB VIEW (2.0 전용) | Agent와 대화 |
MessageStatus
메시지의 현재 상태를 나타내는 상태 값입니다.
| 값 | 설명 | 사용 시점 |
|---|---|---|
PENDING | 전달 대기 | 메시지가 생성되었지만 아직 사용자에게 전달되지 않은 상태 |
DELIVERED | 전달됨 | 메시지가 사용자에게 성공적으로 전달된 상태 |
VIEWED | 조회됨 | 사용자가 메시지를 확인한 상태 |
INTERACTED | 상호작용 발생 | 사용자가 메시지의 액션 버튼을 클릭하거나 상호작용한 상태 |
EXPIRED | 만료됨 | 메시지의 유효 기간이 지나 더 이상 표시되지 않는 상태 |
ARCHIVED | 아카이빙됨 | 시스템에 의해 보관 처리된 상태 |
EXTERNALLY_COMPLETED | 외부 완료 | 다른 곳에서 관련 인터랙션 발생으로 완료 처리 |
Success Response Example
{
"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": `{\n \"userId\": \"a667fedb-e561-4ac1-afba-ea8d22b33ba6\",\n \"endDate\": \"2025-08-31\",\n \"startDate\": \"2025-06-02\",\n \"streaming\": true\n}"
}
}
]
}
{
"id": "msg-456789",
"title": "슬립큐에 오신 것을 환영합니다.",
"priority": 1000,
"boardType": "GUIDANCE",
"status": "DELIVERED",
"createdAt": 1716393600000,
"orderIndex": 1000,
"actions": [
{
"id": "action-001",
"label": "변경된 수면 처방 확인하기",
"priority": 1,
"target": "AHIR_VIEW",
"type": "NAVIGATE",
"ahirUrl": "web-view-url"
}
]
}
400 Bad Request
요청 파라미터가 잘못되었습니다.
{
"statusCode": 400,
"message": "Invalid request parameters",
"error": "Bad Request"
}
401 Unauthorized
인증되지 않은 요청입니다.
{
"statusCode": 401,
"message": "Unauthorized access",
"error": "Unauthorized"
}
500 Internal Server Error
서버 내부 오류가 발생했습니다.
{
"statusCode": 500,
"message": "Internal server error",
"error": "Internal Server Error"
}
관련 API
- MCP 세션 초기화 API (POST): MCP 세션을 초기화하여 실시간 메시지 수신 준비
- MCP SSE 스트림 연결 API (GET): 실시간 메시지 스트림 연결
- MCP 세션 종료 API (DELETE): MCP 세션 정리 및 종료