# Shop QA — AI 客服平台整合文件

> Shop QA 是台灣電商 AI 客服平台(知識庫型 RAG):店家上傳 FAQ/商品文件,AI 自動回答官網 Widget 與 LINE 上的顧客問題。本文件提供完整的串接指南,讓 AI 開發者直接把客服 Widget 嵌入任何網站,或直接呼叫 API。

## 快速開始(30 秒)

### 1. 建立租戶帳號取得 API Key

- 註冊:`POST https://ask.cti.app/api/auth/register` body:`{"name": "店家名", "email": "a@b.com", "password": "..."}`
- 登入:`POST https://ask.cti.app/api/auth/login` 同欄位,回傳 `api_key`(租戶識別 Key,之後所有請求帶 `X-API-Key` header)
- 或直接到網頁 `https://ask.cti.app/auth#register` 註冊,登入後在租戶後台 `https://ask.cti.app/portal` 複製 API Key

### 2. 嵌入 Widget(免寫程式,一段 script)

在網站 `</body>` 前貼上:

```html
<script src="https://ask.cti.app/static/embed.js"
        data-key="你的APIKey"
        data-title="客服小幫手"
        data-position="right"
        data-color="#4f46e5"
        data-greeting="嗨!我是客服小幫手 👋"
        data-placeholder="輸入你的問題…"
        data-avatar="https://你的頭像網址.png" defer></script>
```

即完成:右下角出現浮動客服按鈕,點開是完整對話視窗(AI 回答、多輪記憶、未命中可轉真人)。

### 3. 上傳知識庫文件

```bash
curl -X POST https://ask.cti.app/api/knowledge/upload \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -F "file=@faq.pdf"
```

支援 PDF / Word / txt / md / csv / json。上傳後背景切分向量化,幾秒到幾分鐘後可問答。也可以直接在租戶後台上傳。

## Widget 嵌入參數(embed.js)

| 屬性 | 說明 | 預設 |
|---|---|---|
| `data-key` | 租戶 API Key(必填) | — |
| `data-title` | 按鈕 title | 客服小幫手 |
| `data-position` | 按鈕位置 `left` / `right` | right |
| `data-color` | 品牌色(hex,如 `#e11d48`)按鈕/框同步換色 | #4f46e5 |
| `data-greeting` | 對話框開場白 | 平台預設 |
| `data-placeholder` | 使用者輸入框提示文字 | 輸入你的問題… |
| `data-avatar` | 客服頭像網址 | 平台預設 |

Widget 本體是 iframe:`https://ask.cti.app/widget?key=KEY&embed=1&title=...&color=...&greeting=...&placeholder=...&avatar=...`(embed.js 自動組,不需手動)。iframe 掛在 `#shopqa-btn` / `#shopqa-box` 上,想深度客製可直接引用 iframe。

客製化另一途徑:租戶後台「Widget 客製化」存檔後,後台嵌入碼自動帶上 data-* 參數。

## 聊天 API

### POST https://ask.cti.app/api/chat

Request headers:`X-API-Key: 你的APIKey`

```json
{
  "question": "運費怎麼算?",
  "history": [
    {"role": "user", "content": "之前問的內容"},
    {"role": "assistant", "content": "之前的回答"}
  ],
  "session_id": "可選,同瀏覽器/同 session 傳相同值以記錄對話歷史"
}
```

Response:

```json
{
  "answer": "滿 799 元免運費(台灣本島),未滿收取 80 元運費…",
  "sources": [
    {"title": "運送政策.pdf", "text": "…", "score": 0.85}
  ],
  "confidence": 0.85,
  "known": true
}
```

- `known=true` = 知識庫命中,`false` = 未命中(未命中會記錄,租戶可在後台補知識)
- `sources` 為參考來源(標題/內文/相關度),可顯示給顧客增加可信度
- 依方案有每月訊息額度,超額回 429

## 知識庫 API

