메시지메시지채팅방 메시지 조회

채팅방별 메시지 조회

개요

지정된 채팅방의 메시지 기록을 조회하며, 시간 범위 필터링 및 페이지네이션을 지원합니다. 이 API는 메시지 목록 조회와 동일한 엔드포인트 GET /rooms/{id}/messages/v3를 사용합니다. 이 페이지는 일반적인 조회 시나리오와 예시에 초점을 맞춥니다.


API 엔드포인트

채팅방의 모든 메시지 조회

지정된 채팅방의 메시지 기록을 조회하며, 페이지네이션 및 시간 필터링을 지원합니다.

GET /rooms/{id}/messages/v3

Headers

ParameterTypeRequiredDescription
IM-CLIENT-KEYstringClient Key
IM-AuthorizationstringClient Token

Path Parameters

ParameterTypeRequiredDescription
idstring채팅방 ID

Query Parameters

ParameterTypeRequiredDescription
limitnumber반환할 최대 메시지 수 (기본값: 20, 권장: 50-100)
beforeMessagestring지정된 메시지 ID 이전 메시지 조회 (이전 페이지 이동)
afterMessagestring지정된 메시지 ID 이후 메시지 조회 (다음 페이지 이동)
afterTimestring지정된 시간 이후 메시지 조회 (ISO-8601 또는 밀리초 타임스탬프 형식)
timeRangeFieldstring시간 범위 조회에 사용할 필드: updatedAt, createdAt, messageTime (기본값: updatedAt)

Example Request

채팅방의 최신 메시지 조회

GET /rooms/demo-room/messages/v3?limit=50 HTTP/1.1
IM-CLIENT-KEY: {IM-CLIENT-KEY}
IM-Authorization: {IM-Authorization}
Host: your-app.imkit.io
Connection: close

이전 메시지 조회 (페이지네이션)

GET /rooms/demo-room/messages/v3?limit=50&beforeMessage=5f890cf37d980e06f6aaf349 HTTP/1.1
IM-CLIENT-KEY: {IM-CLIENT-KEY}
IM-Authorization: {IM-Authorization}
Host: your-app.imkit.io
Connection: close

특정 시간 이후 메시지 조회

GET /rooms/demo-room/messages/v3?afterTime=2024-01-01T00:00:00Z&limit=100 HTTP/1.1
IM-CLIENT-KEY: {IM-CLIENT-KEY}
IM-Authorization: {IM-Authorization}
Host: your-app.imkit.io
Connection: close

JavaScript 예시:

const response = await axios.get(
  `https://your-app.imkit.io/rooms/demo-room/messages/v3`,
  {
    params: {
      limit: 50,
    },
    headers: {
      "IM-CLIENT-KEY": IM_CLIENT_KEY,
      "IM-Authorization": TOKEN,
    },
  }
);

cURL 예시:

curl -X "GET" "https://your-app.imkit.io/rooms/demo-room/messages/v3?limit=50" \
     -H 'IM-CLIENT-KEY: {IM-CLIENT-KEY}' \
     -H 'IM-Authorization: {IM-Authorization}'

Response

Success Response (200 OK)

ParameterTypeDescription
RCnumber응답 코드 (0은 성공을 의미)
RMstring응답 메시지
resultobject메시지 조회 결과

조회 결과 구조

ParameterTypeDescription
totalCountnumber채팅방의 총 메시지 수
dataarray메시지 배열 (시간순 정렬)
userDeletedIDsarray현재 사용자가 삭제한 메시지 ID 배열
inspectobject진단 정보 (조회 조건 및 실행 시간 포함)

메시지 객체 구조

ParameterTypeDescription
_idstring메시지 고유 ID
messageany메시지 내용
roomstring연결된 채팅방 ID
senderobject발신자 정보
messageTypestring메시지 유형
messageTimeMSnumber메시지 전송 시간 (밀리초 타임스탬프)
updatedAtMSnumber메시지 업데이트 시간 (밀리초 타임스탬프)
createdAtMSnumber메시지 생성 시간 (밀리초 타임스탬프)
reactionsarray메시지 반응 목록
reactionCountnumber총 반응 수

Example Response

{
  "RC": 0,
  "RM": "OK",
  "result": {
    "totalCount": 245,
    "inspect": {
      "query": {
        "appID": "SampleApp",
        "room": "demo-room",
        "status": { "$ne": 0 }
      },
      "tookMS": 8
    },
    "data": [
      {
        "reactions": [],
        "_id": "5f890cf37d980e06f6aaf349",
        "message": "Hello everyone! Welcome to our chat room.",
        "room": "demo-room",
        "sender": {
          "_id": "user123",
          "nickname": "Alice",
          "avatarUrl": "https://example.com/avatar1.jpg",
          "id": "user123",
          "lastLoginTimeMS": 1640995200000
        },
        "messageType": "text",
        "id": "5f890cf37d980e06f6aaf349",
        "messageTimeMS": 1640995200000,
        "updatedAtMS": 1640995200001,
        "createdAtMS": 1640995200001,
        "reactionCount": 0
      }
    ],
    "userDeletedIDs": []
  }
}

Error Response

401 Unauthorized - 인증 실패

{
  "RC": 401,
  "RM": "Unauthorized",
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid or expired token"
  }
}

403 Forbidden - 권한 부족

{
  "RC": 403,
  "RM": "Forbidden",
  "error": {
    "code": "NOT_ROOM_MEMBER",
    "message": "User is not a member of this room"
  }
}

404 Not Found - 채팅방이 존재하지 않음

{
  "RC": 404,
  "RM": "Room not found",
  "error": {
    "code": "ROOM_NOT_FOUND",
    "message": "Room with specified ID does not exist"
  }
}

Use Cases

채팅방 로딩

  • 초기 로드: 사용자가 채팅방 진입 시 최신 메시지를 로드
  • 기록 탐색: 사용자가 스크롤을 올려 이전 메시지 기록을 열람
  • 새로 고침: 채팅방의 전체 대화 내용을 다시 로드

메시지 동기화

  • 오프라인 동기화: 사용자가 다시 온라인이 될 때 놓친 메시지를 동기화
  • 기기 간 동기화: 여러 기기에서 메시지 일관성을 유지
  • 백업 복구: 백업으로부터 채팅방의 전체 기록을 복원

콘텐츠 분석

  • 대화 분석: 채팅방의 대화 패턴 및 인기 주제 분석
  • 활동 통계: 채팅방의 메시지 양과 사용자 참여도 추적
  • 콘텐츠 모더레이션: 채팅방의 모든 대화 내용을 검토

Notes

  • 권한 필요: 채팅방 멤버만 메시지 내용을 조회할 수 있습니다
  • 페이지네이션 권장: 한 번에 너무 많은 데이터를 로드하지 않도록 적절한 limit 값 (20-100)을 사용하세요
  • 시간 정렬: 메시지는 updatedAt 시간 기준으로 정렬되며, 최신 메시지가 먼저 표시됩니다
  • 삭제 처리: userDeletedIDs 배열에는 현재 사용자가 삭제한 메시지가 포함되므로 UI에서 필터링해야 합니다
  • 성능 최적화: 대형 채팅방의 경우 시간 범위 제한을 사용하여 조회 성능을 향상시키는 것이 권장됩니다
  • 실시간 업데이트: 이 API는 일괄 로딩에 적합하며, 실시간 메시지는 WebSocket 연결을 사용하세요
© 2026 FUNTEK Software Inc. All rights reserved.