API Câu hỏi thường gặp (FAQs) #

FAQs là các mục hỏi đáp mà bot AI của bạn sử dụng khi trả lời khách hàng. Mỗi FAQ thuộc về tài khoản của bạn và có thể được liên kết với một hoặc nhiều chiến dịch, nhờ đó cùng một câu trả lời có thể được tái sử dụng ở bất cứ nơi nào phù hợp. API FAQs cho phép bạn quản lý thư viện đó theo lập trình — tạo, cập nhật, nhập hàng loạt, sắp xếp lại và liên kết các FAQ với các chiến dịch từ mã nguồn của riêng bạn.

Tất cả các endpoint bên dưới đều tương đối so với URL cơ sở https://api.youraiconnector.com/v1. Mọi yêu cầu đều phải được xác thực — xem Truy cập API và Xác thực. Truy cập API là một tính năng trả phí; nếu không có quyền truy cập, các yêu cầu sẽ bị từ chối với mã 403.

Cách bot sử dụng FAQ: Khi bạn tạo hoặc thay đổi một FAQ, nền tảng sẽ chuẩn bị dữ liệu tìm kiếm của nó (được sử dụng để khớp FAQ với các câu hỏi đến) trong nền. Quá trình này thường hoàn tất trong vài giây, sau đó bot sẽ tự động bắt đầu sử dụng mục này.

Đối tượng FAQ #

Mỗi FAQ trả về từ API có cấu trúc như sau:

Các trường bạn có thể thiết lập là: question, answer, is_active, is_global, category, tags, và order_index. Nền tảng quản lý mọi thứ khác (dữ liệu tìm kiếm, số lần sử dụng, dấu thời gian); bất kỳ trường nào khác trong phần thân yêu cầu của bạn đều sẽ bị bỏ qua.

Liệt kê các FAQ #

GET /faqs

Trả về các FAQ trong tài khoản của bạn, hiển thị mục mới nhất trước. Tùy chọn lọc theo một chiến dịch duy nhất hoặc theo trạng thái hoạt động.

Các tham số truy vấn

cURL

curl "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.faqs, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs",
    params={"campaign_id": "campaign123", "limit": 50},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["faqs"], data["next_cursor"])

Phản hồi

{
  "success": true,
  "faqs": [
    {
      "id": "aBcD1234eFgH5678",
      "question": "How long does shipping take?",
      "answer": "Standard shipping takes 3-5 business days.",
      "category": "shipping",
      "tags": ["logistics", "delivery"],
      "is_active": true,
      "is_global": false,
      "usage_count": 12,
      "order_index": 0,
      "campaign_ids": ["campaign123"],
      "created_at": "2026-01-01T12:00:00.000Z",
      "updated_at": "2026-01-02T08:30:00.000Z"
    }
  ],
  "next_cursor": "aBcD1234eFgH5678"
}

Khi next_cursor là null, sẽ không còn kết quả nào nữa.

Lấy một FAQ #

GET /faqs/{faqId}

Trả về một FAQ duy nhất theo ID của nó.

cURL

curl "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { faq } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
faq = res.json()["faq"]

Phản hồi

{
  "success": true,
  "faq": {
    "id": "aBcD1234eFgH5678",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"],
    "is_active": true,
    "is_global": false,
    "usage_count": 12,
    "order_index": 0,
    "campaign_ids": ["campaign123"],
    "created_at": "2026-01-01T12:00:00.000Z",
    "updated_at": "2026-01-02T08:30:00.000Z"
  }
}

Tạo một FAQ #

POST /faqs

Tạo một FAQ mới và liên kết nó với một chiến dịch.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    question: "How long does shipping take?",
    answer: "Standard shipping takes 3-5 business days.",
    category: "shipping",
    tags: ["logistics"],
  }),
});
const { faq_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "tags": ["logistics"],
    },
)
faq_id = res.json()["faq_id"]

Phản hồi

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

Cập nhật FAQ #

PUT /faqs/{faqId}

Cập nhật một phần FAQ. Chỉ các trường có thể ghi được cung cấp mới bị thay đổi; mọi thứ khác vẫn giữ nguyên giá trị hiện tại. Việc thay đổi question hoặc answer sẽ tự động làm mới dữ liệu tìm kiếm của FAQ trong nền.

