Bài viết

Bài viết là đơn vị cấu thành Cơ sở kiến thức. Tạo, liệt kê, cập nhật và xóa nội dung AI Agent dùng để trả lời.

Bài viết là đơn vị cấu thành Cơ sở kiến thức của AI Agent. Mỗi bài đại diện cho một phần kiến thức: trang trợ giúp, mục FAQ, mô tả sản phẩm hoặc bất kỳ nội dung AI cần biết.

Có ba loại: Bài viết (tài liệu đầy đủ có tiêu đề và nội dung), Đoạn văn (mục văn bản ngắn độc lập) và Bài URL (tự tạo khi nhập nội dung web). Bạn có thể tạo bài thủ công qua API, nhập từ website bằng Nhập nội dung bên ngoài, tải tệp qua Tải tệp lên hoặc đồng bộ từ Intercom.

Không có bước huấn luyện lại. Mỗi bài được tạo, cập nhật hoặc xóa đều xử lý tự động trong nền và có hiệu lực ngay khi xong, thường trong vài giây. Theo dõi qua trường embed_state bên dưới hoặc pending_embed_count trong Lấy cài đặt Cơ sở kiến thức.

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 kết quả khớp JSONPath. Kiểm tra đường dẫn gốc, trường, chỉ mục mảng và ký tự đại diện trên JSON được cung cấp. Không chạy Action hoặc lưu bộ nhớ cuộc trò chuyện.

Tạo bài viết

Phạm vi: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/articles/

Nội dung yêu cầu

Tham số	Mô tả
`content` chuỗi, bắt buộc	Nội dung bài viết
`type` chuỗi	`"Article"` (mặc định) hoặc `"Paragraph"`
`title` chuỗi	Tiêu đề bài viết

"Article": tài liệu Cơ sở kiến thức đầy đủ có tiêu đề và nội dung. Dùng cho mục FAQ, bài trợ giúp, mô tả sản phẩm.
"Paragraph": văn bản ngắn độc lập không có tiêu đề. Dùng cho thông tin ngắn, câu trả lời một dòng, dữ liệu tra cứu nhanh.
"URL" (chỉ đọc): tự tạo khi nhập nội dung từ website. Chứa nội dung trang đã thu thập cùng URL nguồn. Không thể đặt khi tạo bài.

Shell
Python

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "Our return policy allows returns within 30 days.",
  "title": "Return Policy"
}'

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "content": "Our return policy allows returns within 30 days.",
        "title": "Return Policy",
    },
)
data = response.json()

Phản hồi 201 Created

{
  "id": 1234,
  "article_id": "abc-123",
  "type": "Article",
  "title": "Return Policy",
  "description": "",
  "content": "Our return policy allows returns within 30 days.",
  "state": "draft",
  "deploy_state": "draft",
  "embed_state": "pending",
  "refresh_failure_reason": "",
  "version": null,
  "max_available_version": null,
  "url": null,
  "tags": [],
  "created_timestamp": "2026-01-15",
  "last_modified_timestamp": "2026-01-15",
  "downloaded_timestamp": "2026-01-15",
  "last_updated_timestamp": "2026-01-15",
  "last_updated_from_external_source_timestamp": null
}

Trường	Mô tả
`id` số nguyên	ID số của bài viết. Đây là định danh chính thức dùng trong mọi đường dẫn URL
`article_id` chuỗi	Định danh chuỗi cũ. Có thể rỗng; dùng `id` thay thế
`type` chuỗi	`"Article"`, `"Paragraph"` hoặc `"URL"`
`title` chuỗi	Tiêu đề bài viết
`description` chuỗi	Mô tả bài viết
`content` chuỗi	Nội dung bài viết
`deploy_state` chuỗi	`"draft"` hoặc `"published"`, chỉ là nhãn (xem lưu ý dưới)
`embed_state` chuỗi hoặc null	Bài đã có hiệu lực chưa: `"pending"`, `"embedding"`, `"embedded"` hoặc `"failed"` (xem lưu ý dưới)
`state` chuỗi	Trạng thái xử lý nội bộ (xem lưu ý dưới)
`refresh_failure_reason` chuỗi	Lý do làm mới URL gần nhất thất bại. Rỗng khi không lưu lỗi làm mới đã phân loại
`version` số nguyên hoặc null	Số phiên bản hiện tại
`max_available_version` số nguyên hoặc null	Phiên bản cao nhất có sẵn
`url` chuỗi hoặc null	URL nguồn (cho bài loại URL)
`tags` mảng chuỗi	Các thẻ liên quan
`created_timestamp` chuỗi	Ngày tạo
`last_modified_timestamp` chuỗi	Ngày chỉnh sửa gần nhất
`downloaded_timestamp` chuỗi	Ngày tải về
`last_updated_timestamp` chuỗi	Ngày cập nhật gần nhất
`last_updated_from_external_source_timestamp` chuỗi hoặc null	Lần cập nhật từ nguồn ngoài gần nhất

Bài viết có ba trường trạng thái. Chỉ một trường cho biết AI Agent có đang sử dụng bài hay không:

