본문으로 건너뛰기

메시지

채널 메시지 목록​

GET /channels/{id}/messages — 채널 내 메시지를 cursor pagination으로 조회합니다.

  • Scope: channels:read + messages:read (둘 다 필요)
  • 쿼리: since(RFC3339, 필수), until(RFC3339, 기본 현재 시각), limit, cursor
  • 조회 구간은 (since, until]입니다 — since는 배타적(경계 시각과 정확히 같은 메시지는 제외), until은 포함적입니다.
  • 다음 경우 400 INVALID_QUERY를 반환합니다: since 누락·형식 오류, until 형식 오류, until이 since보다 뒤가 아닌 경우(같은 시각 포함), until - since가 30일 초과, limit이 [1, 100] 범위를 벗어난 경우, cursor 길이 초과.
curl "https://api.talk.zeroworks.ai/api/public/v1/channels/c1d2.../messages?since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "msg-1a2b-...",
      "channel_id": "c1d2e3f4-...",
      "sender_id": "a1b2c3d4-...",
      "sender_type": "contact",
      "sender_name": "홍길동",
      "content_type": "text",
      "content": "안녕하세요",
      "attachments": [
        { "id": "att-1a2b-...", "type": "image", "filename": "photo.png" }
      ],
      "is_edited": false,
      "created_at": "2026-05-01T10:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": true, "next_cursor": "..." }
}

메시지 cursor는 만료가 없습니다(자세한 내용은 페이지네이션 참고). attachments는 참조(id/type/filename)만 포함하며, 실제 다운로드 URL은 아래 첨부 엔드포인트로 조회합니다.

  • 정렬: 메시지는 created_at **내림차순(최신순)**으로 반환됩니다. next_cursor로 다음 페이지를 따라가면 since 경계를 향해 과거 방향으로 이동합니다(대화를 시간순으로 재구성하려면 클라이언트에서 역순 정렬하세요).
  • attachments: 첨부가 없는 메시지는 키 자체가 생략됩니다(빈 배열·null이 아님).

필드 값 집합​

필드값
sender_typemember(상담원)·contact(고객)·system(시스템)·bot(봇)·internal(내부)·workflow(워크플로)·external(외부 플랫폼 상담원, 예: 네이버 톡톡)·integration(PAT 기반 아웃바운드 발신)
content_typetext·markdown·image·file·card·button·email·video·audio·system·blocks·sticker·location
attachments[].typeimage·file·video·audio
  • sender_id: 불투명 식별자입니다 — 멤버/고객은 UUID, 봇·시스템 메시지는 고정 서비스 UUID(00000000-0000-0000-0000-000000000002)를 가지며, 항상 고객으로 해석되지는 않습니다.
  • sender_type·sender_name: 일부 시스템 발신 메시지에서는 빈 문자열("")일 수 있습니다.

단건 조회​

GET /messages/{id} — 단일 메시지를 조회합니다.

  • Scope: messages:read

첨부 다운로드​

GET /attachments/{id} — 첨부 메타와 다운로드 URL을 조회합니다.

  • Scope: attachments:read + messages:read (둘 다 필요)
  • status='ready'인 첨부만 노출됩니다 (그 외 → 404)
  • url은 5분간 유효한 presigned URL입니다 (url_expires_at 확인)
{
  "success": true,
  "data": {
    "id": "att-1a2b-...",
    "filename": "photo.png",
    "content_type": "image/png",
    "size_bytes": 10240,
    "url": "https://s3.../photo.png?X-Amz-...",
    "url_expires_at": "2026-05-01T10:05:00Z",
    "created_at": "2026-05-01T10:00:00Z"
  }
}