Nếu bạn gửi question hoặc answer, chúng phải là các chuỗi không trống. Việc không gửi các trường có thể ghi được nhận dạng nào sẽ trả về 400.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ is_active: false }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_active": False},
)
data = res.json()

Phản hồi

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

Xóa FAQ #

DELETE /faqs/{faqId}

Xóa vĩnh viễn một FAQ. Tùy chọn truyền campaign_id dưới dạng tham số truy vấn để cũng xóa FAQ đó khỏi danh sách FAQ của chiến dịch đó.

Các tham số truy vấn

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    params={"campaign_id": "campaign123"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true
}

Xóa hàng loạt FAQ #

POST /faqs/bulk-delete

Xóa tối đa 500 FAQ trong một yêu cầu duy nhất. Khi campaign_id được cung cấp, các FAQ đã xóa cũng sẽ bị loại bỏ khỏi danh sách FAQ của chiến dịch đó.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/bulk-delete", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    faq_ids: ["faqId1", "faqId2"],
    campaign_id: "campaign123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/bulk-delete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "deleted_count": 2
}

Câu hỏi thường gặp về Nhập dữ liệu #

POST /faqs/import

Nhập hàng loạt tối đa 500 câu hỏi thường gặp (FAQ) và liên kết tất cả chúng với một chiến dịch. Các mục có question khớp với FAQ hiện có trong thư viện của bạn (không phân biệt chữ hoa chữ thường) sẽ cập nhật FAQ đó thay vì tạo bản sao trùng lặp.

Mẹo hiệu suất: Việc khớp dữ liệu trùng lặp sẽ quét toàn bộ thư viện FAQ của bạn, vì vậy các thư viện rất lớn sẽ làm chậm quá trình nhập. Hãy ưu tiên nhập ít lần với số lượng lớn thay vì nhập nhiều lần với số lượng nhỏ.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "faqs": [
      { "question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide." },
      { "question": "What is your return policy?", "answer": "You can return any item within 30 days." }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    faqs: [
      {
        question: "Do you ship internationally?",
        answer: "Yes, we ship to most countries worldwide.",
      },
      {
        question: "What is your return policy?",
        answer: "You can return any item within 30 days.",
      },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "faqs": [
            {"question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide."},
            {"question": "What is your return policy?", "answer": "You can return any item within 30 days."},
        ],
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "faq_ids": ["aBcD1234eFgH5678", "iJkL9012mNoP3456"],
  "imported_count": 2
}

faq_ids là các ID FAQ đã được tạo hoặc cập nhật, theo thứ tự bạn đã cung cấp.

Sắp xếp lại FAQ #

POST /faqs/reorder

Thiết lập thứ tự hiển thị các FAQ của một chiến dịch. Hãy cung cấp danh sách đầy đủ các ID FAQ theo thứ tự mong muốn; vị trí của mỗi FAQ sẽ được cập nhật để khớp với vị trí của nó trong mảng.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/reorder", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    ordered_faq_ids: ["faqId2", "faqId1", "faqId3"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"],
    },
)
data = res.json()

Phản hồi

{
  "success": true
}

Nếu chiến dịch hoặc bất kỳ ID FAQ nào không được tìm thấy trong tài khoản của bạn, yêu cầu sẽ trả về 404 One or more FAQs were not found.

Liên kết FAQ với một chiến dịch #

POST /faqs/{faqId}/link

Liên kết một FAQ hiện có với một chiến dịch bổ sung. Một FAQ có thể được chia sẻ bởi bất kỳ số lượng chiến dịch nào, vì vậy cùng một câu trả lời chỉ cần được duy trì một lần.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

Hủy liên kết FAQ khỏi chiến dịch #

POST /faqs/{faqId}/unlink

Xóa FAQ khỏi một chiến dịch mà không xóa chính FAQ đó. FAQ vẫn nằm trong thư viện của bạn và vẫn được liên kết với các chiến dịch khác.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

Xây dựng lại dữ liệu tìm kiếm của FAQ #

POST /faqs/{faqId}/rebuild-embeddings

