Chatbot Props

必填​

Prop	型別	說明
config	ClientConfig	Client 設定，至少要有 botProviderEndpoint。詳見下方
customChannelId	string	唯一識別對話頻道的 ID（通常用 user id / session id）

基本顯示​

Prop	型別	預設	說明
title	string	—	Header 標題（Bot 名稱列，與 channelTitle 不同）
avatar	string	—	Bot 頭像 URL
botTypingPlaceholder	string	—	已棄用（0.3.x 起），不再渲染任何內容。執行中提示改為自動顯示、與連線狀態綁定的 running indicator（無需設定）
locale	'en-US' | 'ja-JP' | 'zh-TW'	'en-US'	內建文案語系：工具呼叫標籤、群組摘要、任務 / 子代理面板。見 多語系
channelTitle	string | null	—	對話頂端標題列的初始值（通常取自 channelMetadata()），會隨後端 title.update 動態更新。見 對話標題
inputPlaceholder	string	—	輸入框 placeholder
fullScreen	boolean	false	是否以全螢幕模式渲染
className	string	—	外層 className
style	CSSProperties	—	外層 inline style
loadingComponent	ReactNode	—	自訂載入中畫面

功能開關​

Prop	型別	說明
enableUpload	boolean	啟用圖片上傳按鈕
enableDocumentUpload	boolean	啟用文件上傳按鈕
allowedImageMimeTypes	string[]	限制 enableUpload 可上傳的圖片 MIME 類型；給值即完全覆蓋預設清單。見 檔案上傳
allowedDocumentMimeTypes	string[]	限制 enableDocumentUpload 可上傳的文件 MIME 類型；給值即完全覆蓋預設清單。見 檔案上傳
enableExport	boolean	啟用對話匯出
enableLoadConfigFromService	boolean	從 bot provider 讀取遠端設定（例如 embedConfig）
maintainConnectionWhenClosed	boolean	關閉視窗時保留 SSE 連線
keepConnectionOnUnmount	boolean	預設 false；元件 unmount 時保留進行中的 SSE run 讓它在後端跑完（與 maintainConnectionWhenClosed 的「關閉視窗」情境不同）
autoResetChannel	boolean	預設 true。0.3.x 起 mount 會先查 channel metadata：後端已存在的 channel 一律會被還原（重播歷史），不受此設定影響；只有 channel 尚不存在時，false 才會略過 RESET_CHANNEL 以保留 initMessages。見 自動重置 Channel
userIdentityHint	string	使用者身分識別提示。設定後所有請求（SSE、上傳）會帶上 X-ASGARD-USER-IDENTITY-HINT header

詳見 功能開關 Demo。

初始訊息與事件​

Prop	型別	說明
initMessages	ConversationMessage[]	初始化時就載入的對話紀錄
onSseMessage	(response, { conversation }) => void	每一個 SSE 事件的 callback
onSseError	(error: unknown) => void	SSE 錯誤 callback
onBeforeSendMessage	(params) => params	送出前修改 message params。見 before-send-message
onMessageSent	() => void	訊息送出後 callback
onChannelReady	() => void	Channel 就緒可收訊息時觸發（此時 ref 已更新，可在 callback 內用 ref 送開場訊息）；resetChannel 後會再次觸發
onReset	() => void	Reset channel 時觸發
onClose	() => void	Chatbot 關閉時觸發

客製渲染​