embed_state: trường quan trọng. "pending" và "embedding" nghĩa là vẫn xử lý; "embedded" nghĩa là đã có hiệu lực và AI Agent đang dùng; "failed" nghĩa là xử lý chưa hoàn tất và bài không được dùng. Đây là trường cần thăm dò sau khi ghi.
deploy_state: "draft" hoặc "published". Chỉ là nhãn để bạn tổ chức nội dung, không ảnh hưởng việc AI sử dụng bài.
state: trạng thái lấy nội dung nội bộ. Phần lớn người dùng API có thể bỏ qua. Với bài URL, "refresh_failed" nghĩa là lần làm mới gần nhất không thay được nội dung đã lưu.
refresh_failure_reason: nhóm lỗi ổn định cho lỗi làm mới URL đã phân loại: "http_error", "soft_404", "off_domain_redirect", "auth_wall", "error_page", "empty_content" hoặc "thin_content". Có thể rỗng nếu thu thập thất bại trước khi Quickchat phân loại trang. Nội dung lưu gần nhất vẫn có hiệu lực trừ khi embed_state cũng thất bại.

Liệt kê bài viết

Phạm vi: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/

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
`types` chuỗi	Lọc theo loại: `Article`, `Paragraph`, `URL`
`tags` chuỗi	Lọc theo thẻ
`url` chuỗi	Lọc theo URL
`title` chuỗi	Lọc theo tiêu đề
`query` chuỗi	Tìm theo nội dung

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/?limit=10&offset=0' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "offset": 0},
)
data = response.json()

Phản hồi 200 OK

{
  "items": [
    {
      "id": 1234,
      "article_id": "abc-123",
      "type": "Article",
      "title": "Return Policy",
      "description": "",
      "state": "published",
      "deploy_state": "published",
      "embed_state": "embedded",
      "refresh_failure_reason": "",
      "version": 1,
      "max_available_version": 1,
      "url": null,
      "tags": ["policies"],
      "created_timestamp": "2026-01-15",
      "last_modified_timestamp": "2026-01-15",
      "downloaded_timestamp": "2026-01-15",
      "last_updated_timestamp": "2026-01-15",
      "last_updated_from_external_source_timestamp": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 1
}

Phản hồi danh sách không có trường content. Dùng Lấy bài viết để lấy toàn bộ nội dung của bài cụ thể.

Lấy bài viết

Phạm vi: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Shell
Python

curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

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

Phản hồi 200 OK: trả về đối tượng bài viết đầy đủ (cùng cấu trúc với phản hồi Tạo bài viết), bao gồm trường content.

Cập nhật bài viết

Phạm vi: write_all

PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Nội dung yêu cầu

Tham số	Mô tả
`content` chuỗi	Nội dung đã cập nhật
`title` chuỗi	Tiêu đề đã cập nhật
`tags` mảng chuỗi	Thẻ đã cập nhật
`save_mode` chuỗi	`"draft"` (mặc định) hoặc `"publish"`

Tùy chọn save_mode: "draft" chỉ đặt cờ deploy_state, không ngăn AI dùng nội dung. Bài nháp được xử lý và dùng giống bài đã xuất bản. Đừng dựa vào nó để giữ nội dung chờ duyệt; chỉ ghi bài khi đã sẵn sàng đưa vào sử dụng.

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Updated Return Policy",
  "content": "Returns accepted within 60 days.",
  "save_mode": "publish"
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "title": "Updated Return Policy",
        "content": "Returns accepted within 60 days.",
        "save_mode": "publish",
    },
)
data = response.json()

Phản hồi 200 OK: trả về đối tượng bài viết đã cập nhật.

Xóa bài viết

Xóa một hoặc nhiều bài theo ID.

Phạm vi: write_all

DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/

Nội dung yêu cầu: mảng JSON chứa ID bài viết.

Shell
Python

curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '[1234, 5678]'

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json=[1234, 5678],
)

Phản hồi 200 OK

Tìm bài viết

Tìm trong nội dung bài bằng so khớp văn bản.

Phạm vi: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/search

Tham số truy vấn

Tham số	Mô tả
`query` chuỗi, bắt buộc	Truy vấn tìm kiếm
`is_case_insensitive` boolean	Tìm không phân biệt hoa thường (mặc định: `true`)
`with_title_url_and_tags` boolean	Tìm cả tiêu đề/URL/thẻ (mặc định: `true`)
`strict_search` boolean	Yêu cầu khớp chính xác (mặc định: `false`)
`num_of_display_articles` số nguyên	Số bài hiển thị (mặc định: `5`)
`num_of_data_articles` số nguyên	Số bài tìm kiếm (mặc định: `15`)

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/search?query=return%20policy' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/search",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"query": "return policy"},
)
data = response.json()

Phản hồi 200 OK

{
  "article_snippets": [
    {
      "article_id": 1234,
      "expository_sentence": "Our return policy allows returns within 30 days.",
      "query_words_ids": [
        {"start_char": 4, "end_char": 10, "text": "return"}
      ]
    }
  ],
  "article_snapshots": {
    "items": [],
    "offset": 0,
    "count": 1
  }
}

Liệt kê đoạn văn

Liệt kê tất cả bài loại Paragraph. Đoạn văn là mục văn bản ngắn độc lập không có tiêu đề, khác với Article đầy đủ có cả tiêu đề và nội dung.

Phạm vi: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs

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
`query` chuỗi	Lọc theo nội dung

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs?limit=10' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10},
)
data = response.json()

Phản hồi 200 OK

{
  "items": [
    {
      "id": 1,
      "content": "Our return policy allows returns within 30 days."
    }
  ],
  "offset": 0,
  "count": 1
}

Bài viết

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

Tạo bài viết

Liệt kê bài viết

Lấy bài viết

Cập nhật bài viết

Xóa bài viết

Tìm bài viết

Liệt kê đoạn văn

Bắt đầu

AI Agent

Actions

Hội thoại

Channels

Trang web của bạn

Helpdesk & CRM

Ứng dụng nhắn tin

Tài khoản và thanh toán

Bắt đầu

Cấu hình

Knowledge Base

Hội thoại