Xếp hàng chờ xây dựng lại dữ liệu mà bot AI sử dụng để tìm FAQ này (dữ liệu tìm kiếm theo ngữ nghĩa và từ khóa). Việc này hữu ích nếu FAQ không được chọn trong các câu trả lời như mong đợi. Quá trình xây dựng lại chạy trong nền và thường hoàn tất trong vài giây; FAQ có thể tạm thời bị loại khỏi các câu trả lời của AI trong khi đang được xây dựng lại.

Điểm cuối này trả về 202 Accepted vì công việc vẫn tiếp tục sau khi phản hồi được gửi đi. status luôn là "processing" — hãy tìm nạp lại FAQ sau nếu bạn cần xác nhận việc hoàn tất.

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "status": "processing"
}

Quản lý FAQ có hỗ trợ AI #

Các điểm cuối dưới đây vượt xa các thao tác CRUD thông thường: chúng gọi cùng các công cụ hỗ trợ AI mà trình chỉnh sửa FAQ trên bảng điều khiển sử dụng — tìm các mục trùng lặp, tạo các mục từ tài liệu và khớp FAQ với các tác vụ thiếu hụt kiến thức mở. Phần thân yêu cầu (request bodies) trong tập hợp này sử dụng các tên trường camelCase (campaignId, taskId, sourceIds…), khớp với các hình dạng yêu cầu của chính ứng dụng, thay vì snake_case được sử dụng ở nơi khác trên trang này — hãy sao chép các ví dụ bên dưới thay vì đoán tên trường.

Tạo bản sao FAQ dành riêng cho chiến dịch #

POST /faqs/{faqId}/fork-for-campaign

Tạo một FAQ mới là bản sao của một FAQ hiện có, được giới hạn trong một chiến dịch duy nhất và liên kết lại chiến dịch đó với bản sao mới thay vì bản gốc. Sử dụng tính năng này khi bạn muốn tùy chỉnh câu trả lời cho một chiến dịch mà không làm thay đổi nó ở mọi nơi khác mà FAQ gốc được sử dụng. FAQ gốc vẫn được giữ nguyên — nó chỉ mất liên kết với chiến dịch này.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign456",
    "question": "How long does shipping take to the EU?",
    "answer": "For EU orders, shipping takes 7-10 business days."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      campaign_id: "campaign456",
      question: "How long does shipping take to the EU?",
      answer: "For EU orders, shipping takes 7-10 business days.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign456",
        "question": "How long does shipping take to the EU?",
        "answer": "For EU orders, shipping takes 7-10 business days.",
    },
)
data = res.json()

Phản hồi — 201 Created

{
  "success": true,
  "faq_id": "nEwFaQiD9012mNoP",
  "campaign_id": "campaign456",
  "original_faq_id": "aBcD1234eFgH5678"
}

Tìm các FAQ gần như trùng lặp #

POST /faqs/dedupe

Bắt đầu một tác vụ chạy ngầm để quét thư viện FAQ của bạn nhằm tìm các mục gần như trùng lặp hoặc chồng chéo và hợp nhất hoặc xóa chúng khi hệ thống tự tin. Hữu ích sau khi nhập dữ liệu hàng loạt hoặc sau vài vòng tạo FAQ bằng AI khiến thư viện bị chồng chéo. Mỗi tài khoản chỉ có thể chạy một tác vụ khử trùng lặp tại một thời điểm — bắt đầu tác vụ thứ hai khi tác vụ đầu tiên vẫn đang chạy sẽ trả về 409.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={},
)
data = res.json()

Phản hồi — 202 Accepted

{
  "success": true,
  "job_id": "dedupJob_aBc123"
}

Tác vụ chạy trong nền và thường mất vài phút đối với thư viện lớn. Không có điểm cuối trạng thái riêng biệt — hãy tìm nạp lại GET /faqs sau một thời gian ngắn chờ đợi để xem những gì đã thay đổi. Khi bạn xem xong kết quả, hãy gọi điểm cuối loại bỏ (dismiss) bên dưới để xóa nó.

Loại bỏ kết quả kiểm tra trùng lặp #

POST /faqs/dedupe/dismiss

