Chatbot API

Tổng quan

Chatbot API cho phép chạy Heliuos Chat như một headless engine bên trong sản phẩm của bạn. Mọi câu trả lời đều được tạo ra từ knowledge base của bạn — không phải từ internet. Bạn kiểm soát data, persona và nơi chat xuất hiện.

Base URL

https://api.heliuos.com

Xác thực

Mọi request đều yêu cầu API key truyền qua header x-api-key. Key được tạo từ Heliuos Dashboard.

Mỗi key mang theo một persona quyết định cách AI phản hồi, và một tập quyền — chatbot endpoints yêu cầu quyền chat.

Personas

general mặc định

Trung lập, súc tích, chính xác. Dùng khi key không cấu hình persona riêng.

sales

Phong cách tư vấn. Đặt câu hỏi khám phá nhu cầu, xử lý phản đối.

support

Kiên nhẫn, đồng cảm. Hướng dẫn người dùng từng bước.

curl https://api.heliuos.com/v1/chatbot/sessions \
  -H "x-api-key: heliuos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Sessions

Session lưu lịch sử hội thoại. Tạo session trước khi gửi tin nhắn đầu tiên, sau đó truyền id trả về làm sessionId trong mọi query. API tự động tải lịch sử từ session mỗi request.

Tạo session

POST /v1/chatbot/sessions

Tạo một session hội thoại mới.

Body parameters

title string không bắt buộc

Nhãn cho session. Mặc định là "Chatbot session".

Trả về

Session object với id, title và createdAt. Lưu lại id — cần dùng trong mọi query.

curl -X POST https://api.heliuos.com/v1/chatbot/sessions \
  -H "x-api-key: heliuos_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Ho tro don hang #42"}'

{
  "success": true,
  "data": {
    "id": "sess_abc123",
    "title": "Ho tro don hang #42",
    "createdAt": "2026-06-10T08:00:00.000Z"
  }
}

Danh sách session

GET /v1/chatbot/sessions

Trả về tất cả session của API key hiện tại, mới nhất trước. Hỗ trợ cursor pagination.

Query parameters

cursor string không bắt buộc

Con trỏ phân trang từ meta.nextCursor của response trước.

limit number không bắt buộc

Số lượng tối đa mỗi trang.

curl "https://api.heliuos.com/v1/chatbot/sessions?limit=20" \
  -H "x-api-key: heliuos_xxxx"

{
  "success": true,
  "data": [
    {
      "id": "sess_abc123",
      "title": "Ho tro don hang #42",
      "createdAt": "2026-06-10T08:00:00.000Z"
    }
  ],
  "meta": {
    "nextCursor": "sess_xyz789",
    "hasMore": true
  }
}

Lấy tin nhắn

GET /v1/chatbot/sessions/{sessionId}

Trả về toàn bộ lịch sử tin nhắn của một session. Dùng để khôi phục hội thoại cũ trong UI.

Path parameters

sessionId string bắt buộc

Session ID từ Tạo session.

curl "https://api.heliuos.com/v1/chatbot/sessions/sess_abc123" \
  -H "x-api-key: heliuos_xxxx"

{
  "success": true,
  "data": {
    "id": "sess_abc123",
    "messages": [
      { "role": "user", "content": "Chinh sach hoan tien la gi?" },
      { "role": "assistant", "content": "Heliuos ho tro hoan tien trong 30 ngay..." }
    ]
  }
}

Xóa session

DELETE /v1/chatbot/sessions/{sessionId}

Xóa vĩnh viễn session và toàn bộ tin nhắn. Không thể hoàn tác.

Path parameters

sessionId string bắt buộc

Session ID cần xóa.

curl -X DELETE "https://api.heliuos.com/v1/chatbot/sessions/sess_abc123" \
  -H "x-api-key: heliuos_xxxx"

{
  "success": true,
  "data": { "message": "Session deleted" }
}

Query

Gửi tin nhắn và nhận câu trả lời từ knowledge base. Hai chế độ: đồng bộ (chờ toàn bộ câu trả lời) hoặc streaming (nhận từng token theo thời gian thực qua SSE).

Gửi tin nhắn

POST /v1/chatbot/query

Trả về câu trả lời đầy đủ sau khi pipeline hoàn tất. Phù hợp cho server-side integration không cần output theo thời gian thực.

Body parameters

message string bắt buộc

Tin nhắn của người dùng.

sessionId string bắt buộc

