대화 메타데이터

대화 메타데이터는 사용자 지정 키-값 데이터를 대화에 첨부하여 자체 시스템과 AI 에이전트를 연결합니다. 메타데이터는 Quickchat 워크플로 전체에서 사용됩니다.

• API로 전달: 이 엔드포인트로 CRM, 헬프데스크, 백엔드 등에서 대화에 메타데이터를 프로그램 방식으로 첨부합니다.
• Widget/Embed로 전달: Widget을 불러올 때 초기화 매개변수로 전달하거나 JavaScript SDK로 진행 중인 대화에 동적으로 넣습니다.
• 대시보드에 표시: 사용자 지정 메타데이터는 받은편지함의 대화 상세 정보에 표시됩니다. 내부 키는 필터링되며 수집한 연락처와 Action 메모리는 별도로 표시됩니다.
• 내보내기에 포함: 대시보드에서 대화를 내보내면 메타데이터도 포함되어 오프라인 분석에 사용할 수 있습니다.
• AI Actions에 사용: 메타데이터 값을 {{metadata_<key>}} 자리표시자로 AI Actions에 직접 넣을 수 있습니다. 전체 목록은 AI Action 변수를 참고하세요.
• 허용된 경우 AI 에이전트가 사용: 모델 맥락에는 필터링한 일부 메타데이터가 들어갑니다. 키를 저장했다고 모델이 받거나 언급하는 것은 아닙니다.

고객 참조, 계정 맥락, 분석, Action 입력에 메타데이터를 사용하세요. 저장, 받은편지함 표시, Action 치환, 모델 맥락은 같은 데이터를 사용하는 별도 용도입니다.

대시보드에서 JSON 스키마를 설정했다면 해당 스키마로 메타데이터를 검증합니다.

선택적으로 사용할 수 있는 예시 검사

• 메타데이터 키 미리보기. 중복 이름과 예약 키 오류를 포함하여 입력한 필드 이름이 변수 키가 되는 방식을 확인합니다. 값이나 계정별 권한은 검사하지 않습니다.

• Action 실행 조건 검사하기. Action을 실행하지 않고 입력한 예시 메타데이터로 조건을 평가합니다.

호환되는 브라우저에서는 이 검사를 사이트 도구로도 사용할 수 있습니다. 링크는 일반 양식을 엽니다.

모델 맥락 및 권한 검증

웹사이트 Widget과 Embed처럼 방문자가 제어하는 채널에서는 방문자 연락처 키(visitor_name, visitor_email, visitor_phone_number)와 활성 Actions가 참조하거나 수집하는 허용된 키를 모델 맥락에 넣습니다. 내부 값과 예약 값은 필터링되며 설정 및 크기 제한도 적용됩니다. 다른 연동에는 채널별 맥락 규칙이 있습니다. 사용자 지정 customer_tier나 customer_id는 보냈다는 이유만으로 모델에 자동 노출되지 않습니다.

Action은 요청을 만들 때 AI에 값 생성을 맡기지 않고 {{metadata_<key>}}를 치환할 수 있습니다. 그렇다고 일반 메타데이터가 비밀이 되는 것은 아닙니다. 허용된 값은 별도로 모델 맥락에 포함되거나 Action 응답에 나타날 수 있습니다. 사용자 지정 메타데이터에 API 키나 비밀번호를 저장하지 마세요.

브라우저가 보낸 메타데이터는 신원이나 권한의 증거가 아닙니다. 수신 서비스가 비공개 기록 접근을 인증하고 허가해야 합니다. 브라우저의 고객 ID나 요금제 정보만으로는 충분하지 않습니다. 설정에 대해 실제 Action 요청과 에이전트 응답을 모두 테스트하세요.

메타데이터 조회

권한 범위: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

응답 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

메타데이터 설정

대화의 메타데이터를 생성하거나 수정합니다.

권한 범위: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

요청 본문

매개변수	설명
metadata 객체, 필수	저장할 키-값 메타데이터

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

응답 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---