Chatbot Props
以下列出 @asgard-js/react 的 <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 |
認證
| 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 開發者文件：