Knowledge Worker API

Tạo thêm 1 bot/tenant mới từ một tài khoản đã có API key.

Trường	Kiểu	Bắt buộc	Ghi chú
tenant	string	có	3-40 ký tự: chữ thường/số/gạch ngang/gạch dưới
bot_name	string	có	2-80 ký tự
greeting	string	không	tối đa 500 ký tự
system_prompt	string	không	tối đa 10.000 ký tự

{ "success": true, "tenant": "abc-shop", "bot_name": "AB Shop", "api_key": "sk_...", "created_from": "your-tenant" }

Lỗi 409 nếu tenant đã tồn tại.

Đọc cấu hình hiện tại của bot (tên, màu, webhook, system_prompt, model, temperature, Telegram chat id, Cloudinary, brand_logo_url...).

{ "success": true, "config": { "bot_name": "...", "greeting": "...", "system_prompt": "...", "model": "...", "temperature": 0.3, "max_tokens": 1000, "streaming": true, "webhook": "...", "owner_telegram_chat_id": "...", "..." : "..." } }

Cập nhật một phần cấu hình — chỉ gửi field muốn đổi.

Trường	Kiểu	Ghi chú
bot_name, bot_avatar, color, webhook, greeting, system_prompt, response_language, model, owner_telegram_chat_id, cloudinary_*, brand_logo_url	string	trim tự động
temperature	number	0 – 2
max_tokens	integer	1 – 32768
streaming	boolean

{ "success": true, "updated": ["greeting", "temperature"] }

Chat tự nhiên với trợ lý cấu hình — model tự gọi tool để lưu cấu hình, kết nối kênh (Facebook/Instagram/Zalo/WordPress/Sanity...), thêm agent tool, lên lịch đăng bài, tạo chat-link, v.v. thay vì phải gọi từng API bên dưới bằng tay.

Trường	Kiểu	Bắt buộc
messages	array<{role: "user"|"assistant", content: string}>	có — tối đa 100 message, message cuối phải là "user"

{ "success": true, "reply": "Đã cập nhật lời chào." }

Liệt kê toàn bộ tool mà /agent-chat có thể gọi (built-in + tool tùy chỉnh của tenant).

Gửi 1 tin nhắn của khách tới chatbot AI và nhận câu trả lời (tương đương endpoint /chat nội bộ nhưng tự ép đúng tenant theo API key).

Trường	Kiểu	Bắt buộc	Ghi chú
session	string	có
question	string	có	≤ 10.000 ký tự
lesson_id	string	không	có thì trả lời theo đúng phạm vi lesson đó (xem Bài học (Lessons)), bỏ trống = bot trợ lý chung

Sinh 1 link chat riêng, gắn sẵn tên khách + (tuỳ chọn) ngữ cảnh khách hàng — không cần tạo tenant hay ghi session trước, widget chat.html tự đọc từ URL. Dùng khi hệ thống ngoài (vd POS) muốn gửi link chat cho khách qua SMS/Zalo/email.

Trường	Kiểu	Bắt buộc	Ghi chú
customer_name	string	có	tên hiển thị trong chat
customer_context	object	không	ghi luôn ngữ cảnh khách (đơn hàng, mã KH...) cho session mới tạo

{ "success": true, "session": "a1b2c3d4-...", "chat_url": "https://chat.schoolsai.work/chat.html?bot=your-tenant&session=a1b2c3d4-...&u=Nguy%E1%BB%85n%20V%C4%83n%20A" }

Ghi/cập nhật ngữ cảnh khách hàng (đơn hàng, trạng thái, ghi chú...) cho 1 session đã tồn tại — để chatbot AI có sẵn dữ liệu thật khi trả lời khách, không cần khách tự khai lại.

Trường	Kiểu	Bắt buộc
session	string	có
context	object	có — object phẳng, không phải mảng

{ "success": true, "session": "a1b2c3d4-..." }

Lấy lịch sử tin nhắn của tenant (tối đa 100, mới nhất trước).

Query	Ghi chú
session	lọc theo 1 session cụ thể (không truyền = toàn bộ tenant)

{ "success": true, "messages": [
  { "id": "...", "session": "...", "username": "Khách", "text": "...", "is_bot": false, "needs_human": true, "escalation_resolved": false, "created": "..." }
] }

