Chatbot Props

以下列出 @asgard-js/react 的 <Chatbot> 元件所有可用 props。

必填

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

基本顯示

Prop	型別	預設	說明
title	string	—	Header 標題
avatar	string	—	Bot 頭像 URL
botTypingPlaceholder	string	正在輸入訊息	Bot 正在輸入時的 placeholder
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；設為 false 可保留 initMessages 歷史
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
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

認證

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