본문으로 건너뛰기

검색

워크스페이스의 메시지 본문을 자유 텍스트로 검색하는 조회 API입니다. 검색 결과는 메시지의 읽기 전용 스냅샷이며, 전체 메시지와 첨부는 메시지 API로 이어서 조회합니다.

메시지 검색​

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

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

q는 앞뒤 공백을 제거한 뒤 글자 수를 셉니다. 2자 미만이거나 200자를 초과하면 400 INVALID_QUERY를 반환합니다.

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

검색 색인이 구성되지 않은 서버에서는 503 SEARCH_UNAVAILABLE을 반환합니다. 토큰 권한 문제가 아니므로 search:read를 다시 확인할 필요는 없습니다(대응은 에러 참고).

아래 요청은 "환불"이 들어간 메시지를 검색합니다.

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 필드​

각 hit는 메시지의 읽기 전용 스냅샷이며, 첨부·메타데이터·편집 상태는 포함하지 않습니다. 전체 메시지와 첨부는 GET /messages/{id}, GET /attachments/{id}로 조회합니다.

필드설명
id메시지 ID
channel_id메시지가 속한 채널 UUID
sender_id·sender_name발신자 식별자와 표시 이름
sender_typemember · contact · bot · internal · workflow · external · integration
content_typetext · markdown · image · file · card · button · email · video · audio · blocks · sticker · location
content메시지 본문
created_atRFC 3339 시각