API AI Agent #

Một AI Agent (Tác nhân AI) là bộ não đằng sau bot của bạn: bao gồm các hướng dẫn, tính cách, ngôn ngữ, kiến thức và công cụ của nó. Bạn xây dựng một Agent một lần và sau đó điều hướng lưu lượng truy cập đến nó. Hướng dẫn này bao gồm mọi thứ bạn có thể thực hiện với một Agent thông qua API — tạo, cấu hình, cung cấp kiến thức và công cụ, xem xét các bản nháp và điều hướng các cuộc hội thoại đến nó.

• URL cơ sở — https://api.youraiconnector.com/v1
• Xác thực — khóa API của bạn (xem Xác thực)
• Lỗi & phân trang — xem Lỗi & Phân trang

Tất cả các ví dụ dưới đây đều hiển thị dạng truy vấn ?apiKey= trong cURL và tiêu đề X-API-Key trong JavaScript và Python — cả hai đều hoạt động trên mọi endpoint.

Nếu bạn mới làm quen với khái niệm Agent, hãy đọc AI Agents trước.

Cách thức hoạt động của một Agent #

Có bốn thành phần được quản lý riêng biệt, và việc hiểu rõ từng thành phần trước khi bắt đầu sẽ giúp ích cho bạn:

Một Agent mới sẽ không trả lời bất kỳ ai cho đến khi bạn điều hướng đến nó. Việc tạo một Agent không tự động đưa nó vào một kênh. Đây là bước mà hầu hết các tích hợp thường bỏ lỡ — xem Điều hướng cuộc hội thoại đến một Agent ở cuối trang này.

Đối tượng Agent #

Một tài liệu Agent đầy đủ thường rất lớn — vài trăm kilobyte, chủ yếu là danh sách FAQ, các nguồn kiến thức và bất kỳ nội dung trang nào được đọc từ trang web của bạn. Do đó, khi bạn yêu cầu liệt kê, hệ thống sẽ trả về một dòng tóm tắt ngắn gọn cho mỗi Agent:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Tài liệu đầy đủ sẽ bao gồm mọi thứ khác: instructions, rules, personality, availability, follow_up_config, danh sách FAQ và nguồn kiến thức được liên kết, các khối văn bản được tạo và bất kỳ trạng thái chạy nào (tag_generation, optimize_run).

Một số phản hồi cũng chứa substrate_campaign_id. Đây là bản ghi nội bộ được lưu giữ trên các tài khoản cũ; bạn không bao giờ cần phải thao tác với nó, và trên các tài khoản mới hơn, nó là null hoặc không tồn tại.

Liệt kê các Agent #

GET /agents — mọi Agent trên tài khoản, hiển thị theo thứ tự mới nhất trước.

Điểm cuối này không được phân trang. Theo mặc định, mỗi Agent sẽ trả về cấu hình đầy đủ, vốn rất nặng: một Agent đơn lẻ có thể đạt 580 KB và tài khoản 64-Agent có thể vượt quá 3 MB. Hãy truyền view=summary để nhận hàng ngắn gọn cho mỗi Agent, sau đó đọc thông tin bạn muốn bằng Lấy một Agent.

