본문으로 건너뛰기

상담 태그

상담(채널)에 붙이는 태그의 카탈로그를 읽는 조회 API입니다. 연락처 태그(/contact-tags)와는 완전히 별개의 목록이라, 같은 이름의 태그가 한쪽에만 있을 수 있습니다.

특정 상담에 실제로 붙어 있는 태그는 이 엔드포인트가 아니라 채널 객체의 tags 배열에 있습니다. 자세한 내용은 채널을 참고하세요.

목록 조회​

GET /channel-tags — 워크스페이스에 정의된 상담 태그 카탈로그를 cursor pagination으로 조회합니다.

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

created_at 내림차순으로 반환합니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/channel-tags?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "t1a2b3c4-...",
      "name": "환불요청",
      "color": "#ff0000",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    },
    {
      "id": "t5d6e7f8-...",
      "name": "재고문의",
      "created_at": "2026-01-02T00:00:00Z",
      "updated_at": "2026-01-02T00:00:00Z"
    }
  ],
  "meta": { "has_more": false }
}

응답 필드

필드타입설명
idstring태그 UUID
namestring태그 이름
colorstring태그 색상(예: #ff0000). 색상을 정하지 않았으면 null이 아니라 키가 생략됩니다. "color" in tag로 판별하세요. 위 예시의 두 번째 태그가 색상 미지정입니다.
created_atstring생성 시각(RFC3339)
updated_atstring마지막 수정 시각(RFC3339)
연락처 태그와 달리 usage_count가 없습니다

상담 태그는 사용 횟수를 정확하게 셀 수 없어서 공개 API 응답에 usage_count를 싣지 않습니다. 특정 태그가 붙은 상담 수가 필요하면 채널 목록을 ?tags=로 거르고 개수를 세세요.

태그로 상담 찾기​

카탈로그에서 얻은 태그 이름으로 채널 목록을 거릅니다. 아래 첫 번째 명령은 환불요청 또는 VIP가 붙은 상담을, 두 번째 명령은 둘 다 붙은 상담을 조회합니다.

# '환불요청' 또는 'VIP' 가 붙은 상담
curl "https://api.talk.zeroworks.ai/api/public/v1/channels?tags=환불요청,VIP&tag_match=any" \
  -H "Authorization: Bearer ztpat_..."

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

파라미터 정의는 채널 — 목록 조회에 있습니다. 다음 페이지를 받을 때는 cursor와 함께 tags·tag_match를 다시 보내야 합니다. cursor는 위치만 담고 필터는 담지 않습니다.

태그 부여·해제​

상담에 태그를 붙이고 떼는 방법은 메시지·채널 쓰기에 있습니다. 이 페이지의 카탈로그는 어떤 태그가 있는지 알려 주고, 실제 부여는 채널 엔드포인트가 합니다.

태그 카탈로그 자체를 만들거나 지우는 엔드포인트는 없습니다. 이름 변경·삭제는 그 태그가 붙은 모든 상담에서 태그를 되돌릴 수 없게 떼어 내는 작업이라, 대시보드에서 관리자만 할 수 있습니다.

다만 상담에 카탈로그에 없는 이름을 붙이면 그 이름이 카탈로그에 자동으로 추가됩니다. 연동이 임의의 이름을 계속 만들면 태그 목록이 늘어나고, 정리는 대시보드에서만 할 수 있습니다. 가능하면 이 페이지로 기존 이름을 먼저 조회해서 쓰세요.

오류​

HTTPcode발생 조건
400INVALID_QUERYlimit이 1~100 범위를 벗어남(값을 보정하지 않습니다), 또는 cursor가 만료되었거나 형식이 틀림

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