Prop	型別	說明
theme	Partial<AsgardThemeContextValue>	主題設定，見 主題 Demo
renderHeader	() => ReactNode	完全取代預設 header，見 Custom Header
renderFooter	() => ReactNode	完全取代預設 footer（輸入框區），見 Custom Footer
renderMenu	() => ReactNode	在 body 和 footer 之間插入選單，見 Render Menu
renderTitle	(props) => ReactNode	完全取代對話頂端標題列（props 為 { title, renderDefault }，回傳 null 隱藏）。搭配 untitledLabel（未命名時的字，預設 新對話）、channelTitleHidden（直接隱藏）。見 對話標題
renderMessageContent	(props) => ReactNode	完全取代訊息內容渲染，見 Custom Renderer
renderToolCallGroup	(props) => ReactNode	自訂或隱藏 Tool Call Group，見 工具呼叫
errorMessageRenderer	(message) => ReactNode	自訂錯誤訊息呈現
customActions	ReactNode[]	塞到 header 右側的自訂按鈕
footerEndActions	ReactNode[]	塞到 footer input row 最右邊（send / mic 之後）的自訂節點，見 Footer 尾巴按鈕
messageActions	(message) => MessageActionConfig[]	每一則 bot 訊息下方的 action 按鈕
onMessageAction	(actionId, message) => void	點擊 message action 時的 callback
onTemplateBtnClick	(payload, eventName, raw) => void	Button template 的 emit action callback
onErrorClick	(message) => void	點擊錯誤訊息時的 callback
defaultLinkTarget	'_blank' | '_self' | '_parent' | '_top'	訊息中連結的預設 target
hideRunChrome	boolean	不渲染內建的停靠 Task / 子代理面板，改由你自行擺放，見 自行停靠面板

Sandbox​

Prop	型別	說明
fileExplorer	'builtin' | 'off'	內建 File Explorer 側欄，預設 'builtin'；設 'off' 改由你擺放 <FileExplorerPanel>。見 File Explorer
autoRevealOnOpenFileCard	boolean	open-file 卡片抵達時是否自動展開側欄，預設 true；檔案有未存檔的修改時會抑制
fileExplorerBasePath	string	覆寫檔案樹根目錄的絕對路徑，取代 sandbox 的 workingDirectory
onSandboxOpenBrowser	(sandboxName) => void	接手 sandbox://<name>/open-browser 卡片；有給就以你的為準。見 交接卡
onSandboxOpenFile	(sandboxName, absolutePath) => void	接手 sandbox://<name>/open-file 卡片。注意這是相加不是取代——內建側欄仍會被拉開，除非同時設 fileExplorer="off"
sandboxBrowserOpenTarget	'_blank' | '_self' | '_parent' | '_top'	預設 open-browser 處理器開分頁的目標，預設 '_blank'

認證​

Prop	型別	說明
authState	AuthState	目前的驗證狀態，見下方說明與 Auth Demo
onApiKeySubmit	(apiKey: string) => Promise<void>	使用者送出 API key 時觸發
onAuthError	(error: { isAuthError, isBotProviderError, errorDetail }) => void	認證錯誤 callback

AuthState 的可能值：'loading' | 'needApiKey' | 'authenticated' | 'error' | 'invalidApiKey' | 'subscriptionExpired' | 'botNotFound'

ClientConfig 欄位​

config prop 的型別是 ClientConfig：

欄位	型別	說明
botProviderEndpoint	string	必填。Bot provider base URL
endpoint	string	@deprecated。改用 botProviderEndpoint
apiKey	string	靜態 API key
customHeaders	Record<string, string>	自訂 HTTP headers（例如 Authorization: Bearer ...）
userIdentityHint	string	使用者身分識別提示，自動帶上 X-ASGARD-USER-IDENTITY-HINT header（同頂層 prop）
transformSsePayload	(payload) => payload	送出前變更 SSE payload
debugMode	boolean	開啟 debug log
onRunInit / onMessage / onToolCall / onProcess / onRunDone / onRunError	EventHandler	對應各 SSE event 的 handler

將 botProviderEndpoint 設為字串 "skip" 可以進入 preview mode： 不會建立實際連線，只渲染 initMessages，本站許多 demo 都使用這個模式。

也看看​

• useChannel hook — 不使用 <Chatbot> 自己組 UI
• ConversationMessage 類型 — 訊息的 union type 結構

深入閱讀​

SDK 的完整 API 參考，見 Asgard 開發者文件：

• SDK 總覽
• JavaScript SDK
• React SDK