Widget 属性

通过 <script> 标签的 data-* 属性配置 Widget 行为。

属性列表

属性	必填	说明	默认值	示例
`data-server`	否	后端服务地址	同域	`https://widget.webnav.ai`
`data-base-url`	否	网站 URL，支持逗号分隔多个（第一个为主域名）	`window.location.origin`	`https://a.com,https://b.com`
`data-theme`	否	初始主题	`light`	`dark`
`data-lang`	否	强制语言	自动检测	`zh` / `en` / `ja` / `ko`
`data-logo`	否	自定义 Logo URL	网站 favicon	`https://yoursite.com/logo.png`
`data-mode`	否	全屏模式（移动端 WebView）	正常	`fullscreen`
`data-exclude`	否	不显示客服的路由	无	`/admin/*,/login`
`data-position`	否	气泡初始位置：`bottom-right` 或 `bottom-left`；访客也可直接拖动气泡（松手吸附最近边缘，位置自动记住）	`bottom-right`	`bottom-left`
`data-voice`	否	设为 `true` 开启语音输入（服务端转写，国内可用，失败时降级浏览器 Web Speech）+ 回复朗读（TTS，默认关闭）。听写语言与自动朗读可在 widget 设置面板切换	无	`true`
`data-user-token`	否	访客身份令牌（用于 AI Actions，转发给你的 API 作 `X-Webnav-User`；也可运行时用 `window.WebnavWidget.setUserToken()` 设置）	无	`eyJ...`

主题优先级

data-theme 属性 > localStorage 用户选择 > 默认 light

语言检测优先级

data-lang 属性 > <html lang> > navigator.language > 默认 en

多域名抓取

data-base-url 支持逗号分隔多个 URL，AI 会同时学习所有配置域名的内容：

html

<script
  src="https://widget.webnav.ai/widget/chat-widget.js"
  data-base-url="https://yoursite.com,https://blog.yoursite.com,https://help.another.com"
></script>

第一个 URL 的域名作为主域名（用于缓存目录名和白名单校验）
每个域名会自动推导并抓取其 docs. 子域名
所有内容合并到同一个缓存中，AI 可以跨域名回答

自动 docs 子域名发现

配置 https://example.com 时，系统会自动抓取：

https://example.com — 主站
https://docs.example.com — 文档站（自动推导）

无需手动配置，开箱即用。

路由排除规则

精确匹配：/login 匹配 /login 和 /login/
通配符：/admin/* 匹配 /admin/ 下所有路径
多个用逗号分隔：/admin/*,/login,/checkout/*

AI 模型（BYOK）

AI 对话运行在你自己在 控制台 → 模型配置 中配置的模型上。模型配置通过连通性测试之前，widget 在你的网站上保持隐藏。

供应商	Base URL	说明
`OpenAI 兼容`	必填（如 `https://api.openai.com/v1`）	支持 OpenAI、DeepSeek、通义千问、Moonshot、OpenRouter、自建 vLLM 等所有 OpenAI 兼容端点
`Anthropic Claude`	可选（默认官方 API）	原生 Messages API
`Google Gemini`	可选（默认官方 API）	原生 GenerateContent API

API Key 使用 AES-256-GCM 加密存储，不会回传到浏览器。
保存时执行连通性测试，测试通过后 widget 才会显示。
若模型不支持工具调用，AI Actions（下单/查物流/退款）自动停用，问答功能不受影响。
配置变更约 1 分钟内生效。

歡迎訊息（自動展開）

Pro 及 Enterprise 方案可自動迎接訪客：訪客進站後聊天窗會自動展開，並以第一則氣泡顯示可設定的歡迎訊息。

在 控制台 → 設定 → 歡迎訊息 中按網域設定：

欄位	說明
啟用	開啟/關閉此網域的自動展開
文字（中文/英文）	各最多 200 字。`zh`/`zht` 訪客顯示中文，其它語言顯示英文；留空回落另一份
圖片連結	可選的 HTTPS 圖片連結（如客服 QR Code），顯示在文字下方

行為細節：

每次來訪只自動展開一次（以瀏覽器 session 計），頁面載入 3 秒後展開；訪客關閉後本次來訪不再彈出。
僅桌面端生效 —— 行動端聊天窗為全螢幕，不會自動展開，訪客仍可看到氣泡自行點開。
歡迎訊息為純展示內容：不會寫入訪客的聊天歷史，也不會作為 AI 對話上下文。
設定變更約 1 分鐘內生效（設定快取）。

檔案附件

Pro 及 Enterprise 方案的訪客可在對話中傳送檔案（工具列會出現迴紋針按鈕）：

類型	格式	限制	AI 如何處理
圖片	jpg / png / webp	5 MB（前端自動壓縮）	傳給模型的視覺能力——如訂單截圖；需模型支援視覺
文件	pdf / docx / xlsx / txt	10 MB	抽取文字注入對話上下文——任何模型皆可用

檔案傳送預設關閉——需在 控制台 → 網域管理 中按網域開啟（僅 Pro+）。開啟後迴紋針按鈕才會顯示。
每則訊息 1 個附件；每位訪客每小時最多上傳 10 個。
檔案存於 S3 並設 30 天生命週期自動刪除——過期檔案在歷史記錄中顯示「檔案已過期」。
Enterprise 線上客服支援訪客與客服雙向傳檔；工單最多可帶 3 個附件。

Widget 属性 ​

属性列表 ​

主题优先级 ​

语言检测优先级 ​

多域名抓取 ​

自动 docs 子域名发现 ​

路由排除规则 ​

AI 模型（BYOK） ​

歡迎訊息（自動展開） ​

檔案附件 ​