본문으로 건너뛰기

채널

목록 조회​

GET /channels — 채널 목록을 cursor pagination으로 조회합니다.

  • Scope: channels:read
  • 쿼리: limit(기본 50, 최대 100), cursor, tags, tag_match

삭제되지 않은 모든 채널을 open·snoozed·closed 상태 구분 없이 반환합니다. 서버 측 상태 필터 파라미터는 없으므로, 특정 상태만 필요하면 응답의 status 필드로 직접 필터링하세요.

태그 필터

쿼리값
tags상담 태그 이름을 쉼표로 구분 (예: tags=환불요청,VIP). 이름 앞뒤 공백은 무시합니다. 값이 비어 있으면(?tags=) 필터를 적용하지 않습니다
tag_matchany(기본) — 하나라도 붙은 상담 · all — 나열한 태그가 전부 붙은 상담. 그 외 값은 400 INVALID_QUERY (tags 없이 보내도 값이 틀리면 400)

쉼표로 나눈 뒤 남는 이름이 하나도 없으면(?tags=,,, ?tags=%20) 400 INVALID_QUERY입니다 — 필터를 조용히 무시하고 전체 목록을 돌려주지 않습니다. 태그 이름은 대소문자를 구분합니다.

커서와 함께 쓸 때: meta.next_cursor로 다음 페이지를 받을 때 tags·tag_match를 같이 다시 보내야 합니다. 커서는 목록에서의 위치만 담고 필터 조건은 담지 않으므로, 커서만 보내면 필터가 풀린 전체 목록이 이어집니다.

태그 이름 목록은 상담 태그에서 조회합니다. 없는 이름으로 필터하면 오류가 아니라 빈 결과가 나옵니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/channels?tags=환불요청,VIP&tag_match=all" \
  -H "Authorization: Bearer ztpat_..."
curl "https://api.talk.zeroworks.ai/api/public/v1/channels?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "c1d2e3f4-...",
      "type": "user_chat",
      "provider": "kakao",
      "status": "open",
      "contact_id": "a1b2c3d4-...",
      "assigned_member_id": "m1n2o3-...",
      "assigned_type": "human",
      "tags": [],
      "last_message_at": "2026-05-01T10:00:00Z",
      "message_count": 12,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": false }
}

has_more가 true이면 meta.next_cursor가 함께 내려옵니다. 다음 페이지는 이 값을 cursor 쿼리로 전달해 이어갑니다 — 페이지네이션 참조.

필드 값 집합

필드값
typeuser_chat | team | direct | group (공개 API로 노출되는 상담 채널은 대부분 user_chat)
providernative | web | kakao | naver | email | line | whatsapp | instagram | sms | voice
statusopen | snoozed | closed
assigned_typeai | human | workflow — 미배정 채널에서는 필드 자체가 생략됩니다
tags이 상담에 붙어 있는 상담 태그 이름 배열. 없으면 빈 배열이며 키는 항상 존재합니다. 워크스페이스 전체 태그 목록은 상담 태그 참조

name·description·contact_id·assigned_member_id·last_message_at·snoozed_until은 값이 없으면 null이 아니라 키가 생략됩니다. 존재 여부는 "key" in obj로 판별하세요.

단건 조회​

GET /channels/{id} — 단일 채널을 조회합니다. {id}는 채널 UUID입니다.

  • Scope: channels:read
{ "success": true, "data": { "id": "c1d2e3f4-...", "type": "user_chat", "status": "open", "provider": "kakao", "tags": [], "message_count": 12, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-05-01T10:00:00Z" } }