Widget Attributes

All configuration is done via data-* attributes on the <script> tag. No JavaScript API calls are needed.

Attribute Reference

Attribute	Type	Required	Default	Description
data-server	string	No	https://widget.webnav.ai	Webnav.ai backend server URL
data-base-url	string	Yes	—	The website URL to crawl and index
data-theme	string	No	light	Color theme: light or dark
data-lang	string	No	Auto-detected	UI language: zh, en, zht, ja
data-logo	string	No	Webnav.ai logo	URL of a custom logo for the widget header
data-mode	string	No	bubble	Widget display mode (fullscreen for mobile WebView)
data-exclude	string	No	—	Comma-separated routes to exclude from crawling
data-position	string	No	bottom-right	Initial bubble corner: bottom-right or bottom-left. Visitors can also drag the bubble (snaps to the nearest edge; position is remembered)
data-voice	string	No	—	Set to true to enable voice input (server-side transcription, works where Google is blocked; falls back to browser Web Speech) + reply read-out (TTS, off by default). Dictation language and auto read-out are toggleable in the widget settings panel
data-user-token	string	No	—	Signed visitor identity token for AI Actions (forwarded to your API as X-Webnav-User; also settable at runtime via window.WebnavWidget.setUserToken())

Examples

Minimal

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

Dark Theme with English UI

<script src="https://widget.webnav.ai/widget/chat-widget.js" data-base-url="https://yoursite.com" data-theme="dark" data-lang="en"></script>

Exclude Admin Routes

<script src="https://widget.webnav.ai/widget/chat-widget.js" data-base-url="https://yoursite.com" data-exclude="/admin,/login,/dashboard"></script>

Custom Logo

<script src="https://widget.webnav.ai/widget/chat-widget.js" data-base-url="https://yoursite.com" data-logo="https://yoursite.com/logo.png"></script>

AI Model (BYOK)

AI conversations run on a model you configure yourself in Dashboard → AI Model. The widget stays hidden on your site until a model configuration passes the connectivity test.

Provider	Base URL	Notes
OpenAI-compatible	Required (e.g. https://api.openai.com/v1)	Works with OpenAI, DeepSeek, Qwen, Moonshot, OpenRouter, self-hosted vLLM, and any OpenAI-compatible endpoint
Anthropic Claude	Optional (defaults to official API)	Native Messages API
Google Gemini	Optional (defaults to official API)	Native GenerateContent API

• Your API key is encrypted at rest (AES-256-GCM) and never returned to the browser.
• Saving runs a connectivity test; the widget only renders after the test passes.
• If the model does not support tool calling, AI Actions (orders / tracking / refunds) is disabled automatically while Q&A keeps working.
• Configuration changes take effect within about 1 minute.

Welcome Message (auto-open)

Pro and Enterprise plans can greet visitors automatically: the chat window opens by itself shortly after the visitor arrives, showing a configurable welcome message as the first bubble.

Configure it in Dashboard → Settings → Welcome Message (per domain):

Field	Description
Enable	Turn auto-open on/off for this domain
Text (Chinese / English)	Up to 200 chars each. Chinese shows to zh/zht visitors, English to others; a blank field falls back to the other
Image URL	Optional HTTPS image link (e.g. a support QR code), shown below the text

Behavior details:

• Opens once per visit (per browser session), 3 seconds after page load; closing it keeps it closed for the rest of the visit.
• Desktop only — on mobile the chat window is full-screen, so it never auto-opens there; visitors still see the bubble.
• The welcome message is display-only: it is not stored in the visitor's chat history and is not part of the AI conversation context.
• Changes take effect within about 1 minute (config cache).

File Attachments

Pro and Enterprise plans let visitors send files in the chat (a paperclip button appears in the toolbar):

Type	Formats	Limit	What the AI does
Images	jpg / png / webp	5 MB (auto-compressed client-side)	Sent to your model's vision capability — e.g. order screenshots. Requires a vision-capable model
Documents	pdf / docx / xlsx / txt	10 MB	Text is extracted and injected into the conversation context — works with any model

• File sending is off by default — enable it per domain in Dashboard → Domains (Pro+ only). The paperclip button only appears after you turn it on.
• One attachment per message; up to 10 uploads per visitor per hour.
• Files are stored encrypted-at-rest on S3 with a 30-day lifecycle — expired files show a "File expired" placeholder in old chat history.
• Enterprise live-chat supports two-way file transfer between visitors and agents, and tickets accept up to 3 attachments.