Gửi tin nhắn chủ động tới 1 session đã tồn tại — dùng để hệ thống ngoài (POS, CRM...) chủ động báo tin cho khách qua đúng cuộc chat đang mở (vd "đơn hàng đã xong"). Tự động đánh dấu mọi tin nhắn needs_human đang chờ của session đó là escalation_resolved.

Trường	Kiểu	Bắt buộc	Ghi chú
session	string	có	≤ 200 ký tự — phải là session đã có ít nhất 1 tin nhắn (tạo qua /chat-link hoặc khách đã chat 1 lần)
text	string	không*	≤ 10.000 ký tự
media	array	không*	Tối đa 10 phần tử {type: image|video|audio|file, url: HTTPS, caption?, filename?}. Phải có ít nhất text hoặc media. Với session Facebook, Instagram, WhatsApp hoặc Zalo, server gửi media qua API của nền tảng.

curl -X POST https://apic.schoolsai.work/api/v1/messages \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"session":"a1b2c3d4-...","text":"Đơn hàng đã xong!","media":[{"type":"video","url":"https://cdn.example.com/demo.mp4","caption":"Video hướng dẫn"}]}'

// 200
{ "success": true, ... }
// 404 — session chưa từng có tin nhắn nào
{ "error": "Không tìm thấy phiên trò chuyện" }

Nếu chưa chắc session còn tồn tại, gọi GET /api/v1/messages?session=... trước để kiểm tra, hoặc tạo session bằng POST /api/v1/chat-link ngay từ đầu (server tự lưu customer_context nếu có).

Tạo câu chào đầu cuộc gọi theo tên và ngôn ngữ cấu hình của workspace.

curl -X POST https://apic.schoolsai.work/api/v1/ai-voice/greeting \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"lang":"vi"}'

# 200
{ "success": true, "text": "Xin chào...", "audioBase64": "..." }

Gửi một lượt nói của khách đến đúng AI workspace gắn với API key.

Trường form	Bắt buộc	Ghi chú
audio	có	File âm thanh, ví dụ audio/webm
session	có	Giữ nguyên giữa các lượt để AI workspace nhớ hội thoại
username	không	Tên hiển thị của người gọi
duration_ms	không	Thời lượng audio để tính quota voice

curl -X POST https://apic.schoolsai.work/api/v1/ai-voice/turn \
  -H "Authorization: Bearer sk_xxx" \
  -F "audio=@voice.webm;type=audio/webm" \
  -F "session=customer-call-123" \
  -F "username=Nguyen Van A" \
  -F "duration_ms=4200"

# 200
{ "success": true, "transcript": "...", "reply": "...", "audioBase64": "...", "needsHuman": false }

Không gửi tenant; server luôn lấy workspace từ API key. Khi needsHuman=true, client có thể chuyển sang luồng cuộc gọi nhân viên qua Cloudflare Realtime.

Liệt kê cuộc gọi chưa kết thúc (status != "ended") của tenant.

Query	Ghi chú
session	lọc theo session

Admin bắt đầu 1 cuộc gọi tới khách trong 1 session.

Trường	Bắt buộc
session	có
cf_session_id, track_name	có — id phiên WebRTC từ Cloudflare Realtime

Admin trả lời cuộc gọi đang ringing.

Trường	Bắt buộc
call_id	có
cf_session_id, track_name	có

Từ chối (chưa nghe) hoặc kết thúc (đang gọi) 1 cuộc gọi.

Trường	Bắt buộc	Ghi chú
call_id	có
reason	không	mặc định "declined" / "hangup"

Liệt kê tối đa 50 bài gần nhất, kèm targets (kênh đăng + trạng thái) và media.

Query	Ghi chú
status	lọc bài có ít nhất 1 target ở trạng thái này (pending/approved/scheduled/publishing/published/error)

Tạo bài viết mới, tự tạo target cho từng kênh đã kết nối (mặc định facebook nếu không truyền platforms).

Trường	Kiểu	Bắt buộc
title, content	string	có
image_prompt, image_url, video_url	string	không
platforms	string[]	không — mặc định ["facebook"]
auto_approve	boolean	true = tạo target ở trạng thái "approved" luôn, bỏ qua bước duyệt

Duyệt toàn bộ target đang "pending" của 1 bài. Bị chặn (409) nếu bài thuộc content-plan mà dependency chưa sẵn sàng.

