Tài liệu API

API Chatbot cho phép các ứng dụng bên ngoài tích hợp với bất kỳ chatbot nào bạn tạo. Mỗi chatbot có token API riêng để xác thực yêu cầu và xác định chatbot nào xử lý cuộc hội thoại.

Xác thực

Tất cả yêu cầu API phải kèm theo token API hợp lệ. Token được gắn với một chatbot cụ thể — mỗi token chỉ có thể giao tiếp với chatbot mà nó được tạo ra.

Cách 1 — Header Authorization (khuyến nghị)

httpCopy
Authorization: Bearer veribox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cách 2 — Header X-API-Key

httpCopy
X-API-Key: veribox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Bảo mật: Token API chỉ hiển thị một lần khi tạo. Hãy lưu trữ trong biến môi trường, không bao giờ đặt trong mã nguồn. Token có thể bị thu hồi bất cứ lúc nào từ cài đặt chatbot.

Yêu cầu gói dịch vụ: Nền tảng API khả dụng từ gói Standard trở lên. Gói Starter và Basic không thể tạo token API.

Quản lý token

Bắt đầu nhanh

1. Mở bảng điều khiển chatbot và vào trang Nền tảng.
2. Thêm nền tảng API.
3. Tạo token API mới và sao chép lại (chỉ hiển thị một lần).
4. Sử dụng token trong header Authorization của mọi yêu cầu.

bashCopy
curl -X POST https://your-domain.com/api/v1/chat \
  -H "Authorization: Bearer veribox_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, what can you help me with?",
    "format": "markdown"
  }'

Các endpoint

POST/v1/chat

Gửi tin nhắn và nhận toàn bộ phản hồi cùng lúc. Phù hợp cho tích hợp đơn giản khi không cần streaming.

Nội dung yêu cầu

cURLNode.jsPythonPHPGo
Copy
curl -X POST https://your-domain.com/api/v1/chat \
  -H "Authorization: Bearer veribox_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "format": "markdown",
    "external_user_id": "user_12345"
  }'

Phản hồi 200 OK

jsonCopy
{
  "error": 0,
  "error_message": "",
  "data": {
    "message": "Our business hours are **Monday-Friday, 9am-6pm**.",
    "conversation_id": 42,
    "format": "markdown",
    "usage": {
      "prompt_tokens": 850,
      "completion_tokens": 120,
      "total_tokens": 970
    }
  }
}

POST/v1/chat/stream

Gửi tin nhắn và nhận phản hồi dưới dạng luồng Server-Sent Events (SSE). Phản hồi được truyền từng token khi được tạo ra.

Nội dung yêu cầu giống hệt /v1/chat. Phản hồi sử dụng text/event-stream.

cURLNode.jsPythonPHPGo
Copy
# -N tắt bộ đệm đầu ra để token hiển thị ngay lập tức
curl -N -X POST https://your-domain.com/api/v1/chat/stream \
  -H "Authorization: Bearer veribox_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain your return policy in detail.", "format": "markdown"}'

Luồng phản hồi SSE

data: {"type":"conversation","conversation_id":42}

data: {"type":"delta","content":"Our return"}

data: {"type":"delta","content":" policy allows"}

data: {"type":"delta","content":" returns within 30 days..."}

data: {"type":"formatted","content":"<p>Our return policy allows ...</p>","format":"html"}

data: [DONE]

Lưu ý: Với định dạng html và plain_text, các sự kiện delta chứa các đoạn Markdown thô. Sự kiện formatted cuối cùng được gửi trước [DONE] với nội dung đã được chuyển đổi hoàn chỉnh.

POST/v1/conversations

Tạo cuộc hội thoại mới một cách tường minh. Hữu ích khi bạn muốn khởi tạo cuộc hội thoại mới cho một phiên người dùng cụ thể trước khi gửi tin nhắn.

Nội dung yêu cầu

cURLNode.jsPython
Copy
curl -X POST https://your-domain.com/api/v1/conversations \
  -H "Authorization: Bearer veribox_your_token" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "session_abc123"}'

Phản hồi 200 OK

jsonCopy
{
  "error": 0,
  "error_message": "",
  "data": {
    "conversation_id": 99,
    "chatbot_id": "bot_xxxxxxxx",
    "status": "active",
    "created_at": "2026-03-05T10:00:00Z"
  }
}

GET/v1/conversations/:conversation_id/messages

Lấy tất cả tin nhắn của một cuộc hội thoại. Chỉ có thể truy cập các cuộc hội thoại thuộc chatbot đã xác thực.

cURLNode.jsPython
Copy
curl https://your-domain.com/api/v1/conversations/42/messages \
  -H "Authorization: Bearer veribox_your_token"

Phản hồi 200 OK

jsonCopy
{
  "error": 0,
  "error_message": "",
  "data": {
    "messages": [
      {
        "id": 1,
        "role": "user",
        "content": "What are your business hours?",
        "created_at": "2026-03-05T10:00:00Z"
      },
      {
        "id": 2,
        "role": "assistant",
        "content": "Our business hours are **Monday-Friday, 9am-6pm**.",
        "created_at": "2026-03-05T10:00:01Z"
      }
    ]
  }
}

Streaming (SSE)

Endpoint streaming sử dụng Server-Sent Events (SSE). Mỗi sự kiện là một dòng bắt đầu bằng data: .

Các loại sự kiện

Đọc SSE bằng JavaScript

javascriptCopy
async function streamChat(token, message) {
  const response = await fetch("https://your-domain.com/api/v1/chat/stream", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message, format: "markdown" }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";
    for (const line of lines) {
      if (!line.startsWith("data: ")) continue;
      const payload = line.slice(6).trim();

      if (payload === "[DONE]") {
        console.log("Stream complete");
        return;
      }

      const event = JSON.parse(payload);
      if (event.type === "delta") {
        process.stdout.write(event.content); // hoặc thêm vào DOM
      } else if (event.type === "conversation") {
        console.log("Conversation ID:", event.conversation_id);
      }
    }
  }
}

Định dạng phản hồi

Trường format kiểm soát cách văn bản phản hồi của chatbot được trả về. Engine RAG luôn tạo Markdown nội bộ; API chuyển đổi trước khi trả về.

Lưu ý về streaming: Trong chế độ streaming, các sự kiện delta luôn chứa các đoạn Markdown thô bất kể định dạng. Với html hoặc plain_text, văn bản đã chuyển đổi hoàn chỉnh được gửi trong sự kiện formatted ngay trước [DONE].

Mã lỗi

Tất cả phản hồi tuân theo cấu trúc chuẩn. Trường error khác 0 cho biết có lỗi xảy ra.

jsonCopy
{
  "error": 1,
  "error_message": "Unauthorized: invalid or expired API token",
  "data": null
}