Siêu dữ liệu cuộc trò chuyện

Siêu dữ liệu cuộc trò chuyện cho phép gắn dữ liệu khóa-giá trị tùy chỉnh vào cuộc trò chuyện, tạo cầu nối giữa hệ thống của bạn và AI Agent. Siêu dữ liệu đi xuyên suốt quy trình Quickchat:

• Đưa vào qua API: dùng các endpoint này để gắn siêu dữ liệu vào bất kỳ cuộc trò chuyện bằng lập trình (ví dụ từ CRM, bộ phận hỗ trợ hoặc backend)
• Đưa vào qua widget/nhúng: truyền siêu dữ liệu làm tham số khởi tạo khi tải widget hoặc chèn động trong cuộc trò chuyện đang hoạt động bằng JavaScript SDK
• Hiển thị trong bảng điều khiển: siêu dữ liệu tùy chỉnh xuất hiện trong chi tiết cuộc trò chuyện ở Hộp thư đến. Khóa nội bộ được lọc bỏ; thông tin liên hệ đã thu thập và bộ nhớ Action có cách hiển thị riêng
• Có trong bản xuất: siêu dữ liệu được kèm theo khi xuất cuộc trò chuyện từ bảng điều khiển, phục vụ phân tích ngoại tuyến
• Dùng trong AI Actions: giá trị siêu dữ liệu có thể chèn trực tiếp bằng placeholder {{metadata_<key>}} vào AI Actions. Xem Biến AI Action để biết đầy đủ placeholder khả dụng
• AI Agent có thể dùng khi được phép: ngữ cảnh mô hình dùng một tập con siêu dữ liệu đã lọc. Lưu một khóa không bảo đảm mô hình nhận hoặc nhắc tới nó

Dùng siêu dữ liệu cho tham chiếu khách hàng, ngữ cảnh tài khoản, phân tích và đầu vào Action. Lưu trữ, hiển thị Hộp thư đến, thay thế Action và ngữ cảnh mô hình là các cách dùng riêng của cùng dữ liệu.

Siêu dữ liệu được xác thực theo JSON schema nếu đã cấu hình trong bảng điều khiển.

Kiểm tra ví dụ tùy chọn

• Xem trước khóa siêu dữ liệu. Kiểm tra tên trường được cung cấp trở thành khóa biến thế nào, gồm tên trùng và lỗi khóa dành riêng. Không kiểm tra giá trị hoặc quyền riêng theo tài khoản.

• Kiểm tra điều kiện chạy Action. Đánh giá điều kiện dựa trên siêu dữ liệu mẫu được cung cấp mà không chạy Action.

Trong trình duyệt tương thích, các phép kiểm tra này cũng có sẵn dưới dạng công cụ website. Liên kết mở biểu mẫu tiêu chuẩn.

Ngữ cảnh mô hình và phân quyền

Trên các kênh do khách kiểm soát như Widget website và Nhúng, ngữ cảnh mô hình nhận các khóa liên hệ (visitor_name, visitor_email, visitor_phone_number) và khóa đủ điều kiện được Actions đang hoạt động tham chiếu hoặc thu thập. Giá trị nội bộ và dành riêng bị lọc; giới hạn cấu hình và kích thước cũng áp dụng. Các tích hợp khác có quy tắc ngữ cảnh riêng theo kênh. Khóa tùy chỉnh customer_tier hoặc customer_id không tự hiển thị với mô hình chỉ vì bạn đã gửi.

Action có thể thay {{metadata_<key>}} khi tạo yêu cầu mà không cần AI sinh giá trị đó. Điều này không làm siêu dữ liệu thông thường thành bí mật: giá trị đủ điều kiện có thể đi vào ngữ cảnh mô hình riêng hoặc xuất hiện trong phản hồi Action. Không lưu khóa API hay mật khẩu trong siêu dữ liệu tùy chỉnh.

Siêu dữ liệu do trình duyệt gửi không chứng minh danh tính hoặc quyền. Dịch vụ nhận phải xác thực và phân quyền truy cập bản ghi riêng tư; ID khách hàng hoặc cấp gói do trình duyệt gửi là không đủ. Hãy kiểm thử cả yêu cầu Action tạo ra lẫn câu trả lời Agent với cấu hình của bạn.

Lấy siêu dữ liệu

Phạm vi: 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()

Phản hồi 200 OK

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

Đặt siêu dữ liệu

Tạo hoặc cập nhật siêu dữ liệu cho cuộc trò chuyện.

Phạm vi: write_all

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

Nội dung yêu cầu

Tham số	Mô tả
metadata đối tượng, bắt buộc	Siêu dữ liệu khóa-giá trị cần lưu

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()

Phản hồi 200 OK

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

---