Xóa công việc chống trùng lặp đã hoàn tất để nó không còn hiển thị dưới dạng kết quả đang hoạt động. Idempotent (có tính lũy đẳng) — an toàn để gọi ngay cả khi không có gì cần loại bỏ. Trả về 409 nếu công việc vẫn đang queued hoặc processing (bạn không thể loại bỏ một lần chạy chưa hoàn tất).

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe/dismiss", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{ "success": true }

Tạo câu hỏi thường gặp (FAQ) từ các tài liệu đã tải lên #

POST /faqs/generate-from-documents

Đọc một hoặc nhiều tài liệu đã có trong kho lưu trữ tệp của tài khoản của bạn và yêu cầu AI soạn thảo các câu hỏi thường gặp từ nội dung của chúng, kiểm tra các bản nháp so với thư viện hiện có của bạn để tái sử dụng hoặc cập nhật các mục thay vì tạo ra các bản sao trùng lặp. Kết quả không được ghi lại ngay lập tức — chúng được lưu trữ dưới dạng tập hợp thay đổi đang chờ xử lý trên chiến dịch để bạn xem xét, sau đó được áp dụng (hoặc loại bỏ) bằng Áp dụng các thay đổi FAQ đã xem xét bên dưới. Việc này tốn tín dụng vì đây là lượt tạo nội dung bằng AI dựa trên văn bản tài liệu.

