<Chatbot> Props Reference

以下列出 @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	啟用文件上傳按鈕
enableExport	boolean	啟用對話匯出
enableLoadConfigFromService	boolean	從 bot provider 讀取遠端設定（例如 embedConfig）
maintainConnectionWhenClosed	boolean	關閉視窗時保留 SSE 連線
autoResetChannel	boolean	預設 true；設為 false 可保留 initMessages 歷史

詳見 功能開關 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
onReset	() => void	Reset channel 時觸發
onClose	() => void	Chatbot 關閉時觸發

客製渲染

Prop	型別	說明
theme	Partial<AsgardThemeContextValue>	主題設定，見 主題 Demo
renderHeader	() => ReactNode	完全取代預設 header，見 Custom Header
renderMenu	() => ReactNode	在 body 和 footer 之間插入選單，見 Render Menu
renderMessageContent	(props) => ReactNode	完全取代訊息內容渲染，見 Custom Renderer
renderToolCallGroup	(props) => ReactNode	自訂或隱藏 Tool Call Group，見 工具呼叫
errorMessageRenderer	(message) => ReactNode	自訂錯誤訊息呈現
customActions	ReactNode[]	塞到 header 右側的自訂按鈕
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 ...）
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 結構