Lên kế hoạch + viết nền (async) 1 cụm nhiều bài blog SEO xoay quanh 1 chủ đề, có liên kết nội bộ giữa các bài.

Trường	Bắt buộc	Ghi chú
topic	có
count	không	mặc định 5, tối đa 8

Đếm số bài theo từng trạng thái pipeline (pending/approved/scheduled/publishing/published/error).

Chạy thủ công (không đợi cron) job crawl RSS + viết nháp, job publish bài đã duyệt, hoặc 1 lượt AI agent vận hành cho tenant hiện tại.

Liệt kê tối đa 100 tài liệu (id, title, char_count, created).

Thêm 1 tài liệu mới, tự động embed cho tìm kiếm ngữ nghĩa (tương đương endpoint nội bộ /embed, ép đúng tenant).

Trường	Kiểu	Bắt buộc	Ghi chú
text	string	có	≤ 500.000 ký tự
title	string	không	≤ 200 ký tự

Xoá 1 tài liệu theo id.

Đồng bộ lại toàn bộ nguồn tài liệu đã cấu hình (vd Sanity/WordPress) cho tenant.

Tạo mới hoặc cập nhật 1 lesson (upsert theo lesson_id). Tự động: (1) lưu nội dung để bot theo lesson lookup thẳng, (2) nhúng vào workspace RAG của tenant cho bot trợ lý chung, (3) nếu lesson đã tồn tại thì tự xoá bản nhúng cũ trước khi nhúng lại — gọi lại API này mỗi khi sửa nội dung lesson là đủ, không cần tự quản lý embedding.

Trường	Kiểu	Bắt buộc	Ghi chú
lesson_id	string	có	id lesson bên hệ thống của bạn — ≤ 100 ký tự, dùng lại đúng id này khi chat/xoá
title	string	không
content	string	có	toàn bộ nội dung bài học (text) — ≤ 500.000 ký tự

Xoá 1 lesson — dọn luôn bản nhúng RAG tương ứng khỏi workspace của tenant, để bot trợ lý chung không còn nhắc tới nội dung đã xoá.

Liệt kê các tool (API ngoài) tenant đã đăng ký.

Đăng ký 1 API ngoài làm tool cho AI gọi. Dùng {tên_tham_số} trong url_template để chèn giá trị model chọn.

Trường	Kiểu	Bắt buộc	Ghi chú
name	string	có	chỉ chữ/số/gạch dưới
description	string	không	để model biết khi nào nên gọi tool này
method	string	không	mặc định GET — kênh marketplace-chat chỉ chạy được GET
url_template	string	có	vd https://api.client.com/search?q={keyword}&price_max={price_max}
parameters_schema	string	không	JSON Schema dạng chuỗi, mô tả tham số model được điền
headers_template	string	không	JSON dạng chuỗi, vd API key tĩnh của bạn
result_path	string	không	đường dẫn lấy phần cần thiết từ response JSON, vd data.results

Gỡ 1 tool đã đăng ký.

Chat cho khách hàng cuối — AI tự gọi đúng tool GET đã đăng ký (xem POST /agent-tools) để trả lời, áp dụng cùng giới hạn lượt chat/tháng như POST /chat.

Trường	Kiểu	Bắt buộc	Ghi chú
session	string	có
messages	array	có	có — tối đa 100 message, message cuối phải là "user"
item_id	string	không	khách đang xem đúng 1 mục cụ thể (vd trang chi tiết 1 tin BĐS) — server tự gọi thẳng tool tên get_item_detail (nếu đã đăng ký) với tham số id, không chờ model quyết định, đảm bảo tư vấn đúng mục đang xem
item_context	string	không	≤ 20.000 ký tự — nếu hệ thống gọi API này (backend của bạn) đã có sẵn nội dung mục đang xem, gửi thẳng text đã làm sạch qua đây thay vì dùng item_id; ưu tiên hơn item_id nếu cả 2 cùng được gửi, tránh phải gọi ngược lại API của bạn

Chat cho người vận hành nội bộ theo contract orchestration-only. Response luôn echo nguyên vẹn request_id.

Trường	Kiểu	Bắt buộc	Ghi chú
request_id	UUID	có	Duy nhất cho mỗi lượt; dùng làm idempotency key
session	string	có	Không dùng chung cho các request đồng thời
messages	array	có	Tối đa 20 message; content tối đa 8.000 ký tự

