AI Chat API

Quick Reference

• Base URL: https://insights.omisell.com/api/v1/ai
• Auth: Authorization: Omi <token>
• Content-Type: application/json

Endpoints Overview

Method	Endpoint	Mô tả	Auth
POST	/api/v1/ai/chat	Gửi câu hỏi AI	Yes

---

POST /api/v1/ai/chat

Gửi câu hỏi bằng ngôn ngữ tự nhiên. Backend phân tích intent, generate SQL, execute, và trả kết quả kèm visualization hints.

Request Body

Field	Type	Required	Mô tả
question	string	Yes	Câu hỏi bằng ngôn ngữ tự nhiên
insight_code	string	No	Mã insight (nếu muốn context cụ thể)
granularity	string	No	Mức thời gian: day, week, month, quarter, year
filters	Record<string, unknown>	No	Bộ lọc bổ sung

Source: (src/app/shared/models/api.models.ts — AIChatRequest)

Response Body (200 OK)

Field	Type	Mô tả
mode	'insight' | 'free_query'	Chế độ xử lý
intent	string	Intent được nhận diện
explanation	string	Giải thích kết quả (Markdown)
data	DataRow[]	Dữ liệu trả về
chart_hint	ChartHint?	Gợi ý visualization
query_code	string?	Mã insight (nếu mode=insight)
query_name	string?	Tên insight
sql_used	string?	Câu SQL đã thực thi
alerts	Alert[]?	Cảnh báo (info/warning/critical)
execution_status	'success' | 'blocked' | 'error'	Trạng thái thực thi
execution_time_ms	number?	Thời gian xử lý (ms)
error_message	string?	Thông báo lỗi (nếu error)

Source: (src/app/shared/models/api.models.ts — AIChatResponse)

Sub-types

ChartHint:

Field	Type	Mô tả
chart_type	ChartType	bar, line, pie, stacked_bar, grouped_bar, area, heatmap
x_column	string	Cột trục X
y_columns	string[]	Các cột trục Y
title	string	Tiêu đề biểu đồ

Alert:

Field	Type	Mô tả
level	'info' | 'warning' | 'critical'	Mức độ
message	string	Nội dung cảnh báo

Examples

cURL

curl -X POST "https://insights.omisell.com/api/v1/ai/chat" \
  -H "Authorization: Omi <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Doanh thu 7 ngày qua"
  }'

JavaScript (fetch)

const response = await fetch('https://insights.omisell.com/api/v1/ai/chat', {
  method: 'POST',
  headers: {
    'Authorization': `Omi ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: 'Doanh thu 7 ngày qua',
  }),
});
const data = await response.json();
// data.explanation, data.data, data.chart_hint

Response Example (Success)

{
  "mode": "insight",
  "intent": "revenue_overview",
  "explanation": "Doanh thu 7 ngày qua theo ngày...",
  "data": [
    { "date": "2026-04-08", "revenue": 15200000, "orders": 48 },
    { "date": "2026-04-09", "revenue": 18500000, "orders": 52 }
  ],
  "chart_hint": {
    "chart_type": "line",
    "x_column": "date",
    "y_columns": ["revenue"],
    "title": "Doanh thu 7 ngày qua"
  },
  "query_code": "O1-01",
  "query_name": "Tổng quan doanh số đa kênh",
  "alerts": [
    { "level": "info", "message": "Doanh thu tăng 12% so với tuần trước" }
  ],
  "execution_status": "success",
  "execution_time_ms": 450
}

Source: (src/app/core/services/api.service.ts:42-44)

Liên kết

• API Index — Tổng quan API
• Insights API — Execute insight trực tiếp
• SOP: AI Chat — Hướng dẫn sử dụng