> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 고객 속성

> 조직에서 정의한 항목에 맞춰 고객 정보를 구조화합니다. 대화에서 값을 자동으로 추출합니다.

메모리는 자유로운 문장으로 남기는 정보이고, 고객 속성은 정해진 형식으로 저장하는
값입니다. `멤버십 등급: 골드`, `첫 상담일: 2026-07-12`처럼 조직이 정의한 항목에
맞춰 저장됩니다. 고객을 분류하거나 외부 시스템과 연동할 때 사용합니다.
값은 대화에서 자동으로 추출됩니다.

## 이럴 때 사용하세요

| 목적            | 속성 예시    | 값 형식 | 갱신 방식    |
| ------------- | -------- | ---- | -------- |
| 고객의 최근 관심사 분류 | 관심 상품    | 텍스트  | 항상 덮어쓰기  |
| 정해진 단계로 고객 분류 | 멤버십 등급   | 선택지  | 항상 덮어쓰기  |
| 최초 접점 보존      | 최초 유입 경로 | 선택지  | 비어 있을 때만 |
| 처음 확인한 날짜 보존  | 첫 상담일    | 날짜   | 비어 있을 때만 |

긴 상담 맥락이나 예외 사항은 [메모리](/docs/build/customer-memory/memory)에 더 적합합니다.
주문 상태처럼 원본 시스템에서 최신 값을 확인해야 하는 정보는 자동 추출 대신 API로
동기화하세요.

## 속성 정의 만들기

고객 속성 정의는 어떤 항목을 어떤 형식으로 모을지 정합니다.
대시보드의 **설정 > 고객 속성**에서 정의를 만들고,
속성 이름, 설명, 값 형식을 입력하세요. 설명은 대화에서 어떤 값을 추출할지
판단하는 기준이 되므로 구체적으로 적을수록 정확하게 추출됩니다.

| 값 형식  | 설명                  | 예시                 |
| ----- | ------------------- | ------------------ |
| 텍스트   | 자유롭게 입력하는 짧은 값      | 관심 상품              |
| 숫자    | 정수 또는 소수            | 예상 구매 수량           |
| 예·아니요 | 두 상태 중 하나           | 재연락 희망 여부          |
| 날짜    | `YYYY-MM-DD` 형식의 날짜 | 첫 상담일              |
| 선택지   | 미리 정한 값 중 하나        | 멤버십 등급 (브론즈/실버/골드) |

**선택지**를 고르면 저장할 수 있는 값도 함께 설정합니다.

```mermaid theme={null}
flowchart LR
    A[속성 정의 생성] --> B[메모리 활성화]
    B --> C[대화 종료]
    C --> D[고객 속성 자동 추출]
```

## 자동 추출

활성화된 속성 정의가 있으면 대화에서 근거가 있는 값만 추출합니다.
고객이 말하지 않은 내용을 추측해 채우지 않습니다.
추출은 인터랙션이 끝난 뒤 진행됩니다.

<Note>
  고객 속성 자동 추출도 **메모리 활성화**를 켜야 실행합니다. 에이전트 빌드
  화면의 [메모리 섹션](/docs/build/customer-memory/memory)에서 켤 수 있습니다.
</Note>

### 값 충돌 처리

이미 값이 있는 속성에 새 값이 추출되면 어떻게 할지 정의별로 선택합니다.

<Tabs>
  <Tab title="항상 덮어쓰기">
    새 값을 추출하면 기존 값을 새 값으로 바꿉니다. 관심 상품이나 멤버십 등급처럼
    최신 상태를 유지해야 할 때 사용하세요.
  </Tab>

  <Tab title="비어 있을 때만">
    저장된 값이 없을 때만 추출한 값을 넣습니다. 최초 유입 경로나 첫 상담일처럼 처음
    확인한 값을 유지할 때 사용하세요.
  </Tab>
</Tabs>

## 저장된 값 관리하기

고객 상세 화면에서는 고객 속성을 조회하고 필터에 사용할 수 있지만 직접 수정하거나
삭제할 수는 없습니다. 자동 추출 결과를 정정해야 한다면 v3 API로 값을 변경하세요.
API로 직접 변경한 값에는 자동 추출의 충돌 처리 방식이 적용되지 않습니다.

속성 정의의 생성·조회·수정·삭제는 API로도 할 수 있습니다.
[v3 API 참조](/api-reference/v3/introduction)를 확인하세요.

## 권장 운영법

* **한 속성에는 한 가지 사실만 담으세요.** `관심 상품 및 구매 시기`보다 `관심 상품`,
  `구매 예정일`처럼 나누면 추출 결과를 검색하고 연동하기 쉽습니다.
* **설명에 판단 기준을 적으세요.** `관심 상품`이라면 “고객이 구매 의사를 밝힌 제품명”처럼
  어떤 발화를 근거로 삼을지 구체적으로 작성하세요.
* **분류에는 선택지를 우선 사용하세요.** 표기가 제각각인 텍스트보다 정해진 선택지가
  검색과 집계에 유리합니다. 서로 겹치지 않는 값만 두세요.
* **처음 확인한 값을 보존해야 할 때만 `비어 있을 때만`을 사용하세요.** 이 방식은 자동
  추출로 기존 값을 바꾸지 않습니다. 정정이 필요하면 v3 API로 직접 수정하세요.
* **운영 중인 속성의 이름은 신중하게 바꾸세요.** 이름을 바꿔도 고객에게 저장된
  기존 값은 새 이름으로 옮겨지지 않습니다. 새 이름이 필요하면 이관 계획을 먼저
  세우세요.
* **값 형식은 생성 후 바꿀 수 없습니다.** 다른 형식이 필요하면 새 속성 정의를 만들고
  기존 값을 옮기세요.

***

<Accordion title="연관 검색어">
  고객 속성, attribute, 속성 정의, 자동 추출, 값 형식, 선택지, 갱신 방식, 구조화
</Accordion>