- `GET https://ask.cti.app/api/knowledge` → 列出文件:`[{"doc_id","title","chunks","status","created_at"}]`
- `POST https://ask.cti.app/api/knowledge/upload` → multipart `file`,回 `{"doc_id","title","status":"processing"}`
- `DELETE https://ask.cti.app/api/knowledge/{doc_id}` → 刪除文件

支援格式:pdf / docx / txt / md / csv / json。單檔上限依方案(免費 5MB),文件數額度依方案(免費 5 份)。

## LINE 串接(可選)

租戶在後台 `https://ask.cti.app/portal` 填入 LINE Messaging API 的 Channel Secret 與 Access Token,取得 Webhook URL:

```
https://ask.cti.app/api/webhook/line/{tenant_id}
```

貼到 LINE Developers → Messaging API → Webhook URL,即完成 LINE 客服自動回覆(簽章驗證、AI 回答、未命中記錄全內建)。

## 方案與額度

- 免費:100 則/月、5 份文件、5MB/檔
- 標準 NT$990:5,000 則/月、50 份文件、20MB/檔
- 專業 NT$2,990:30,000 則/月、200 份文件、50MB/檔
- 查方案:`GET https://ask.cti.app/api/billing/plans`(公開);升級:後台刷卡/ATM/超商(綠界金流)
- 查額度:`GET https://ask.cti.app/api/tenant/quota`(X-API-Key)回 `{"messages_used","messages_limit","docs_used","docs_limit","plan"}`

## 其他端點

- `POST https://ask.cti.app/api/handoff` body:`{"question","session_id"}` → 顧客要求真人時建立轉接單(`{"handoff_id"}`)
- `GET https://ask.cti.app/api/tenant/widget-config` / `PUT https://ask.cti.app/api/tenant/widget-config` → Widget 客製化設定(租戶)
- `GET https://ask.cti.app/api/tenant/conversations` → 對話紀錄列表(租戶)
- `GET https://ask.cti.app/api/tenant/me` → 租戶資料
- 管理端點(`/api/admin/*`、`/api/tenants`、`/api/stats`、`/api/unanswered`)需管理員權限,一般不開放給外部串接。

## 頁面導覽

- `https://ask.cti.app/` — 產品 landing(含 DEMO widget 可直接試用)
- `https://ask.cti.app/auth` — 註冊/登入
- `https://ask.cti.app/portal` — 租戶後台(知識庫上傳、嵌入碼、Widget 客製化、LINE 串接、對話紀錄、方案升級)
- `https://ask.cti.app/admin` — 平台管理後台(不開放)
- `https://ask.cti.app/blog` — 電商經營/AI 客服文章
- `https://ask.cti.app/widget` — Widget 本體頁(供 iframe 嵌入)

## 完整串接範例

### React / Next.js(在 layout 或 App 元件加)

```tsx
// components/ChatWidget.tsx
export default function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://ask.cti.app/static/embed.js";
    s.setAttribute("data-key", process.env.NEXT_PUBLIC_SHOPQA_KEY!);
    s.setAttribute("data-color", "#e11d48");
    s.setAttribute("data-greeting", "嗨!我是 XX 商店客服 👋");
    s.defer = true;
    document.body.appendChild(s);
  }, []);
  return null;
}
```

### Vanilla JS(直接呼叫聊天 API)

```js
async function ask(question, history = []) {
  const res = await fetch("https://ask.cti.app/api/chat", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "你的APIKey",
    },
    body: JSON.stringify({ question, history, session_id: localStorage.getItem("sq_session") }),
  });
  return res.json(); // { answer, sources, confidence, known }
}
```

### cURL

```bash
curl -X POST https://ask.cti.app/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 你的APIKey" \
  -d '{"question": "退貨流程是什麼?"}'
```

## 備註

- 所有 API 皆 HTTPS;租戶 API 認證 = `X-API-Key` header(由註冊/登入取得)
- 對話歷史:widget 每次開啟產生 session_id(同瀏覽器同租戶),租戶/管理員可在後台查完整對話
- 未命中問題(`known=false`)自動記錄,租戶可一鍵補知識,AI 越用越聰明
- 本文件是給 AI 閱讀的整合指南;完整商業說明見 `https://ask.cti.app/` landing