Cấu hình chuyển giao

Chuyển giao cho người phụ trách cho phép AI Agent tự động chuyển cuộc trò chuyện tới nhân viên khi phát hiện tình huống cần hỗ trợ trực tiếp. AI điều khiển việc chuyển giao: AI liên tục đánh giá cuộc trò chuyện theo hướng dẫn có thể cấu hình và kích hoạt chuyển giao khi phù hợp, không cần can thiệp thủ công.

Cách chuyển giao tự động hoạt động:

1. Trong cuộc trò chuyện, AI đánh giá từng tin nhắn theo hướng dẫn chung (ví dụ khách bực bội, thiếu kiến thức) và hướng dẫn tùy chỉnh bạn định nghĩa
2. Khi một hướng dẫn được kích hoạt, AI hiển thị thông báo hỏi khách có muốn nói chuyện với nhân viên không
3. Nếu khách xác nhận, cuộc trò chuyện được chuyển tới nhân viên, tùy chọn kèm bản tóm tắt do AI tạo về nội dung trước đó
4. Nếu đã cấu hình giờ làm việc và yêu cầu nằm ngoài giờ, một thông báo tùy chỉnh được hiển thị thay thế

Các cách chuyển giao khác:

• Kích hoạt bằng từ khóa: khách có thể gõ cụm từ cụ thể (ví dụ “nói chuyện với nhân viên”, “tư vấn viên”) để yêu cầu chuyển trực tiếp
• Chuyển giao thủ công từ bảng điều khiển: nhân viên có thể tiếp quản bất kỳ cuộc trò chuyện nào trong Hộp thư đến bằng cách thay đổi người được giao

Định tuyến theo chủ đề cho phép AI giao cuộc trò chuyện cho một đồng nghiệp dựa trên mô tả định tuyến của người đó. Mỗi hồ sơ thuộc một người dùng, tách biệt với danh mục chủ đề trong Thông tin chuyên sâu. Cấu hình hồ sơ qua routing_profiles trong yêu cầu PUT. Người được giao và người nhận email thông báo là hai cài đặt riêng.

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

• Xem trước yêu cầu API Action. Hiển thị mẫu yêu cầu được cung cấp bằng giá trị mẫu tổng hợp mà không gửi đi. Bỏ qua tiêu đề chứa thông tin xác thực.

• Xác thực bộ dữ liệu kiểm thử. Kiểm tra bộ dữ liệu nhỏ được cung cấp theo định dạng hỗ trợ mà không chạy AI Agent.

Lấy cấu hình chuyển giao

Phạm vi: read_all

GET https://app.quickchat.ai/v1/api/human_handoff/configuration

Shell

curl https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Phản hồi 200 OK

Phản hồi chứa một số đối tượng lồng nhau:

settings: cấu hình chuyển giao chính:

Trường	Mô tả
is_active boolean	Có bật chuyển giao cho nhân viên hay không
keywords mảng chuỗi	Từ khóa kích hoạt chuyển giao (ví dụ ["speak to human", "agent"])
ai_summary_active boolean	Gửi tóm tắt cuộc trò chuyện do AI tạo cho nhân viên khi chuyển giao
topic_based_routing_active boolean	Có bật định tuyến theo chủ đề tới nhân viên cụ thể hay không (chỉ đọc, cấu hình qua hồ sơ định tuyến)
question_message chuỗi	Tin nhắn hỏi khách có muốn kết nối với nhân viên không
confirmation_message chuỗi	Tin nhắn sau khi khách xác nhận chuyển giao (tối đa 500 ký tự)
confirmation_outside_working_hours_message chuỗi	Tin nhắn khi yêu cầu chuyển giao ngoài giờ làm việc (tối đa 500 ký tự)
working_hours_active boolean	Chỉ cho phép chuyển giao trong giờ làm việc
timezone chuỗi	Múi giờ làm việc (ví dụ "Europe/London")
send_email_notification boolean	Gửi email thông báo cho nhân viên khi chuyển giao
emails mảng chuỗi	Địa chỉ email nhận thông báo

availability: lịch làm việc (mảng khung giờ):

Trường	Mô tả
id số nguyên	ID khung giờ
day_span chuỗi	Ngày hoặc khoảng ngày (ví dụ "monday", "monday-friday")
start_time chuỗi	Giờ bắt đầu theo định dạng "HH:MM"
end_time chuỗi	Giờ kết thúc theo định dạng "HH:MM"

generic_guidelines: quy tắc kích hoạt chuyển giao định sẵn (mảng):

Trường	Mô tả
name chuỗi	Loại hướng dẫn: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description chuỗi	Mô tả khi nào hướng dẫn kích hoạt
is_active boolean	Có bật hướng dẫn này không

custom_guidelines: quy tắc kích hoạt chuyển giao do người dùng định nghĩa (mảng):

Trường	Mô tả
id số nguyên	ID hướng dẫn
name chuỗi	Tên hướng dẫn tùy chỉnh (tối đa 100 ký tự)
description chuỗi	Khi nào hướng dẫn này cần kích hoạt chuyển giao (tối đa 2.000 ký tự)
is_active boolean	Có bật hướng dẫn này không

routing_profiles: định tuyến theo chủ đề chuyển cuộc trò chuyện tới đúng nhân viên dựa trên nội dung trao đổi.

Khi AI bắt đầu chuyển giao, nó có thể chọn một đồng nghiệp từ các hồ sơ định tuyến đang bật. Cuộc trò chuyện được giao cho người đó nếu lựa chọn hợp lệ; nếu không sẽ chưa được giao. Các cách kích hoạt chuyển giao khác cũng có thể để cuộc trò chuyện chưa được giao. Email thông báo dùng settings.send_email_notification và settings.emails, độc lập với lựa chọn định tuyến.

Ví dụ: đặt mô tả “Câu hỏi thanh toán và hóa đơn” cho nhân viên tài chính và “Hỗ trợ kỹ thuật” cho kỹ sư. Với câu hỏi hóa đơn, AI có thể giao cho nhân viên tài chính. Danh sách email nhận thông báo không thay đổi theo việc giao này.

Cấu hình hồ sơ tại Actions và MCPs > Chuyển giao cho người phụ trách > Chỉnh sửa Action > Định tuyến theo chủ đề, hoặc qua yêu cầu PUT.

Trường	Mô tả
user_id số nguyên	ID người dùng của đồng nghiệp; người đó phải có quyền truy cập AI Agent này
routing_description chuỗi	Những cuộc trò chuyện đồng nghiệp nên xử lý (tối đa 150 ký tự; không được rỗng khi bật)
is_active boolean	Có bật hồ sơ định tuyến này không
email, first_name, last_name chuỗi	Thông tin người dùng do GET trả về; không bắt buộc trong PUT

Cập nhật cấu hình chuyển giao

Phạm vi: write_all

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

Chú ý

PUT thay toàn bộ cấu hình chuyển giao một cách nguyên tử. Bao gồm settings, availability, generic_guidelines và custom_guidelines. Thêm routing_profiles để giữ định tuyến: nếu bỏ qua, mặc định là danh sách rỗng và xóa hồ sơ hiện có. Để sửa từng phần, trước hết GET cấu hình hiện tại, sửa trường cần thiết rồi PUT lại toàn bộ đối tượng. Mỗi hồ sơ dùng user_id, routing_description và is_active.

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

Phản hồi 200 OK: trả về cấu hình chuyển giao đã cập nhật.

---