연락처 태그

워크스페이스에 정의된 연락처 태그의 카탈로그를 읽는 조회 API입니다. 상담(채널)에 붙이는 태그(상담 태그)와는 별개의 목록이라, 같은 이름의 태그가 한쪽에만 있을 수 있습니다. 특정 연락처에 부여된 태그 이름은 이 엔드포인트가 아니라 GET /contacts/{id}/tags로 조회합니다.

목록 조회

GET /contact-tags — 연락처 태그 카탈로그를 cursor pagination으로 조회합니다.

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

특정 연락처가 아니라 워크스페이스 전체의 태그 정의를 created_at 내림차순으로 반환합니다.

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

응답

{
  "success": true,
  "data": [
    {
      "id": "t1a2b3c4-...",
      "name": "vip",
      "color": "#ff0000",
      "usage_count": 12,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    },
    {
      "id": "t5d6e7f8-...",
      "name": "신규문의",
      "usage_count": 0,
      "created_at": "2026-01-02T00:00:00Z",
      "updated_at": "2026-01-02T00:00:00Z"
    }
  ],
  "meta": { "has_more": false }
}

응답 필드

필드	타입	설명
id	string	태그 UUID
name	string	태그 이름
color	string	태그 색상(예: #ff0000). 색상을 정하지 않았으면 null이 아니라 키가 생략됩니다. "color" in tag로 판별하세요. 위 예시의 두 번째 태그가 색상 미지정입니다.
usage_count	integer	이 태그가 부여된 연락처 수
created_at	string	생성 시각(RFC3339)
updated_at	string	마지막 수정 시각(RFC3339)

오류

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

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