버전: 0.68.0

Agent Board 메시지 상태 업데이트 API (PATCH)

개요

Agent Board 메시지 상태 업데이트 API는 여러 개의 에이전트 보드 메시지의 상태를 한번에 일괄 업데이트하는 기능을 제공합니다. 이 API는 사용자가 메시지를 읽거나 상호작용할 때 메시지의 상태를 효율적으로 관리하며, 대량의 메시지 상태 변경을 최적화된 방식으로 처리합니다.

주요 특징

일괄 업데이트: 여러 메시지의 상태를 한번의 요청으로 동시 처리
성능 최적화: Bulk update를 통한 데이터베이스 효율성 향상
상태 추적: 메시지 읽음, 상호작용, 만료 등 다양한 상태 관리
실시간 반영: 업데이트된 상태가 즉시 시스템에 반영

데이터 활용

업데이트된 메시지 상태 데이터는 다음과 같은 용도로 활용됩니다:

사용자 경험 개선: 읽은 메시지와 읽지 않은 메시지 구분 표시
상호작용 분석: 사용자의 메시지 참여도 및 반응 패턴 분석
알림 관리: 읽지 않은 메시지 수 계산 및 알림 배지 표시
워크플로우 최적화: 사용자 행동 기반 메시지 전략 개선
데이터 분석: 메시지 효과성 및 사용자 참여도 측정

제약사항

유효한 액세스 토큰 필요 (JWT 인증)
인증된 사용자만 해당 사용자의 메시지 상태 업데이트 가능
메시지 ID 배열은 최소 1개 이상 필요 (빈 배열이나 null 값은 오류 반환)
status는 MessageStatus enum 값 중 하나여야 함 (유효하지 않은 값은 오류 반환)
존재하지 않는 메시지 ID에 대해서는 무시되며 오류 발생하지 않음
상태 변경은 비가역적 (되돌릴 수 없음)

메시지 상태 업데이트

여러 에이전트 보드 메시지의 상태를 한번에 업데이트합니다.

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

Headers

Header	Type	Description	Required
`Authorization`	`Bearer {accessToken}`	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
`Content-Type`	`application/json`	JSON 형식의 요청 본문을 전송합니다.	Yes
`Accept`	`application/json`	JSON 형식의 응답을 요청합니다.	Yes
`Accept-Language`	`de-DE`, `en-US`, `ko-KR`	오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.	No

Request Body

Request Schema

{
  "messageIds": ["string"],
  "status": "string"
}

Request Fields

필드	타입	설명	예시값	필수
`messageIds`	string[]	상태를 업데이트할 메시지 ID 배열 (최소 1개 이상 필요)	`["msg-123", "msg-456", "msg-789"]`	Yes
`status`	string	새로운 메시지 상태 - MessageStatus enum 값 중 하나여야 함	`"VIEWED"`	Yes

Responses

HTTP Status Code	설명	Error Code(s)
200	메시지 상태 업데이트 성공	-
400	잘못된 요청 파라미터	`BAD_REQUEST`, `MESSAGE_IDS_REQUIRED`, `INVALID_MESSAGE_STATUS`
401	인증되지 않은 액세스	`UNAUTHORIZED`
500	내부 서버 오류	`INTERNAL_ERROR`

200 OK

메시지 상태가 성공적으로 업데이트되었습니다.

Response Schema

{
  "success": "boolean",
  "updatedCount": "number",
  "updatedMessageIds": ["string"],
  "status": "string",
  "message": "string"
}

Response Fields

필드	타입	설명	예시값	필수
`success`	boolean	업데이트 성공 여부	`true`	Yes
`updatedCount`	number	실제로 업데이트된 메시지 수	`3`	Yes
`updatedMessageIds`	string[]	업데이트된 메시지 ID 배열	`["msg-123", "msg-456", "msg-789"]`	Yes
`status`	string	업데이트된 상태 값 - MessageStatus 참조	`"VIEWED"`	Yes
`message`	string	업데이트 결과 메시지	`"Successfully updated 3 message(s) to VIEWED"`	Yes

