본문으로 건너뛰기
버전: 0.68.0

특정 Agent Board 메시지 이후의 리스트 조회 API (GET)

개요​

특정 Agent Board 메시지 이후의 리스트 조회 API는 messageId 쿼리 파라미터의 생성시각을 기준으로, 해당 메시지 이후의 에이전트 보드 메시지를 조회하는 기능을 제공합니다. 이 API는 메시지 이력을 시간순으로 정렬하여 반환합니다. messageId 가 없다면 사용자의 모든 메시지가 조회됩니다.

주요 특징​

  • 전체 이력 조회: 만료된 메시지를 포함한 모든 메시지 이력 제공
  • 시간순 정렬: 생성일 기준 내림차순(최신순) 정렬

데이터 활용​

조회된 메시지 리스트 데이터는 다음과 같은 용도로 활용됩니다:

  • 메시지 이력 관리: 사용자의 메시지 기록 조회 및 관리
  • 메시지 추적: 과거 메시지 재확인 및 추적
  • 사용 패턴 분석: 메시지 조회 패턴 분석 및 개선

제약사항​

  • 유효한 액세스 토큰 필요 (JWT 인증)
  • 인증된 사용자만 해당 사용자의 메시지 조회 가능

메시지 리스트 조회​

사용자의 에이전트 보드 메시지를 조회합니다.

  • HTTP Method: GET
  • Path: /v1/agent-board/messages/since
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰입니다.Yes
Acceptapplication/jsonJSON 형식의 응답을 요청합니다.Yes
Accept-Languagede-DE, en-US, ko-KR오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.No

Parameters​

Query Parameters​

ParameterTypeDescriptionDefaultRequiredConstraints
messageIdstring마지막으로 확인한 message id-No

Responses​

HTTP Status Code설명Error Code(s)
200메시지 리스트 조회 성공-
400잘못된 요청 파라미터MESSAGE_NOT_FOUND
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
}

Response Fields

필드타입설명예시값필수
messagesarray메시지 객체 배열[...]Yes
unreadMessageCountnumber읽지 않은 메시지 수 (PENDING, DELIVERED 상태 메시지 개수, Kotlin: Int, Swift: Int)10Yes

Message Object Fields

메시지 객체의 구조는 최신 메시지 조회 API와 동일합니다.

필드타입설명예시값필수
idstring메시지의 고유 식별자"msg-123"Yes
titlestring메시지 제목"슬립큐에 오신 것을 환영합니다."Yes
prioritynumber메시지 우선순위 (높을수록 우선, Kotlin: Int, Swift: Int)1000Yes
boardTypestring보드 메시지 타입 - BoardType 참조"GUIDANCE"Yes
statusstring메시지 상태 - MessageStatus 참조"DELIVERED"Yes
createdAtnumber메시지 생성 일시 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)1716393600000Yes
orderIndexnumber메시지의 정렬 인덱스 (Kotlin: Long, Swift: Int64)100Yes
actionsarray사용자가 수행할 수 있는 액션 목록[...]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": 500,
      "actions": [
        {
          "id": "action-003",
          "label": "수면 기록 입력",
          "priority": 1,
          "target": "SLEEP_LOG",
          "type": "NAVIGATE"
        }
      ]
    }
  ],
  "unreadMessageCount": 12
}

400 Bad Request (잘못된 message id 값)​

id 에 해당하는 message 를 찾을 수 없습니다.

{
  "statusCode": 400,
  "message": "MESSAGE_NOT_FOUND",
  "error": "메시지를 찾을 수 없습니다."
}

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전달 대기메시지가 생성되었지만 아직 사용자에게 전달되지 않은 상태NN
DELIVERED전달됨메시지가 사용자에게 성공적으로 전달된 상태NY
VIEWED조회됨사용자가 메시지를 화면에서 확인한 상태YY
INTERACTED상호작용 발생사용자가 메시지의 액션 버튼을 클릭하거나 상호작용한 상태YY
EXTERNALLY_COMPLETED외부 완료다른 곳에서 관련 인터랙션 발생으로 완료 처리된 상태YY
EXPIRED만료됨메시지의 유효 기간이 지나 더 이상 표시되지 않는 상태YN
ARCHIVED아카이빙됨시스템에 의해 보관 처리되었거나, 사용자가 보관 처리한 상태YN

사용 예시​

기본 조회 (모든 메시지)​

GET /v1/agent-board/messages/since
Authorization: Bearer {accessToken}
Accept: application/json

특정 메시지 이후의 리스트 조회​

GET /v1/agent-board/messages/since?messageId=d89cc8eb-de34-469a-865d-683048916068
Authorization: Bearer {accessToken}
Accept: application/json

관련 API​