검색

메시지 검색

GET /search — 워크스페이스 내 메시지 본문을 자유 텍스트로 검색합니다.

Scope: search:read
쿼리: q(검색어, 필수, 2~200자)

검색은 단일 페이지로 응답하며 cursor가 없습니다. total은 쿼리에 매칭된 전체 문서 수이며 100을 초과할 수 있습니다. 단일 응답에 반환되는 hits는 최대 100건으로 제한되므로, 더 많은 결과가 필요하면 q를 좁혀 다시 검색하세요. 검색 대상은 메시지 본문으로 한정됩니다.

q가 2자 미만이거나 200자를 초과하면 400 INVALID_QUERY를 반환합니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/search?q=환불" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": {
    "query": "환불",
    "hits": [
      {
        "id": "f1e2d3c4-...",
        "channel_id": "c1d2e3f4-...",
        "sender_id": "a1b2c3d4-...",
        "sender_type": "contact",
        "sender_name": "홍길동",
        "content_type": "text",
        "content": "환불 요청합니다",
        "created_at": "2026-05-01T10:00:00Z"
      }
    ],
    "total": 1
  }
}

매칭되는 메시지가 없으면 hits는 빈 배열, total은 0입니다. 검색은 워크스페이스에 색인된 메시지 본문을 대상으로 하며, 방금 보낸 메시지는 색인까지 짧은 지연이 있을 수 있습니다. 삭제된 메시지와 시스템이 생성한 메시지(sender_type=system)는 결과에서 제외됩니다.

각 hit는 메시지의 읽기 전용 스냅샷이며 다음 필드를 포함합니다.

{
  "id": "f1e2d3c4-...",
  "channel_id": "c1d2e3f4-...",
  "sender_id": "a1b2c3d4-...",
  "sender_type": "contact",
  "sender_name": "홍길동",
  "content_type": "text",
  "content": "환불 요청합니다",
  "created_at": "2026-05-01T10:00:00Z"
}

sender_type: member · contact · bot · internal · workflow · external · integration
content_type: text · markdown · image · file · card · button · email · video · audio · blocks · sticker · location

hit에는 첨부·메타데이터·편집 상태가 포함되지 않습니다. 전체 메시지와 첨부는 GET /messages/{id}, GET /attachments/{id}로 조회합니다.

메시지 검색​

메시지 검색