본문으로 건너뛰기

채널

채널은 고객과 주고받는 상담의 단위입니다. 이 문서는 상담 목록과 단건 정보를 읽는 조회 API를 설명합니다. 상담의 메시지는 메시지에서, 상담을 닫거나 배정하는 쓰기 작업은 메시지·채널 쓰기에서 다룹니다.

목록 조회​

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

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

삭제되지 않은 모든 채널을 상태에 관계없이 created_at 내림차순(최신 먼저)으로 반환합니다. 서버에는 상태 필터 파라미터가 없으므로, 특정 상태만 필요하면 응답의 status로 직접 거르세요.

태그 필터

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

쉼표로 나눈 뒤 남는 이름이 하나도 없으면(?tags=,,, ?tags=%20) 필터를 조용히 무시하고 전체 목록을 돌려주는 대신 400 INVALID_QUERY를 반환합니다. 카탈로그에 없는 이름으로 거르면 오류가 아니라 빈 결과가 나옵니다. 태그 이름 목록은 상담 태그에서 조회합니다.

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

아래 명령은 환불요청과 VIP가 모두 붙은 상담을 조회합니다.

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

필터 없이 한 번에 50건씩 읽는 명령은 다음과 같습니다.

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 쿼리로 넘겨 다음 페이지를 받으세요. 자세한 규칙은 페이지네이션을 참고하세요.

응답 필드

필드타입설명
idstring채널 UUID
typestringuser_chat | team | direct | group. 공개 API로 볼 수 있는 상담 채널은 대부분 user_chat입니다.
providerstring상담이 들어온 경로. native | web | kakao | naver | email | line | whatsapp | instagram | messenger | sms | voice | board | api
statusstring상담 상태. open | snoozed | closed | pending(워크플로가 응대 중인 단계) | abandoned(고객이 답하지 않아 워크플로 응대가 끝난 상태)
name, descriptionstring채널 이름과 설명. 값이 없으면 키가 생략됩니다.
contact_idstring이 상담의 고객(연락처) UUID. 값이 없으면 키가 생략됩니다.
assigned_member_idstring배정된 상담원의 멤버 ID. 값이 없으면 키가 생략됩니다.
assigned_typestring배정 주체. ai | human | workflow. 미배정 채널에서는 키가 생략됩니다.
tagsstring[]이 상담에 붙어 있는 상담 태그 이름 배열. 없으면 빈 배열이며 키는 항상 있습니다. 워크스페이스 전체 태그 목록은 상담 태그에서 조회합니다.
last_message_atstring마지막 메시지 시각(RFC3339). 값이 없으면 키가 생략됩니다.
message_countinteger채널의 메시지 수
snoozed_untilstring스누즈를 해제하는 시각(RFC3339). 값이 없으면 키가 생략됩니다.
created_atstring생성 시각(RFC3339)
updated_atstring마지막 수정 시각(RFC3339)

값이 없는 선택 필드는 null이 아니라 키 자체가 생략됩니다. "key" in obj로 존재 여부를 판별하세요.

단건 조회​

GET /channels/{id} — 채널 하나를 조회합니다. {id}는 채널 UUID입니다.

  • Scope: channels:read
curl "https://api.talk.zeroworks.ai/api/public/v1/channels/c1d2e3f4-..." \
  -H "Authorization: Bearer ztpat_..."

응답 — data에 목록 조회와 같은 필드의 채널 객체 하나가 들어 있습니다. 아래는 배정·메시지가 없는 채널의 예시입니다.

{ "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" } }

오류​

HTTPcode발생 조건
400INVALID_QUERYlimit이 1~100 범위를 벗어남(값을 보정하지 않습니다), cursor가 만료되었거나 형식이 틀림, tag_match가 any·all이 아님, tags에 이름이 하나도 없음
400INVALID_INPUT{id}가 UUID 형식이 아님
404NOT_FOUND채널이 없거나 이 워크스페이스에 속하지 않음, 또는 삭제됨

공통 오류는 에러 문서를 참고하세요.