Điểm cuối này không chứa tệp: storagePath phải trỏ đến một tệp đã nằm trong thư mục tải lên của riêng bạn (users/{your user id}/uploads/), theo cùng quy ước như Nhập tài liệu đã tải lên trên API Cơ sở Kiến thức.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/generate-from-documents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "uploadedFiles": [
      { "storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/generate-from-documents", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    uploadedFiles: [
      { storagePath: "users/abc123uid/uploads/handbook.pdf", fileName: "handbook.pdf", mimeType: "application/pdf" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/generate-from-documents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "uploadedFiles": [
            {"storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf"},
        ],
    },
)
data = res.json()

Phản hồi — 202 Accepted

{
  "success": true,
  "faqCount": 6,
  "reusedCount": 2,
  "modifiedCount": 1,
  "newCount": 3
}

faqCount là tổng số thay đổi được đề xuất đang chờ xem xét; reusedCount, modifiedCount và newCount phân tách số đó thành các FAQ khớp với một mục hiện có mà không thay đổi, các mục mà AI đề xuất chỉnh sửa và các mục hoàn toàn mới. Các tệp đã tải lên sẽ bị xóa khỏi bộ lưu trữ sau khi quá trình xử lý kết thúc, bất kể thành công hay không.

Áp dụng các thay đổi FAQ đã xem xét #

POST /faqs/apply-optimization

Áp dụng (hoặc loại bỏ) một tập hợp các thay đổi FAQ do AI đề xuất đang chờ xử lý — loại thay đổi được tạo bởi Tạo FAQ từ tài liệu ở trên, hoặc bởi đánh giá tối ưu hóa FAQ của bảng điều khiển. Bạn chọn chính xác những thay đổi đề xuất nào để chấp nhận; bất kỳ thay đổi nào bạn không đề cập đến sẽ được giữ nguyên (một thay đổi bị bỏ qua không bao giờ được coi là sự từ chối dẫn đến việc xóa nội dung).

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/apply-optimization?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "acceptedChanges": [
      { "action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days." },
      { "action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/apply-optimization", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    acceptedChanges: [
      { action: "create_new", question: "Do you ship to the EU?", answer: "Yes, EU shipping takes 7-10 business days." },
      { action: "remove", faq_ref_path: "users/abc123uid/faqs/oldFaqId" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/apply-optimization",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "acceptedChanges": [
            {"action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days."},
            {"action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId"},
        ],
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "message": "Applied 2 FAQ changes",
  "faq_count": 7
}

faq_count là tổng số FAQ được liên kết của chiến dịch (hoặc Tác nhân) sau khi áp dụng. Nếu không có tập hợp thay đổi nào đang chờ xử lý để áp dụng, phản hồi sẽ là { "success": true, "message": "No pending FAQ changes to apply" }.

Tìm các FAQ tương tự với một tác vụ #

POST /faqs/similar-for-task

Xếp hạng thư viện FAQ của bạn theo mức độ liên quan đến câu hỏi của tác vụ thiếu hụt kiến thức — đây cũng là cơ chế tra cứu đằng sau bộ chọn “Sử dụng FAQ hiện có” trên bảng điều khiển. Chỉ đọc. taskId phải trỏ đến một tác vụ thuộc loại faq_update.

Điểm cuối này luôn trả về 200, ngay cả khi xảy ra lỗi dự kiến như tác vụ không xác định — hãy kiểm tra success trong phần nội dung thay vì trạng thái HTTP.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/similar-for-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "limit": 10 }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/similar-for-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", limit: 10 }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/similar-for-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "limit": 10},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": {
    "task_id": "task789",
    "matches": [
      {
        "faq_id": "aBcD1234eFgH5678",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "created_at": "2026-01-01T12:00:00.000Z",
        "similarity": 0.81,
        "embedding_similarity": 0.81,
        "keyword_similarity": 0.6,
        "bm25_score": 4.2,
        "distance": 0.19
      }
    ]
  }
}

Các kết quả khớp được sắp xếp theo similarity (khớp ngữ nghĩa khi có sẵn, nếu không thì dựa trên sự trùng lặp từ khóa), kết quả tốt nhất đứng đầu. Khi xảy ra lỗi nhẹ, định dạng phản hồi là { "success": false, "error": "...", "error_code": 404 } — error_code phản ánh trạng thái HTTP thông thường.

Giải quyết tác vụ bằng FAQ hiện có #

POST /faqs/resolve-task

Giải quyết tác vụ thiếu hụt kiến thức bằng cách liên kết nó với một FAQ bạn đã có (thay vì viết mới), gửi câu trả lời của FAQ đó cho liên hệ đã kích hoạt tác vụ thiếu hụt, và đánh dấu tác vụ là hoàn tất. Hãy sử dụng tính năng này sau khi Tìm các FAQ tương tự với tác vụ tìm thấy một FAQ hiện có đã bao hàm câu hỏi đó.

Giống như điểm cuối ở trên, điểm cuối này luôn trả về 200 — hãy kiểm tra success trong phần nội dung.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/resolve-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "faqId": "aBcD1234eFgH5678" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/resolve-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", faqId: "aBcD1234eFgH5678" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/resolve-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "faqId": "aBcD1234eFgH5678"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": {
    "task_id": "task789",
    "faq_id": "aBcD1234eFgH5678",
    "follow_up_status": "published"
  }
}

follow_up_status cho bạn biết điều gì đã xảy ra với việc theo dõi liên hệ: published (đã gửi ngay lập tức), queued (AI đang trong quá trình trả lời liên hệ đó, nên sẽ được gửi sau), skipped_no_contact (tác vụ không có liên hệ được liên kết), hoặc skipped_no_campaign (không có chiến dịch nào để gửi qua đó).

Lỗi API FAQ #

Các endpoint FAQ trả về cấu trúc lỗi tiêu chuẩn:

{
  "success": false,
  "error": "FAQ not found"
}

Các mã chung mà mọi điểm cuối có thể trả về — 401, 403 (gói của bạn không bao gồm quyền truy cập API), 429 (giới hạn tốc độ) và 500 — được liệt kê cùng với hướng dẫn thử lại trong Lỗi & Phân trang.

POST /faqs/similar-for-task và POST /faqs/resolve-task là hai ngoại lệ trên trang này: chúng trả về 200 ngay cả khi xảy ra lỗi dự kiến (tác vụ không xác định, sai loại tác vụ) và đặt trạng thái thực vào error_code trong phần nội dung — hãy xem từng điểm cuối ở trên.

Liên quan #

• API Chiến dịch — các chiến dịch mà FAQ của bạn được liên kết tới.
• API Cơ sở kiến thức — tự động nhập trang web và tài liệu vào FAQ, đồng thời gộp các FAQ thành các nhóm kiến thức có thể tái sử dụng.
• Truy cập API — tạo khóa API của bạn.
• Xác thực — tất cả các cách để truyền khóa của bạn.