Response thành công: { "request_id", "type":"answer", "answer", "finish_reason":"stop" } hoặc { "request_id", "type":"tool", "tool_call_id", "name", "args" }. Gửi kết quả tool ở lượt tiếp theo với cùng request/session và giữ nguyên tool_call_id. Tối đa 6 vòng tool.

Liệt kê tối đa 50 đề xuất gần nhất, mới nhất trước. Lọc theo trạng thái bằng query status.

Trường	Kiểu	Bắt buộc	Ghi chú
status	string	không	pending / confirmed / rejected — bỏ trống để lấy tất cả

Thực thi thật đề xuất đang pending — gọi tool với đúng tham số model đã chọn lúc đề xuất, ghi lại kết quả.

Lỗi 409 nếu đề xuất không còn ở trạng thái pending (đã xác nhận/từ chối trước đó — không xác nhận/từ chối lại được).

Huỷ 1 đề xuất đang pending — không có gì được thực thi.

Liệt kê toàn bộ store (workspace) của platform, kèm gói cước hiện tại và số lượng đã dùng/giới hạn.

curl https://apic.schoolsai.work/api/account/workspaces \
  -H "Authorization: Bearer <account_token>"
# -> { "success": true, "plan": "pro", "limit": 10, "used": 3,
#      "workspaces": ["platform-default", "agency-x", "agency-y"] }

Tạo 1 store mới (workspace phụ) cho platform. Giới hạn 10 lần gọi/giờ để chống tạo tràn lan.

Trường	Kiểu	Bắt buộc	Ghi chú
tenant	string	có	3-40 ký tự, chữ thường/số/gạch ngang/gạch dưới — nên dùng slug ổn định theo id nội bộ của store, vd agency-1024
bot_name	string	có	2-80 ký tự
greeting	string	không
system_prompt	string	không	dùng cho thông tin tĩnh, nhỏ của store (giới thiệu, chính sách, giờ mở cửa) — xem khối "Chọn đúng cách nạp dữ liệu" bên dưới

curl -X POST https://apic.schoolsai.work/api/account/workspaces \
  -H "Authorization: Bearer <account_token>" -H "Content-Type: application/json" \
  -d '{"tenant":"agency-1024","bot_name":"Agency 1024 Assistant"}'
# -> 201 { "success": true, "tenant": "agency-1024", "bot_name": "...",
#          "api_key": "sk_xxx", "plan": "pro", "used": 4, "limit": 10 }
# LƯU NGAY "api_key" trả về — đây là api_key RIÊNG của store này, dùng cho
# mọi endpoint khác trên trang (agent-tools, marketplace-chat, config, knowledge...).

Lỗi 409 nếu tenant đã tồn tại (chọn slug khác). Lỗi 403 nếu platform đã đạt giới hạn số store của gói hiện tại (mặc định free 3 / pro 10) — liên hệ Schoolsai để nâng nếu platform cần nhiều store hơn, đây là giới hạn có thể nới riêng theo từng platform, không cố định.

Xoá 1 store (workspace phụ) — xoá luôn bot và toàn bộ dữ liệu riêng của store đó (knowledge base, agent tools...), giải phóng 1 chỗ trong giới hạn số workspace. Không thể xoá workspace mặc định của tài khoản qua endpoint này.

curl -X DELETE https://apic.schoolsai.work/api/account/workspaces/agency-1024 \
  -H "Authorization: Bearer <account_token>"
# -> 200 { "success": true, "tenant": "agency-1024" }

Lỗi 404 nếu tenant không tồn tại hoặc không thuộc tài khoản của bạn. Lỗi 403 nếu cố xoá workspace mặc định của tài khoản (workspace gắn liền với chính account, không phải store tự tạo). Hành động này không thể hoàn tác — api_key của store đó ngừng hoạt động ngay lập tức.

Trường	Kiểu	Bắt buộc	Ghi chú
content_type	string	có	"blog" · "social"
times	string[]	có	mảng "HH:MM", 1 giờ = 1 bài/ngày áp dụng
days	string[]	không	mon..sun; rỗng/bỏ qua = áp dụng hàng ngày
is_active	boolean	không

Cập nhật 1 phần (cùng field như tạo mới, tất cả optional).