Chat

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.

• 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.

Chat

Endpoint Chat thời gian thực gửi tin nhắn khách tới AI Agent và trả câu trả lời AI trong một lượt yêu cầu-phản hồi. Đây là endpoint dùng khi xây giao diện chat riêng trên Quickchat AI.

Nó khác endpoint khác ở hai điểm: nằm tại app.quickchat.ai/chat, ngoài đường dẫn cơ sở /v1/api/ và /v1/api_core/, và đọc scenario_id từ nội dung yêu cầu thay vì token. Nó dùng cùng xác thực Bearer token như phần còn lại của API.

Ghi chú

Gửi mọi yêu cầu tới https://app.quickchat.ai/chat. scenario_id trong nội dung phải khớp AI Agent gắn với Bearer token.

Gửi tin nhắn

POST https://app.quickchat.ai/chat

Nội dung yêu cầu

Tham số	Mô tả
scenario_id chuỗi, bắt buộc	ID AI Agent. Phải khớp scenario_id gắn với Bearer token
text chuỗi, bắt buộc	Tin nhắn đầu vào của người dùng
conv_id chuỗi	ID cuộc trò chuyện. Bỏ qua ở yêu cầu đầu để tạo mới, rồi truyền lại conv_id nhận được trong các yêu cầu tiếp theo để tiếp tục
client_metadata đối tượng	Cặp khóa-giá trị tùy chỉnh (đề xuất tối đa 5 khóa) gắn vào mỗi tin nhắn. Hiển thị thành cột dữ liệu trong bản xuất cuộc trò chuyện ở Hộp thư đến

Yêu cầu không có conv_id bắt đầu cuộc trò chuyện mới và phản hồi trả lại conv_id được tạo. Lưu conv_id rồi gửi lại trong yêu cầu sau để giữ ngữ cảnh qua nhiều tương tác.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Phản hồi 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Trường	Mô tả
conv_id chuỗi	Định danh cuộc trò chuyện. Luôn được trả về. Truyền lại trong trường conv_id của nội dung để tiếp tục cuộc trò chuyện
reply chuỗi	Câu trả lời AI Agent. Có thể chứa HTML như xuống dòng <br>
ord_number số nguyên	Số thứ tự tin nhắn trong cuộc trò chuyện
src số nguyên	Chỉ báo nguồn nội bộ. Ứng dụng API có thể bỏ qua

Để tiếp tục cuộc trò chuyện hiện có, truyền lại conv_id đã nhận:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Siêu dữ liệu phía khách

Endpoint Chat nhận tham số tùy chọn client_metadata: thuộc tính tùy chỉnh gán cho mỗi tin nhắn mới và hiển thị thành cột dữ liệu trong bản xuất cuộc trò chuyện ở Hộp thư đến. Bạn cũng có thể gắn cùng thuộc tính qua widget. Chúng tôi đề xuất gửi tối đa 5 khóa mỗi lần, ví dụ {"userId": 12, "website": "mywebsite.com"}. Đây là khuyến nghị, không phải giới hạn API cưỡng chế.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Lọc theo thẻ Cơ sở kiến thức

Bạn có thể thêm thẻ vào bài viết Cơ sở kiến thức và dùng để giới hạn những bài AI tham khảo, giúp AI chỉ trả lời từ một tập con. Hiện tính năng lọc này chỉ hỗ trợ qua API.

Để lọc theo thẻ, thêm khóa kb_topic vào client_metadata. Khóa kb_topic phải có trong mọi yêu cầu của cuộc trò chuyện, kể cả yêu cầu mở đầu. Giá trị có thể đổi giữa các yêu cầu nhưng khóa phải hiện diện suốt cuộc trò chuyện để bộ lọc có hiệu lực.

Trong ví dụ dưới, mọi bài gắn thẻ your-topic hoặc không có thẻ đều nằm trong tập kiến thức có thể dùng cho câu trả lời.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Lỗi

Endpoint Chat trả thông báo lỗi dạng văn bản thuần với mã trạng thái HTTP phù hợp.

Trạng thái	Mô tả	Cách xử lý
400	Thiếu scenario_id hoặc không cung cấp thông tin xác thực	Thêm scenario_id vào nội dung và tiêu đề hợp lệ Authorization: Bearer <API_TOKEN>
400	conv_id không hợp lệ (Conversation conv_id <id> is not valid.)	Bỏ conv_id để tạo cuộc trò chuyện mới hoặc truyền conv_id từ phản hồi trước
401	Thông tin xác thực không hợp lệ (Unauthorized.)	Kiểm tra Bearer token hoặc khóa API hợp lệ với scenario_id này
404	Không biết scenario_id (No implementation found for scenario_id <id>)	Kiểm tra scenario_id và Bearer token có gắn với nó không
500	Lỗi máy chủ nội bộ	Vấn đề phía chúng tôi. Vui lòng liên hệ bộ phận hỗ trợ
503	Dịch vụ không khả dụng	Máy chủ tạm quá tải hoặc bảo trì. Nếu vẫn xảy ra, vui lòng liên hệ bộ phận hỗ trợ