Tổng quan

Quickchat AI cung cấp REST API để truy cập cấu hình AI Agent, Cơ sở kiến thức, Cuộc trò chuyện, AI Actions và nhiều tính năng khác bằng lập trình.

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

• So sánh cách triển khai. Đối chiếu kênh, quyền truy cập website và tính năng bạn khai báo cần với các lựa chọn thiết lập Quickchat AI. Không kiểm tra website hoặc tài khoản của bạn.

• Kiểm tra kết nối MCP mẫu. Chỉ khởi tạo và liệt kê công cụ tại endpoint tài liệu Cloudflare hoặc Microsoft Learn. Không đăng nhập hoặc thực thi công cụ.

Xác thực

Mọi endpoint API dùng xác thực Bearer token. Đưa token API vào tiêu đề Authorization của mỗi yêu cầu:

Authorization: Bearer <API_TOKEN>

Token được tạo trong bảng điều khiển Quickchat tại Ứng dụng bên ngoài > API. Mỗi token là JWT chứa scenario_id, nên không cần tiêu đề định danh bổ sung.

• Hiệu lực token: 52 tuần kể từ khi tạo
• Có thể thu hồi token bất cứ lúc nào trong bảng điều khiển
• Mỗi token chỉ dành cho một AI Agent (scenario)
• Tạo token yêu cầu gói Business trở lên; trên gói thấp hơn, tùy chọn bị vô hiệu hóa và endpoint trả về 402 Payment Required

Ghi chú

Endpoint Chat thời gian thực (POST https://app.quickchat.ai/chat) nhận cùng Bearer token như phần còn lại của API, nhưng nằm ngoài đường dẫn cơ sở /v1/api/ và yêu cầu scenario_id trong nội dung yêu cầu. Xem trang Chat để biết đầy đủ.

Phạm vi token

Token API được tạo với một trong hai phạm vi:

Phạm vi	Mức truy cập	Mô tả
read_all	Chỉ đọc	Đọc mọi tài nguyên nhưng không tạo, cập nhật hay xóa
write_all	Đọc và ghi	Toàn quyền với mọi endpoint, gồm thao tác ghi

• Token được gán phạm vi khi tạo trong bảng điều khiển tại Ứng dụng bên ngoài > API
• Phạm vi write_all tự bao gồm mọi quyền read_all
• Dùng token read_all trên endpoint ghi trả về 403 với "Insufficient token scope. Required: write_all"

Mẹo

Dùng token read_all cho giám sát, phân tích và tích hợp chỉ đọc. Chỉ dùng write_all khi tích hợp cần tạo hoặc sửa tài nguyên.

Phạm vi yêu cầu theo nhóm endpoint:

Nhóm endpoint	Thao tác đọc	Thao tác ghi
Cài đặt chatbot	read_all	write_all
Cài đặt Cơ sở kiến thức	read_all	write_all
Bài viết	read_all	write_all
URL ngôn ngữ của bài viết	read_all	write_all
Thẻ	read_all	Không có
Tải tệp lên	Không có	write_all
Nhập nội dung bên ngoài	Không có	write_all
Cơ sở kiến thức Intercom	read_all	write_all
Cấu hình Widget	read_all	write_all
Cuộc trò chuyện	read_all	Không có
Siêu dữ liệu cuộc trò chuyện	read_all	write_all
Cấu hình chuyển giao	read_all	write_all
Đánh giá cuộc trò chuyện	read_all	write_all
AI Actions	read_all	write_all

URL cơ sở

Nhóm endpoint	URL cơ sở
Cơ sở kiến thức, AI Actions, Tải tệp lên, Nhập, Cài đặt chatbot, Widget, Chuyển giao, Đánh giá cuộc trò chuyện	https://app.quickchat.ai/v1/api/
Cuộc trò chuyện	https://app.quickchat.ai/v1/api_core/
Chat thời gian thực	https://app.quickchat.ai/chat

Giới hạn tốc độ

Giới hạn tốc độ áp dụng theo token và endpoint.

Nhóm	Giới hạn	Áp dụng cho
READ	120 yêu cầu/phút	GET và thao tác liệt kê
WRITE	60 yêu cầu/phút	POST, PATCH, PUT, DELETE
HEAVY	20 yêu cầu/phút	Tải tệp, nhập, thu thập web

Khi vượt giới hạn, API trả về HTTP 429 Too Many Requests.

Webhook

Quickchat AI không gửi webhook ra ngoài. Không có cách đăng ký sự kiện để chúng tôi POST tới endpoint của bạn khi có tin nhắn, chuyển giao hoặc đóng cuộc trò chuyện.

Các lựa chọn thay thế phục vụ mục đích khác nhau:

• AI Actions gọi API của bạn trong cuộc trò chuyện. API Actions có chế độ AI quyết định, Trước phản hồi đầu tiên và Khi metadata khớp. Chế độ tự động thử gọi một lần mỗi cuộc trò chuyện theo điều kiện đã mô tả; không phải đăng ký mọi tin nhắn hay lần chuyển giao. Dùng cho việc ghi nhận khách tiềm năng hoặc thông báo hệ thống khi đủ dữ liệu.
• Google Sheets thêm một hàng khi Action chạy. Không tự ghi mọi tin nhắn hoặc lần chuyển giao.
• Thăm dò Conversations API lấy cuộc trò chuyện đã lưu và sự kiện, gồm tin nhắn và dấu chuyển giao được ghi nhận. Tuân theo phân trang và giới hạn READ ở trên. Thăm dò gây độ trễ; so sánh trạng thái giữa các lần có thể bỏ lỡ thay đổi trung gian. Không nên giả định đây là lịch sử đầy đủ của mọi chuyển giao hoặc thay đổi người phụ trách.

Truy cập API yêu cầu gói Business; xem Gói và giới hạn.

Phân trang

Endpoint danh sách hỗ trợ phân trang bằng tham số truy vấn:

Tham số	Mô tả
limit số nguyên	Số mục mỗi trang
offset số nguyên	Số mục bỏ qua

Phản hồi phân trang có cấu trúc sau:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Xử lý lỗi

Mọi lỗi được trả dưới dạng JSON theo định dạng sau:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Trạng thái	Mã	Mô tả
400	BAD_REQUEST	Đầu vào không hợp lệ hoặc thiếu trường bắt buộc
401	PERMISSION_DENIED	Token không hợp lệ, hết hạn hoặc bị thu hồi
402	PAYMENT_REQUIRED	Cần gói đăng ký đang hoạt động
403	PERMISSION_DENIED	Token thiếu phạm vi cần thiết cho thao tác
404	NOT_FOUND	Không tìm thấy tài nguyên
409	CONFLICT	Thao tác xung đột (ví dụ chỉnh sửa đồng thời)
422	VALIDATION_ERROR	Nội dung yêu cầu không vượt qua xác thực schema
429	TOO_MANY_REQUESTS	Vượt giới hạn tốc độ
500	UNKNOWN	Lỗi máy chủ nội bộ
503	SERVICE_UNAVAILABLE	Tạm thời không khả dụng

---