Session ID từ Tạo session. Lịch sử hội thoại được tải tự động.

format "markdown" | "text" không bắt buộc

Định dạng câu trả lời. Mặc định "markdown". Dùng "text" nếu muốn chuỗi thuần.

Trả về

Response với text, images tùy chọn (khi knowledge base có ảnh liên quan), token usage và sessionId.

curl -X POST https://api.heliuos.com/v1/chatbot/query \
  -H "x-api-key: heliuos_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Chinh sach doi tra hang la gi?",
    "sessionId": "sess_abc123"
  }'

{
  "success": true,
  "data": {
    "text": "Doi tra duoc chap nhan trong vong 30 ngay...",
    "images": [
      {
        "url": "https://cdn.heliuos.com/img/return-flow.png",
        "alt": "So do quy trinh doi tra"
      }
    ],
    "usage": {
      "promptTokens": 512,
      "completionTokens": 128,
      "totalTokens": 640
    },
    "sessionId": "sess_abc123"
  }
}

Streaming response

POST /v1/chatbot/query/stream

Body giống Gửi tin nhắn. Phản hồi dưới dạng luồng Server-Sent Events — token đến theo thời gian thực khi model tạo ra.

Body parameters

message string bắt buộc

Tin nhắn của người dùng.

sessionId string bắt buộc

Session ID. Lịch sử được tải tự động.

format "markdown" | "text" không bắt buộc

Định dạng câu trả lời. Mặc định "markdown".

Chuỗi SSE events

event: status

Pipeline bắt đầu. Data: {"status":"generating"}

data: (không có tên event)

Mỗi đoạn text. Data: {"type":"chunk","content":"..."}

event: metadata

Stream hoàn tất. Data: {"model":"claude-...","images":0}

event: done

Kết thúc kết nối. Data: [DONE]

event: error

Pipeline gặp lỗi. Data: {"message":"..."}

curl -X POST https://api.heliuos.com/v1/chatbot/query/stream \
  -H "x-api-key: heliuos_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Tom tat bao cao Q1",
    "sessionId": "sess_abc123"
  }'

event: status
data: {"status":"generating"}

data: {"type":"chunk","content":"Doanh thu Q1 dat "}

data: {"type":"chunk","content":"4,2 trieu USD, tang 18%."}

event: metadata
data: {"model":"claude-sonnet-4-6","images":0}

event: done
data: [DONE]

const res = await fetch(
  'https://api.heliuos.com/v1/chatbot/query/stream',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'heliuos_xxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message, sessionId }),
  }
);

const reader = res.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 raw = line.slice(5).trim();
    if (raw === '[DONE]') break;
    const { type, content } = JSON.parse(raw);
    if (type === 'chunk') process.stdout.write(content);
  }
}

Lỗi

Mọi lỗi trả về success: false với object error chứa code (machine-readable) và message (human-readable).

Mã lỗi

Status	Code	Nguyên nhân
400	BAD_REQUEST	Thiếu hoặc sai `message` / `sessionId`
401	UNAUTHORIZED	Thiếu hoặc sai API key
403	FORBIDDEN	API key không có quyền `chat`
500	INTERNAL_ERROR	Pipeline gặp lỗi

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "message is required"
  }
}

const data = await res.json();

if (!data.success) {
  switch (data.error.code) {
    case 'UNAUTHORIZED':
      // chuyen huong den trang cau hinh key
      break;
    case 'BAD_REQUEST':
      console.error(data.error.message);
      break;
  }
}

Bắt đầu nhanh

Tạo session, gửi tin nhắn và in kết quả — chưa tới 20 dòng code.

const API_KEY = 'heliuos_your_key_here';
const BASE    = 'https://api.heliuos.com';

const h = { 'x-api-key': API_KEY, 'Content-Type': 'application/json' };

// 1. Tao session
const { data: session } = await fetch(`${BASE}/v1/chatbot/sessions`, {
  method: 'POST',
  headers: h,
  body: JSON.stringify({ title: 'Chat cua toi' }),
}).then(r => r.json());

// 2. Gui tin nhan
const { data } = await fetch(`${BASE}/v1/chatbot/query`, {
  method: 'POST',
  headers: h,
  body: JSON.stringify({
    message: 'Cac goi gia cua ban la gi?',
    sessionId: session.id,
  }),
}).then(r => r.json());

console.log(data.text);
// → "Chung toi co ba goi: Starter, Pro va Enterprise..."