> For the complete documentation index, see [llms.txt](https://docs.clickai.vn/clickai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clickai.vn/clickai-docs/nha-phat-trien/tich-hop-clickai-qua-restful-api.md). # Tích hợp ClickAI qua RESTful API ## Mục lục · \[Cách API Integration hoạt động]\(#cách-api-integration-hoạt-động) · \[Bắt đầu]\(#bắt-đầu) · \[Xác thực (Authentication)]\(#xác-thực-authentication) · \[API lấy danh sách Assistants]\(#api-lấy-danh-sách-assistants) · \[API cho Text Generation App]\(#api-cho-text-generation-app) · \[API cho Conversational App (Chatbot / Agent)]\(#api-cho-conversational-app) · \[API cho Workflow App]\(#api-cho-workflow-app) · \[Quản lý conversation\_id]\(#quản-lý-conversation\_id) · \[Streaming vs Blocking Response]\(#streaming-vs-blocking-response) · \[File Upload API]\(#file-upload-api) · \[Feedback API]\(#feedback-api) · \[Conversations API]\(#conversations-api) · \[Error Handling]\(#error-handling) · \[Rate Limits]\(#rate-limits) · \[SDK & Libraries]\(#sdk--libraries) ## Cách API Integration hoạt động ┌─────────────────┐ ┌─────────────────┐\ │ Ứng dụng │ HTTP Request │ ClickAI │\ │ của bạn │──────────────────▶│ Platform │\ │ (Frontend/ │ │ │\ │ Backend) │◀──────────────────│ AI Processing │\ │ │ JSON / SSE │ │\ └─────────────────┘ Response └─────────────────┘ 1\. Build ứng dụng AI trong ClickAI Studio 2\. Generate API credentials (Secret Key) 3\. Call API từ ứng dụng của bạn 4\. Users tương tác qua giao diện của bạn — ClickAI xử lý AI phía sau ## Bắt đầu ### Bước 1: Truy cập API Settings 5\. Mở ứng dụng trong ClickAI Studio 6\. Nhấn "Publish" → Chọn tab "API" 7\. Xem tài liệu API tự động cho ứng dụng ### Bước 2: Tạo API Key 8\. Trong tab API, nhấn "+ Create API Key" 9\. Đặt tên mô tả (ví dụ: production-backend) 10\. Copy Secret Key — lưu trữ an toàn, chỉ hiển thị 1 lần ### Bước 3: Xác định endpoint phù hợp ClickAI có hai base URL tùy theo loại API:
Base URLDùng cho
https://clickai.ioStudio / Console APIs (quản lý apps, workspace)
https://api.clickai.ioApp Runtime APIs (chat, workflow, files)
Loại ứng dụngBaseEndpoint
Danh sách Assistantsclickai.ioGET /assistant/api/assistant/my-assistants
Text Generationapi.clickai.ioPOST /v1/completion-messages
Chatbot / Agentapi.clickai.ioPOST /v1/chat-messages
Workflowapi.clickai.ioPOST /v1/workflows/run
## Xác thực (Authentication) Mọi API request đều yêu cầu Bearer Token trong header: Authorization: Bearer {YOUR\_SECRET\_KEY}\ Content-Type: application/json 🛑 CAUTION: \*\*Bảo mật API Key:\*\* - KHÔNG BAO GIỜ đặt API Key trong code client-side (JavaScript frontend) - KHÔNG commit API Key vào Git repository - Luôn gọi API từ backend server - Lưu API Key trong environment variables - Rotate key định kỳ nếu nghi ngờ bị lộ ## API lấy danh sách Assistants Lấy danh sách các assistants (apps) thuộc workspace của bạn. ### Endpoint GET ### Query Parameters
ParameterTypeRequiredMô tả
pageinteger❌Trang hiện tại (mặc định: 1)
page_sizeinteger❌Số items mỗi trang (mặc định: 10)
modestring❌Loại app: workflow, agent-chat, chat, completion
workspace_idstring✅ID workspace của bạn
### Ví dụ — Lấy danh sách Workflow Apps curl -G '' \\\ -d 'page=1' \\\ -d 'page\_size=10' \\\ -d 'mode=workflow' \\\ -d 'workspace\_id=\' \\\ -H 'accept: application/json' \\\ -H 'authorization: Bearer \' ### Ví dụ — Lấy danh sách Agent Chat Apps curl -G '' \\\ -d 'page=1' \\\ -d 'page\_size=10' \\\ -d 'mode=agent-chat' \\\ -d 'workspace\_id=\' \\\ -H 'accept: application/json' \\\ -H 'authorization: Bearer \' ### Ví dụ — Python import requests\ \ url = " \ headers = {\ 'accept': 'application/json',\ 'authorization': 'Bearer YOUR\_ACCESS\_TOKEN',\ }\ \ params = {\ 'page': 1,\ 'page\_size': 10,\ 'mode': 'workflow',\ 'workspace\_id': 'YOUR\_WORKSPACE\_ID'\ }\ \ response = requests.get(url, headers=headers, params=params)\ data = response.json()\ \ for app in data.get('data', \[]):\ print(f"App: {app\['name']} (ID: {app\['id']})") ### Response {\ "page": 1,\ "page\_size": 10,\ "total": 5,\ "data": \[\ {\ "id": "app-abc123",\ "name": "Customer Support Bot",\ "mode": "agent-chat",\ "description": "AI hỗ trợ khách hàng",\ "created\_at": 1705395332\ }\ ]\ } 💡 TIP: Sử dụng API này để tự động lấy danh sách apps trong workspace, phục vụ cho việc tích hợp MCP hoặc quản lý apps qua script. ## API cho Text Generation App Dành cho ứng dụng tạo nội dung một lần (single-turn), không lưu lịch sử hội thoại. ### Endpoint POST ### Request Body
FieldTypeRequiredMô tả
inputsobject✅Biến đầu vào theo cấu hình app
response_modestring✅"streaming" hoặc "blocking"
userstring✅User ID duy nhất để tracking
filesarray❌Files đính kèm (nếu app hỗ trợ)
### Ví dụ — cURL curl --location --request POST '' \\\ \--header 'Authorization: Bearer YOUR-SECRET-KEY' \\\ \--header 'Content-Type: application/json' \\\ \--data-raw '{\ "inputs": {\ "text": "Viết email cảm ơn khách hàng đã mua sản phẩm"\ },\ "response\_mode": "streaming",\ "user": "user-abc-123"\ }' ### Ví dụ — Python import requests\ import json\ \ url = " \ headers = {\ 'Authorization': 'Bearer YOUR-SECRET-KEY',\ 'Content-Type': 'application/json',\ }\ \ data = {\ "inputs": {\ "text": "Viết email cảm ơn khách hàng đã mua sản phẩm"\ },\ "response\_mode": "streaming",\ "user": "user-abc-123"\ }\ \ response = requests.post(url, headers=headers, data=json.dumps(data))\ print(response.text) ### Ví dụ — JavaScript (Node.js) const axios = require('axios');\ \ const response = await axios.post(\ ' {\ inputs: { text: 'Viết email cảm ơn khách hàng' },\ response\_mode: 'streaming',\ user: 'user-abc-123'\ },\ {\ headers: {\ 'Authorization': 'Bearer YOUR-SECRET-KEY',\ 'Content-Type': 'application/json'\ }\ }\ );\ \ console.log(response.data); ### Response (Blocking Mode) {\ "id": "msg-abc123",\ "answer": "Kính gửi Quý khách hàng...",\ "created\_at": 1705395332,\ "metadata": {\ "usage": {\ "prompt\_tokens": 45,\ "completion\_tokens": 128,\ "total\_tokens": 173,\ "total\_price": "0.000346",\ "currency": "USD"\ }\ }\ } ## API cho Conversational App Dành cho Chatbot và Agent — hỗ trợ multi-turn conversation. ### Endpoint POST ### Request Body
FieldTypeRequiredMô tả
inputsobject❌Biến đầu vào (chỉ cho cuộc hội thoại mới)
querystring✅Tin nhắn của người dùng
response_modestring✅"streaming" hoặc "blocking"
conversation_idstring❌ID cuộc hội thoại (để trống = tạo mới)
userstring✅User ID duy nhất
filesarray❌Files đính kèm
### Ví dụ — cURL curl --location --request POST '' \\\ \--header 'Authorization: Bearer YOUR-SECRET-KEY' \\\ \--header 'Content-Type: application/json' \\\ \--data-raw '{\ "inputs": {},\ "query": "Xin chào, tôi cần hỗ trợ về sản phẩm",\ "response\_mode": "streaming",\ "conversation\_id": "",\ "user": "user-abc-123"\ }' ### Ví dụ — Python import requests\ import json\ \ url = " \ headers = {\ 'Authorization': 'Bearer YOUR-SECRET-KEY',\ 'Content-Type': 'application/json',\ }\ \ data = {\ "inputs": {},\ "query": "Xin chào, tôi cần hỗ trợ về sản phẩm",\ "response\_mode": "streaming",\ "conversation\_id": "",\ "user": "user-abc-123"\ }\ \ response = requests.post(url, headers=headers, data=json.dumps(data))\ print(response.text) ### Response (Blocking Mode) {\ "id": "msg-abc456",\ "conversation\_id": "conv-xyz789",\ "answer": "Xin chào! Tôi có thể giúp gì cho bạn...",\ "created\_at": 1705395332,\ "metadata": {\ "usage": {\ "prompt\_tokens": 56,\ "completion\_tokens": 89,\ "total\_tokens": 145\ }\ }\ } ## API cho Workflow App Dành cho Workflow — batch processing, pipeline execution. ### Endpoint POST ### Request Body
FieldTypeRequiredMô tả
inputsobject✅Biến đầu vào cho workflow
response_modestring✅"streaming" hoặc "blocking"
userstring✅User ID duy nhất
### Ví dụ — cURL curl --location --request POST '' \\\ \--header 'Authorization: Bearer YOUR-SECRET-KEY' \\\ \--header 'Content-Type: application/json' \\\ \--data-raw '{\ "inputs": {\ "input\_text": "Phân tích dữ liệu bán hàng Q4 2024"\ },\ "response\_mode": "streaming",\ "user": "user-abc-123"\ }' ### Response (Blocking Mode) {\ "workflow\_run\_id": "wf-run-abc123",\ "task\_id": "task-xyz789",\ "data": {\ "id": "wf-abc123",\ "workflow\_id": "wf-def456",\ "status": "succeeded",\ "outputs": {\ "result": "Kết quả phân tích..."\ },\ "total\_tokens": 456,\ "created\_at": 1705395332,\ "finished\_at": 1705395345\ }\ } ## Quản lý conversation\_id conversation\_id là khóa quan trọng nhất khi làm việc với Conversational Apps. ### Quy tắc chi tiết
Tình huốngXử lýGhi chú
Bắt đầu hội thoại mớiconversation_id: "" (để trống)Hệ thống tạo ID mới và trả về trong response
Tiếp tục hội thoạiconversation_id: "conv-xyz789"Sử dụng ID từ response trước
Truyền inputs giữa sessionDùng Conversation Variablesinputs bị bỏ qua khi có conversation_id
### Ví dụ flow hoàn chỉnh import requests\ import json\ \ BASE\_URL = " HEADERS = {\ 'Authorization': 'Bearer YOUR-SECRET-KEY',\ 'Content-Type': 'application/json',\ }\ \ \# === Lượt 1: Bắt đầu hội thoại mới ===\ response1 = requests.post(f"{BASE\_URL}/chat-messages", headers=HEADERS,\ data=json.dumps({\ "inputs": {"language": "vi"},\ "query": "Xin chào, tôi muốn hỏi về bảo hành",\ "response\_mode": "blocking",\ "conversation\_id": "", # Để trống → tạo mới\ "user": "user-001"\ })\ )\ data1 = response1.json()\ conv\_id = data1\["conversation\_id"] # Lưu lại conversation\_id\ print(f"Bot: {data1\['answer']}")\ print(f"Conversation ID: {conv\_id}")\ \ \# === Lượt 2: Tiếp tục hội thoại ===\ response2 = requests.post(f"{BASE\_URL}/chat-messages", headers=HEADERS,\ data=json.dumps({\ "inputs": {},\ "query": "Sản phẩm XYZ có bảo hành bao lâu?",\ "response\_mode": "blocking",\ "conversation\_id": conv\_id, # Truyền ID để tiếp tục\ "user": "user-001"\ })\ )\ data2 = response2.json()\ print(f"Bot: {data2\['answer']}")\ \ \# === Lượt 3: Tiếp tục ===\ response3 = requests.post(f"{BASE\_URL}/chat-messages", headers=HEADERS,\ data=json.dumps({\ "inputs": {},\ "query": "Cảm ơn bạn!",\ "response\_mode": "blocking",\ "conversation\_id": conv\_id,\ "user": "user-001"\ })\ )\ data3 = response3.json()\ print(f"Bot: {data3\['answer']}") 🚨 WARNING: Khi truyền \`conversation\_id\` đã tồn tại, mọi giá trị trong \`inputs\` sẽ bị bỏ qua. Chỉ \`query\` được xử lý. Nếu cần thay đổi biến giữa session, hãy sử dụng \*\*Conversation Variables\*\*. ## Streaming vs Blocking Response ### Blocking Mode · Response trả về toàn bộ kết quả khi xử lý xong · Phù hợp cho: Backend processing, batch jobs · Timeout mặc định: 60 giây {\ "response\_mode": "blocking"\ } ### Streaming Mode (Khuyến nghị) · Response trả về từng phần qua Server-Sent Events (SSE) · Phù hợp cho: Real-time chat, UX tốt hơn · Không giới hạn thời gian xử lý {\ "response\_mode": "streaming"\ } Xử lý SSE trong JavaScript: const eventSource = new EventSource(\ ' {\ method: 'POST',\ headers: {\ 'Authorization': 'Bearer YOUR-SECRET-KEY',\ 'Content-Type': 'application/json'\ },\ body: JSON.stringify({\ inputs: {},\ query: 'Xin chào',\ response\_mode: 'streaming',\ user: 'user-001'\ })\ }\ );\ \ // Hoặc dùng fetch API\ const response = await fetch('', {\ method: 'POST',\ headers: {\ 'Authorization': 'Bearer YOUR-SECRET-KEY',\ 'Content-Type': 'application/json'\ },\ body: JSON.stringify({\ inputs: {},\ query: 'Xin chào',\ response\_mode: 'streaming',\ conversation\_id: '',\ user: 'user-001'\ })\ });\ \ const reader = response.body.getReader();\ const decoder = new TextDecoder();\ \ while (true) {\ const { done, value } = await reader.read();\ if (done) break;\ \ const chunk = decoder.decode(value);\ const lines = chunk.split('\n');\ \ for (const line of lines) {\ if (line.startsWith('data: ')) {\ const data = JSON.parse(line.slice(6));\ if (data.event === 'message') {\ process.stdout.write(data.answer);\ }\ }\ }\ } ### SSE Event Types
EventMô tả
messagePhần nội dung phản hồi (text chunk)
agent_messagePhản hồi từ Agent mode
agent_thoughtQuá trình suy luận của Agent
message_fileFile được tạo bởi AI
message_endKết thúc tin nhắn, bao gồm metadata
tts_messageAudio chunk (nếu bật TTS)
message_replaceNội dung thay thế (content moderation)
errorLỗi xảy ra trong stream
pingKeep-alive signal
## File Upload API Upload file để sử dụng trong conversation: ### Endpoint POST ### Request (multipart/form-data)
FieldTypeMô tả
filefileFile cần upload
userstringUser ID
### Ví dụ — cURL curl --location --request POST '' \\\ \--header 'Authorization: Bearer YOUR-SECRET-KEY' \\\ \--form 'file=@"/path/to/document.pdf"' \\\ \--form 'user="user-abc-123"' ### Response {\ "id": "file-abc123",\ "name": "document.pdf",\ "size": 1024000,\ "extension": "pdf",\ "mime\_type": "application/pdf",\ "created\_by": "user-abc-123",\ "created\_at": 1705395332\ } ### Sử dụng file trong chat {\ "inputs": {},\ "query": "Tóm tắt nội dung file này",\ "response\_mode": "streaming",\ "conversation\_id": "",\ "user": "user-abc-123",\ "files": \[\ {\ "type": "document",\ "transfer\_method": "local\_file",\ "upload\_file\_id": "file-abc123"\ }\ ]\ } ## Feedback API Thu thập feedback người dùng cho từng tin nhắn: ### Endpoint POST ### Request Body {\ "rating": "like",\ "user": "user-abc-123",\ "content": "Câu trả lời rất hữu ích!"\ }
FieldValuesMô tả
rating"like", "dislike", nullĐánh giá (null = hủy đánh giá)
contentstringComment bổ sung (optional)
## Conversations API ### Lấy danh sách conversations GET ### Lấy lịch sử tin nhắn GET ### Đổi tên conversation POST {\ "name": "Hỗ trợ bảo hành sản phẩm XYZ",\ "auto\_generate": false,\ "user": "user-abc-123"\ } ### Xóa conversation DELETE ## Error Handling ### HTTP Status Codes
CodeMô tả
200Thành công
400Bad Request — Request không hợp lệ
401Unauthorized — API Key sai hoặc hết hạn
403Forbidden — Không có quyền truy cập
404Not Found — Resource không tồn tại
429Too Many Requests — Vượt quá rate limit
500Internal Server Error — Lỗi server
### Error Response Format {\ "code": "invalid\_param",\ "message": "The 'query' field is required",\ "status": 400\ } ### Xử lý lỗi — Python import requests\ import json\ \ try:\ response = requests.post(url, headers=headers, data=json.dumps(data))\ response.raise\_for\_status()\ result = response.json()\ print(result\["answer"])\ \ except requests.exceptions.HTTPError as e:\ if e.response.status\_code == 401:\ print("API Key không hợp lệ")\ elif e.response.status\_code == 429:\ print("Quá nhiều requests, thử lại sau")\ else:\ error = e.response.json()\ print(f"Lỗi: {error.get('message', 'Unknown error')}")\ \ except requests.exceptions.ConnectionError:\ print("Không thể kết nối đến ClickAI API") ## Rate Limits
Gói dịch vụRequests/phútRequests/ngày
Sandbox10010,000
Professional500100,000
Team1,000500,000
EnterpriseCustomCustom
📝 NOTE: Khi vượt rate limit, API trả về \`429 Too Many Requests\`. Implement retry logic với exponential backoff. ## SDK & Libraries ### Official SDKs
Ngôn ngữPackageInstall
Pythonclickai-sdkpip install clickai-sdk
JavaScript@clickai/sdknpm install @clickai/sdk
### Python SDK from clickai import ClickAI\ \ client = ClickAI(api\_key="YOUR-SECRET-KEY")\ \ \# Chat\ response = client.chat.create(\ query="Xin chào",\ user="user-001"\ )\ print(response.answer)\ \ \# Streaming\ for chunk in client.chat.create(\ query="Viết một bài thơ",\ user="user-001",\ stream=True\ ):\ print(chunk.answer, end="") ### JavaScript SDK import { ClickAI } from '@clickai/sdk';\ \ const client = new ClickAI({ apiKey: 'YOUR-SECRET-KEY' });\ \ // Chat\ const response = await client.chat.create({\ query: 'Xin chào',\ user: 'user-001'\ });\ console.log(response.answer);\ \ // Streaming\ const stream = await client.chat.create({\ query: 'Viết một bài thơ',\ user: 'user-001',\ stream: true\ });\ \ for await (const chunk of stream) {\ process.stdout.write(chunk.answer);\ } *📖 Xem thêm: \[MCP Server]\(./02-mcp-server.md) · \[Build]\(../01-build.md) · \[Publish]\(../02-publish.md)*