데이터 타입 정의

MessageStatus

메시지의 현재 상태를 나타내는 상태 값입니다.

값	설명	사용 시점	읽음 여부	클라이언트 업데이트 가능 여부
`QUEUED`	전달 대기	메시지가 생성되었지만 아직 사용자에게 전달되지 않은 상태	N	❌
`DELIVERED`	전달됨	메시지가 사용자에게 성공적으로 전달된 상태	N	✅
`VIEWED`	조회됨	사용자가 메시지를 화면에서 확인한 상태	Y	✅
`INTERACTED`	상호작용 발생	사용자가 메시지의 액션 버튼을 클릭하거나 상호작용한 상태	Y	✅
`EXTERNALLY_COMPLETED`	외부 완료	다른 곳에서 관련 인터랙션 발생으로 완료 처리된 상태	Y	❌
`EXPIRED`	만료됨	메시지의 유효 기간이 지나 더 이상 표시되지 않는 상태	Y	✅
`ARCHIVED`	아카이빙됨	시스템에 의해 보관 처리되었거나, 사용자가 보관 처리한 상태	Y	✅

상태 변경 시나리오

일반적인 메시지 상태 변경 흐름은 다음과 같습니다:

QUEUED → DELIVERED: 메시지가 사용자에게 전달됨
DELIVERED → VIEWED: 사용자가 메시지를 읽음
VIEWED → INTERACTED: 사용자가 액션 버튼을 클릭함
DELIVERED 또는 VIEWED → EXPIRED: 메시지 유효 기간 만료
EXPIRED → ARCHIVED: 시스템에 의한 아카이빙
DELIVERED -> EXTERNALLY_COMPLETED: 인터랙션 발생으로 완료 처리

Success Response Example

{
  "success": true,
  "updatedCount": 3,
  "updatedMessageIds": ["msg-123", "msg-456", "msg-789"],
  "status": "VIEWED",
  "message": "Successfully updated 3 message(s) to VIEWED"
}

Request Example

{
  "messageIds": ["msg-123", "msg-456", "msg-789"],
  "status": "VIEWED"
}

400 Bad Request

messageIds가 빈 배열이거나 누락된 경우:

{
  "statusCode": 400,
  "message": "메시지 ID 목록이 필요합니다.",
  "error": "MESSAGE_IDS_REQUIRED",
  "errorCode": 12059
}

status가 유효하지 않은 enum 값인 경우:

{
  "statusCode": 400,
  "message": "유효하지 않은 메시지 상태입니다.",
  "error": "INVALID_MESSAGE_STATUS",
  "errorCode": 12060
}

401 Unauthorized

인증되지 않은 요청입니다.

{
  "statusCode": 401,
  "message": "Unauthorized access",
  "error": "Unauthorized"
}

500 Internal Server Error

서버 내부 오류가 발생했습니다.

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

사용 예시

단일 메시지 읽음 처리

curl -X PATCH "https://api.example.com/v1/agent-board/messages/status" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "messageIds": ["msg-123"],
    "status": "VIEWED"
  }'

여러 메시지 일괄 상호작용 처리

curl -X PATCH "https://api.example.com/v1/agent-board/messages/status" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "messageIds": ["msg-123", "msg-456", "msg-789"],
    "status": "INTERACTED"
  }'

만료된 메시지 아카이빙

curl -X PATCH "https://api.example.com/v1/agent-board/messages/status" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "messageIds": ["msg-expired-1", "msg-expired-2"],
    "status": "ARCHIVED"
  }'

개요​

주요 특징​

데이터 활용​

제약사항​

메시지 상태 업데이트​

Headers​

Request Body​

Responses​

200 OK​

데이터 타입 정의​

MessageStatus​

상태 변경 시나리오​

400 Bad Request​

401 Unauthorized​

500 Internal Server Error​

사용 예시​

단일 메시지 읽음 처리​

여러 메시지 일괄 상호작용 처리​

만료된 메시지 아카이빙​

관련 API​

개요