Các tham số truy vấn

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Phản hồi (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Tạo một Agent #

POST /agents — chỉ thực sự cần name; hãy gửi bất kỳ cấu hình nào bạn đã biết kèm theo đó. Một Agent mới sẽ được kích hoạt theo mặc định.

Các trường yêu cầu (tất cả đều tùy chọn ngoại trừ name)

Xây dựng Agent từ trang web của bạn. Hãy bao gồm scrape_urls và nền tảng sẽ đọc các trang đó rồi tự động viết hướng dẫn cho bạn. Phản hồi sẽ cho bạn biết quá trình tạo đó đã bắt đầu hay chưa, để bạn biết liệu có cần kiểm tra tiến độ của Agent hay không.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Phản hồi (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued là true khi nền tảng bắt đầu ghi các hướng dẫn từ các trang bạn đã cung cấp.

400 có nghĩa là phần thân không phải là một đối tượng JSON, một trường bị từ chối hoặc Agent vượt quá kích thước cấu hình mà gói của bạn cho phép. 403 có nghĩa là tài khoản không được phép sử dụng một trong các cài đặt bạn đã gửi — ví dụ như một cấp độ AI mà nhà cung cấp tài khoản chưa cấp quyền.

Lấy một Agent #

GET /agents/{agentId}

Truyền fields với một danh sách được phân tách bằng dấu phẩy để chỉ nhận lại những gì bạn cần, ví dụ fields=name,active,goal. id luôn được bao gồm và các tên không tồn tại trên Agent sẽ bị bỏ qua thay vì bị từ chối. Hãy bỏ qua nó để nhận toàn bộ tài liệu.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Một Agent không tồn tại trong tài khoản của bạn sẽ trả về 404.

Cập nhật một Agent #

PUT /agents/{agentId} — chỉ gửi các trường bạn muốn thay đổi; mọi thứ khác sẽ được giữ nguyên.

Các cài đặt lồng nhau có thể được xử lý từng phần tử một bằng khóa có dấu chấm, vì vậy "availability.monday" chỉ thay đổi Thứ Hai và giữ nguyên các ngày còn lại trong tuần.

Lưu ý

• Để thay đổi loại sự kiện có thể đặt chỗ mà Tác nhân (Agent) sẽ đặt, hãy gửi event_id (id của sự kiện, hoặc null để xóa nó). Gửi event_ids kèm một mảng để liên kết nhiều loại cùng lúc — loại đầu tiên sẽ trở thành loại chính và [] sẽ hủy liên kết tất cả. event_id và event_ids loại trừ lẫn nhau, và bản thân trường event không thể được ghi trực tiếp.
• enable_bookings phải là giá trị boolean thực, và booking_provider phải là một trong các giá trị default, zenchef, formitable.
• Các trường quyền sở hữu và danh tính sẽ bị bỏ qua, cũng như trạng thái chạy nội bộ (tiến trình tạo và tối ưu hóa).
• Định tuyến không được thiết lập tại đây. Sử dụng PUT /entry-points/channel-defaults để đặt Tác nhân làm người trả lời cho một kênh, POST /agents/{agentId}/entry-points cho các quy tắc từ khóa và bình luận, và PATCH /agents/{agentId}/active để tạm dừng hoặc tiếp tục hoạt động của nó.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Phản hồi (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Phần thân trống sẽ trả về 400 kèm theo "No fields to update".

Cập nhật cài đặt bot #

PUT /agents/{agentId}/bot-config — cách thức cụ thể để chỉ thay đổi các cài đặt hội thoại.

Một Tác nhân không có phần bot riêng biệt: các cài đặt của nó nằm trực tiếp trên Tác nhân, vì vậy tên các trường ở đây giống với tên bạn sẽ gửi tới PUT /agents/{agentId}. Điểm cuối này tồn tại như một cách an toàn và tập trung để thay đổi một vài trong số đó. Yêu cầu phải có ít nhất một trường.

Tên trường ở đây phải là tên thuần túy — chữ cái, số, dấu gạch dưới và dấu gạch ngang. Các đường dẫn có dấu chấm không được chấp nhận tại điểm cuối này (không giống như PUT /agents/{agentId}), vì vậy bot.goal sẽ bị từ chối với mã 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

Văn bản dài sẽ được tính vào kích thước cấu hình mà gói dịch vụ của bạn cho phép, vì vậy một tập hợp hướng dẫn quá lớn có thể bị từ chối với mã 400.

Thiết lập giờ hoạt động #

PUT /agents/{agentId}/active-hours — khoảng thời gian mà Tác nhân tự động trả lời. Ngoài các khung giờ đó, nó sẽ giữ im lặng.

Gửi một đối tượng availability với khóa là ngày trong tuần (từ monday đến sunday). Mỗi ngày nhận một khung thời gian duy nhất hoặc một danh sách các khung thời gian, theo định dạng HH:MM 24 giờ. Những ngày bạn bỏ qua sẽ giữ nguyên cài đặt cũ, và bất kỳ khóa nào không phải là ngày trong tuần đều sẽ bị từ chối — vì vậy lỗi đánh máy sẽ không dẫn đến việc không thực hiện gì cả.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Phản hồi (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Khóa ngày trong tuần không hợp lệ sẽ trả về 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Tạm dừng hoặc tiếp tục Tác nhân #

PATCH /agents/{agentId}/active — bật hoặc tắt Agent. Một Agent bị tạm dừng sẽ giữ nguyên mọi cấu hình nhưng ngừng phản hồi ngay lập tức; việc tiếp tục hoạt động sẽ có hiệu lực ngay lập tức.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Phản hồi (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active phải là một giá trị boolean thực — bất kỳ giá trị nào khác sẽ trả về 400 kèm theo "active (boolean) is required".

Sao chép một Agent #

POST /agents/{agentId}/duplicate — tạo một bản sao với cấu hình được giữ nguyên. Bản sao sẽ không gửi bất kỳ nội dung nào cho đến khi bạn trỏ một kênh hoặc một Điểm truy cập (Entry Point) vào nó.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Phản hồi (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Một bản sao được tính vào hạn mức Agent trong gói của bạn giống hệt như khi tạo mới từ đầu, vì vậy yêu cầu sẽ bị từ chối với 403 khi tài khoản đã đạt giới hạn.

Xóa một Agent #

DELETE /agents/{agentId}

Việc xóa sẽ bị từ chối khi Agent vẫn đang được gắn với một thành phần nào đó mà nếu thiếu nó sẽ ngừng hoạt động — ví dụ như một chương trình phát sóng, một Điểm truy cập, hoặc (trên các tài khoản cũ) một chiến dịch. Phản hồi sẽ liệt kê những gì đang giữ Agent đó để bạn có thể tách chúng ra trước rồi thử lại.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Phản hồi (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Đã chặn (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Bản nháp: xem lại các thay đổi trước khi chúng được áp dụng #

Các chỉnh sửa được thực hiện trong trình soạn thảo và bất kỳ nội dung viết lại nào được tạo bởi Tối ưu hóa bằng AI sẽ được lưu dưới dạng bản nháp chưa xuất bản cho đến khi bạn xuất bản chúng. Agent đang hoạt động sẽ tiếp tục phản hồi với cấu hình hiện tại của nó cho đến lúc đó.

Xuất bản bản nháp #

POST /agents/{agentId}/publish-draft — chuyển bản nháp sang cấu hình đang hoạt động và xóa bản nháp trong cùng một bước.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Phản hồi (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys liệt kê các cài đặt đã được chuyển từ bản nháp sang Agent đang hoạt động, để bạn có thể hiển thị những gì đã thay đổi.

Hãy kiểm tra xem bản nháp có tồn tại hay không trước khi gọi lệnh này. Việc xuất bản một Agent không có bản nháp là một lệnh gọi không được hỗ trợ và hiện tại sẽ trả về 500 với một thông báo chung, không phải thông báo cụ thể. Để hủy bỏ bản nháp thay vì xuất bản, hãy sử dụng lệnh loại bỏ (discard) bên dưới.

Hủy bản nháp #

POST /agents/{agentId}/discard-draft — loại bỏ bản nháp và giữ nguyên cấu hình hiện tại. Có thể gọi an toàn khi không có bản nháp nào; sẽ không có gì xảy ra.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Tối ưu hóa Tác nhân bằng AI #

POST /agents/{agentId}/optimize — viết lại cấu hình của Tác nhân dựa trên phản hồi của bạn (“nó cứ đưa ra các ưu đãi”, “câu trả lời quá dài”) và lưu bản viết lại dưới dạng bản nháp thay vì áp dụng trực tiếp.

Gửi user_feedback (một chỉ dẫn đơn giản) hoặc, khi phản hồi về một câu trả lời không tốt cụ thể, hãy gửi thumbs_down_feedback cùng với thumbs_down_message gây ra vấn đề đó. Ít nhất một trong hai phải chứa văn bản.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Phản hồi (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Công việc chạy trong nền và lệnh gọi sẽ trả về ngay lập tức. Đọc Tác nhân bằng GET /agents/{agentId} và theo dõi optimize_run.status; khi trạng thái trở về Draft, bản viết lại sẽ nằm trong phần bản nháp của Tác nhân. Hãy xem xét nó, sau đó xuất bản hoặc hủy bỏ.

Mỗi Tác nhân chỉ được thực hiện một lần chạy tại một thời điểm — lệnh gọi thứ hai trong khi lệnh thứ nhất đang chạy sẽ trả về 409. Việc này sử dụng tín dụng AI.

Quy tắc gắn thẻ #

Quy tắc gắn thẻ bao gồm một thẻ và mô tả về thời điểm áp dụng thẻ đó. Trong cuộc trò chuyện, Tác nhân sẽ đọc mô tả đó và gắn thẻ cho liên hệ khi phù hợp, đây là cách các quy trình tự động dựa trên thẻ được kích hoạt.

Đối tượng quy tắc

Thêm quy tắc gắn thẻ #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Phản hồi (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Thay thế quy tắc gắn thẻ #

PUT /agents/{agentId}/tags/{tagId} — quy tắc được tìm thấy theo id thẻ trong đường dẫn và được thay thế toàn bộ, không phải hợp nhất, vì vậy hãy gửi toàn bộ quy tắc thay vì chỉ phần bạn đang thay đổi. Thẻ mà nó trỏ tới vẫn được giữ nguyên ngay cả khi bạn bỏ qua tag_id, vì vậy một chỉnh sửa không thể tách quy tắc khỏi thẻ của nó.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Xóa quy tắc gắn thẻ #

DELETE /agents/{agentId}/tags/{tagId} — Tác nhân ngừng áp dụng thẻ đó. Bản thân thẻ và bất kỳ liên hệ nào đã mang thẻ đó đều không bị ảnh hưởng.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Cả hai điểm cuối đều trả về 404 khi Tác nhân không tồn tại hoặc khi nó không có quy tắc nào cho thẻ đó.

Tạo tập hợp thẻ bằng AI #

POST /agents/{agentId}/tags/generate — thiết kế toàn bộ tập hợp các quy tắc (tên thẻ và cách diễn đạt “áp dụng khi…” đằng sau mỗi quy tắc) bằng cách đọc các hướng dẫn và mục tiêu của chính Tác nhân.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Phản hồi (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

Công việc chạy trong nền. Hãy đọc phần Agent và theo dõi tag_generation.status; các quy tắc sẽ nằm trong tags của Agent. Mỗi Agent chỉ chạy một tác vụ tại một thời điểm (nếu không sẽ gặp 409) và tác vụ này sẽ sử dụng tín dụng AI.

Nguồn kiến thức #

Nguồn kiến thức là các trang và tài liệu mà nền tảng đã đọc cho bạn. Việc đính kèm một nguồn vào Agent cho phép nó trả lời dựa trên nội dung đó.

Nguồn gốc của id nguồn. Thêm nội dung bằng các endpoint cơ sở kiến thức — POST /kb-sources/url cho một trang, POST /kb-sources/file cho một tài liệu, POST /kb-sources/bulk-import cho toàn bộ trang web. Các endpoint này trả về một source_id mà bạn cần thăm dò bằng GET /kb-sources/{sourceId} cho đến khi nó sẵn sàng. POST /kb-sources/url cũng chấp nhận autoLinkToAgentId, giúp đính kèm nguồn vào Agent ngay khi quá trình nhập hoàn tất, vì vậy bạn có thể bỏ qua lệnh gọi đính kèm bên dưới.

Đính kèm nguồn kiến thức #

POST /agents/{agentId}/kb-sources — gửi kb_source_ids kèm theo danh sách để đính kèm toàn bộ tập hợp trong một lệnh gọi (điều bạn muốn sau khi thu thập dữ liệu trang web), hoặc kb_source_id cho một nguồn duy nhất. Chỉ gửi một trong hai. Việc đính kèm một thứ đã được đính kèm sẽ không thay đổi gì cả.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Phản hồi (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Gỡ nguồn kiến thức #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} cho một mục, hoặc POST /agents/{agentId}/kb-sources/bulk-remove với kb_source_ids cho nhiều mục. Việc xóa hàng loạt là một POST vì danh sách các id được truyền trong phần thân yêu cầu.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

Bản thân các nguồn không bị xóa và vẫn khả dụng cho các Tác nhân khác của bạn. Việc tách một thứ gì đó không được đính kèm sẽ không thay đổi bất cứ điều gì.

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

Các FAQ được quản lý trên các điểm cuối riêng và được liên kết với một Tác nhân từ đó: POST /faqs/{faqId}/link với { "agent_id": "ag7HkQ2ZpLxR3mNb" }, và POST /faqs/{faqId}/unlink để gỡ bỏ nó. Một FAQ có thể được chia sẻ bởi bất kỳ số lượng Tác nhân nào. Xem API FAQ.

Một FAQ chỉ được sử dụng bởi các Tác nhân mà nó được liên kết — việc tạo ra một FAQ là chưa đủ.

Công cụ #

Hàm tùy chỉnh #

POST /agents/{agentId}/custom-functions cho phép Tác nhân gọi một trong các hàm tùy chỉnh của bạn trong khi trò chuyện. Chỉ các hàm thuộc cùng một tài khoản mới có thể được đính kèm, và việc đính kèm một hàm đã được đính kèm sẽ không thay đổi bất cứ điều gì.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} sẽ tách nó ra. Bản thân hàm không bị xóa và vẫn khả dụng cho các Tác nhân khác của bạn.

Quản lý chính các hàm trên /custom-functions — xem Hàm tùy chỉnh để biết chúng là gì.

Máy chủ MCP #

Máy chủ MCP là một gói công cụ có sẵn mà Tác nhân của bạn có thể tự khám phá và gọi — xem Kết nối Máy chủ MCP với Bot của bạn. Các máy chủ được đăng ký một lần trên tài khoản, sau đó được đính kèm vào bất kỳ Tác nhân nào cần sử dụng chúng.

Các máy chủ MCP cần tính năng hàm tùy chỉnh trong gói của bạn. Nếu không có tính năng này, các điểm cuối /mcp-servers ở cấp tài khoản sẽ trả về 403. Việc đính kèm một máy chủ đã đăng ký vào một Tác nhân không bị giới hạn.

Đăng ký máy chủ #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Phản hồi (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Khi lưu, nền tảng sẽ kết nối với máy chủ và lưu vào bộ nhớ đệm danh sách các công cụ mà nó cung cấp. Một máy chủ không thể kết nối vẫn được lưu, với lý do nằm trong last_error và danh sách công cụ trống — vì vậy bạn có thể đăng ký trước và khắc phục kết nối sau.

Một auth_type là oauth2 sẽ lưu đăng ký với oauth_connected: false và không có công cụ nào: chưa có mã thông báo (token). Việc ủy quyền cho máy chủ OAuth cần đăng nhập qua trình duyệt và được thực hiện từ bảng điều khiển, không phải qua API.

Liệt kê, cập nhật và xóa máy chủ #

• GET /mcp-servers — mọi máy chủ đã đăng ký, mới nhất trước, trong servers.
• PUT /mcp-servers/{serverId} — chỉ gửi những gì bạn muốn thay đổi. Việc thay đổi URL hoặc các trường xác thực sẽ kiểm tra lại kết nối và làm mới danh sách công cụ đã lưu trong bộ nhớ đệm.
• DELETE /mcp-servers/{serverId} — xóa đăng ký và hủy liên kết khỏi mọi Tác nhân và chiến dịch đã bật nó.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Thông tin bí mật không bao giờ được trả về. Các phản hồi mang theo auth_header_value_set (một cờ true/false cho biết giá trị đã được lưu trữ) thay vì thông tin xác thực, và các mã thông báo OAuth cùng bí mật khách hàng vẫn nằm ở phía máy chủ. Mọi thứ khác đều được trả về: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Kiểm tra kết nối #

POST /mcp-servers/test-connection — kết nối tới một máy chủ và liệt kê các công cụ của nó. Có hai cách để gọi lệnh này:

• với server_id — kiểm tra cấu hình đã lưu và làm mới danh sách công cụ được lưu trong bộ nhớ đệm;
• với url nội dòng (cộng với auth_header_name / auth_header_value) — một bài kiểm tra trước khi lưu mà không lưu trữ bất kỳ thứ gì.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Phản hồi (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Lỗi kết nối không phải là lỗi HTTP — bạn sẽ nhận được một 200 với success: false và một error mô tả những gì đã xảy ra, vì vậy bạn có thể hiển thị nó bên cạnh trường mà người vận hành đang chỉnh sửa.

Gắn máy chủ vào một Tác nhân (Agent) #

Việc đăng ký một máy chủ không cấp quyền truy cập cho bất kỳ Tác nhân nào vào máy chủ đó. Hãy gắn nó:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Phản hồi (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} sẽ tách nó ra một lần nữa. Bản thân máy chủ không bị xóa và vẫn khả dụng cho các Tác nhân khác của bạn. Việc gắn hoặc tách một thứ gì đó đã ở trạng thái đó sẽ không thay đổi bất cứ điều gì.

Thư viện phương tiện #

Thư viện phương tiện lưu trữ các tệp mà một Tác nhân có thể gửi trong cuộc trò chuyện — menu, bảng giá, ảnh sản phẩm. Một Tác nhân có thể lưu giữ tối đa 50 mục.

Liệt kê phương tiện #

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Phản hồi (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Các mục được lưu trữ trên Tác nhân (Agent) sẽ xuất hiện trước, sau đó là các mục cũ hơn vẫn còn được lưu trữ trên chiến dịch mà Tác nhân đó được tạo ra; media_home (agent hoặc campaign) cho biết mục nào thuộc nhóm nào. Trong mỗi nhóm, mục mới nhất sẽ được hiển thị trước.

media_url hết hạn sau 7 ngày. Đây là liên kết tải xuống được tạo khi tệp được tải lên — hãy coi liên kết cũ là đã hết hạn thay vì bị hỏng, và đọc lại danh sách để nhận liên kết mới.

Tải lên phương tiện #

POST /agents/{agentId}/media-library — tệp được tải lên nội dòng dưới dạng base64, tối đa 10 MB. Lệnh gọi sẽ trả về sau khi tệp được lưu trữ, vì vậy hãy cho phép thời gian chờ lâu hơn một chút so với yêu cầu thông thường. Lưu ý rằng phần thân này sử dụng tên trường theo kiểu camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Hai việc sẽ tự động diễn ra: ảnh GIF động được chuyển đổi thành video để có thể phát trên mọi kênh, và nền tảng sẽ viết một bản tóm tắt ngắn gọn về nội dung thực sự có trong tệp để Tác nhân biết khi nào tệp đó phù hợp.

Mã 400 bao gồm các trường bị thiếu, loại tệp không được hỗ trợ, tệp trống hoặc quá lớn và việc đạt giới hạn 50 mục. Mã 403 có nghĩa là thư viện phương tiện đã bị tắt đối với tài khoản này.

Cập nhật mục phương tiện #

PATCH /agents/{agentId}/media-library/{itemId} — chỉ dành cho siêu dữ liệu. Bản thân tệp không thể thay thế được; hãy tải lên mục mới và xóa mục cũ. Phần thân này sử dụng kiểu snake_case: title, description, send_message, max_sends_per_conversation (một số nguyên không âm, hoặc null để xóa giới hạn).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Phản hồi (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Xóa mục phương tiện #

DELETE /agents/{agentId}/media-library/{itemId} — xóa mục và tệp đã lưu trữ của nó. Việc xóa một mục đã không còn tồn tại vẫn thành công và báo cáo deleted: false, vì vậy lệnh gọi này an toàn để thử lại.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Tạo tin nhắn theo dõi #

POST /agents/{agentId}/template-generation — tự động viết các tin nhắn theo dõi của Tác nhân cho bạn (các lời nhắc mà Tác nhân gửi khi cuộc trò chuyện trở nên im ắng), dựa trên mục đích của Tác nhân đó.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Có hai cách để nhận kết quả này, và trường target sẽ cho bạn biết đó là cách nào:

• target: "agent" với 200 — các tin nhắn đã được ghi lại trong cuộc gọi và kết quả nằm trong data. Đọc lại chúng từ follow_up_config của Tác nhân. Đây là trường hợp thông thường.
• target: "campaign" với 202 — công việc đã được xếp hàng chờ cho chiến dịch có tên trong campaign_id. Hãy theo dõi template_generation_status của chiến dịch đó cho đến khi hoàn tất.

cold_only cần một chiến dịch gửi đi và sẽ bị từ chối với 409 (reason: "cold_only_requires_campaign") trên một Tác nhân không có chiến dịch nào. 403 nghĩa là tính năng tự động theo dõi không được bật cho tài khoản. Tính năng này sử dụng tín dụng AI, và 400 với "Insufficient credits." nghĩa là tài khoản đã hết tín dụng.

Định tuyến cuộc hội thoại đến một Tác nhân #

Một Tác nhân chỉ trả lời các cuộc hội thoại mà Điểm truy cập gửi đến. Cho đến khi một kênh có Điểm truy cập, tin nhắn đầu tiên từ một người mà bạn chưa từng trò chuyện vẫn được lưu trữ, nhưng không có gì tiếp nhận nó và không có trợ lý nào trả lời.

Liệt kê các Điểm truy cập của Tác nhân #

GET /agents/{agentId}/entry-points — các quy tắc định tuyến gửi cuộc hội thoại đến Tác nhân này, quy tắc mới nhất hiển thị trước. Cả quy tắc hiện tại và quy tắc đã ngừng hoạt động đều được trả về; quy tắc đã ngừng hoạt động sẽ có enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Đối với các mặc định kênh của toàn bộ tài khoản, bao gồm cả kênh được cố tình đặt là không có ai trả lời, hãy đọc GET /entry-points/channel-defaults thay thế.

Tạo Điểm truy cập #

POST /agents/{agentId}/entry-points — Tác nhân trong đường dẫn luôn được ưu tiên, vì vậy không bao giờ có thể tạo quy tắc cho một Tác nhân khác với Tác nhân trong URL.

channels là bắt buộc và cho biết các kênh mà quy tắc áp dụng — ví dụ: whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget hoặc custom_channel. Các quy tắc mới được bật trừ khi bạn chỉ định khác.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Phản hồi (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Quy tắc nào thắng khi có nhiều quy tắc có thể áp dụng: một cuộc hội thoại đang diễn ra hoặc một phân công thủ công sẽ giữ lại Tác nhân mà nó đã có; nếu không, các quy tắc từ khóa sẽ thắng quy tắc bình luận, quy tắc bình luận thắng quy tắc người theo dõi, và mặc định kênh là lựa chọn cuối cùng. Việc các quy tắc này đã quyết định bất cứ điều gì trên tài khoản hay chưa được báo cáo bởi GET /entry-points/routing-status.

Đây là phiên bản rút gọn. Hướng dẫn Entry Points API bao gồm toàn bộ các quy tắc về thứ bậc, bình luận và người theo dõi, mỗi số WhatsApp chỉ được dùng một Agent, cũng như cách thay đổi hoặc xóa quy tắc. Xem Entry Points để biết về khái niệm này và Channels API để kết nối chính kênh đó.

Lỗi API Tác nhân AI #

Các endpoint của Tác nhân trả về cấu trúc lỗi tiêu chuẩn:

{
  "success": false,
  "error": "Agent 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.

Lưu ý về trình khám phá. Các endpoint /agents nằm trong đặc tả OpenAPI đã xuất bản, vì vậy bạn có thể duyệt qua các trường chính xác của chúng và chạy các yêu cầu trực tiếp trong Tài liệu tham khảo API. Các endpoint /mcp-servers ở cấp tài khoản cũng nằm trong đặc tả, vì vậy bạn cũng có thể khám phá chúng ở đó.

Liên quan #

• Tác nhân AI — Tác nhân là gì, giải thích bằng ngôn ngữ đơn giản.
• Điểm truy cập — cách các cuộc hội thoại được định tuyến đến một Tác nhân.
• API Câu hỏi thường gặp — xây dựng và liên kết kiến thức mà Tác nhân của bạn dùng để trả lời.
• API Kênh — kết nối các kênh mà một Tác nhân phản hồi.
• Kết nối Máy chủ MCP với Bot của bạn · Hàm tùy chỉnh
• Tài liệu tham khảo API — trình khám phá endpoint tương tác đầy đủ.