Chatbot Props

Required​

Prop	Type	Description
config	ClientConfig	Client config; must include botProviderEndpoint
customChannelId	string	Unique channel id on your side (user id / session id)

Display​

Prop	Type	Default	Description
title	string	—	Header title (the bot-name row, distinct from channelTitle)
avatar	string	—	Bot avatar URL
botTypingPlaceholder	string	—	Deprecated (since 0.3.x) — no longer renders anything. The run-in-progress cue is now a connection-bound running indicator shown automatically (no prop needed)
locale	'en-US' | 'ja-JP' | 'zh-TW'	'en-US'	Language for built-in text: tool-call labels, group summary, Task / Subagent panels. See Locales
channelTitle	string | null	—	Seed for the thread-top title row (usually from channelMetadata()); updates live from the backend title.update event. See Channel Title
inputPlaceholder	string	—	Input box placeholder
fullScreen	boolean	false	Render in full-screen mode
className	string	—	Outer className
style	CSSProperties	—	Outer inline style
loadingComponent	ReactNode	—	Custom loading UI

Feature Toggles​

Prop	Type	Description
enableUpload	boolean	Enable the image upload button
enableDocumentUpload	boolean	Enable the document upload button
allowedImageMimeTypes	string[]	Restrict image MIME types for enableUpload; when set it fully overrides the default list. See File Upload
allowedDocumentMimeTypes	string[]	Restrict document MIME types for enableDocumentUpload; when set it fully overrides the default list. See File Upload
enableExport	boolean	Enable conversation export
enableLoadConfigFromService	boolean	Load remote config (e.g. embedConfig) from bot provider
maintainConnectionWhenClosed	boolean	Keep the SSE connection alive when the window is closed
keepConnectionOnUnmount	boolean	Default false. Keep an in-flight SSE run alive when the component unmounts so it can finish on the backend (distinct from maintainConnectionWhenClosed, which is the window-closed case)
autoResetChannel	boolean	Default true. Since 0.3.x, mount first checks channel metadata: a channel that already exists on the backend is always restored (history replayed) regardless of this flag; only for a not-yet-existing channel does false skip RESET_CHANNEL to preserve initMessages. See Auto Reset Channel
userIdentityHint	string	User identity hint; when set, all requests (SSE, upload) send the X-ASGARD-USER-IDENTITY-HINT header

See the Feature Toggles demo.

Init Messages & Events​

Prop	Type	Description
initMessages	ConversationMessage[]	Initial messages loaded on mount
onSseMessage	(response, { conversation }) => void	Callback fired on every SSE event
onSseError	(error: unknown) => void	SSE error callback
onBeforeSendMessage	(params) => params	Modify params before sending. See before-send-message
onMessageSent	() => void	Fired after a message has been sent
onChannelReady	() => void	Fired once the channel is ready to accept messages (the ref is updated, so you can send an opening message from the ref inside the callback); re-fires after resetChannel
onReset	() => void	Fired when the channel is reset
onClose	() => void	Fired when the chatbot is closed

Custom Rendering​

Prop	Type	Description
theme	Partial<AsgardThemeContextValue>	Theme overrides — see Theme demo
renderHeader	() => ReactNode	Replace the default header — see Custom Header
renderFooter	() => ReactNode	Replace the default footer (input area) entirely — see Custom Footer
renderMenu	() => ReactNode	Insert a menu between body and footer — see Render Menu
renderTitle	(props) => ReactNode	Replace the thread-top title row (props is { title, renderDefault }; return null to hide). Pairs with untitledLabel (fallback for unnamed, default 新對話) and channelTitleHidden. See Channel Title
renderMessageContent	(props) => ReactNode	Replace message content rendering — see Custom Renderer
renderToolCallGroup	(props) => ReactNode	Customize or hide the tool-call group — see Tool Call
errorMessageRenderer	(message) => ReactNode	Custom error message renderer
customActions	ReactNode[]	Custom buttons rendered on the right of the header
footerEndActions	ReactNode[]	Custom nodes rendered at the trailing end of the footer input row (after send/mic) — see Footer End Actions
messageActions	(message) => MessageActionConfig[]	Action buttons under each bot message
onMessageAction	(actionId, message) => void	Callback when a message action is clicked
onTemplateBtnClick	(payload, eventName, raw) => void	Callback for button-template emit actions
onErrorClick	(message) => void	Callback when an error message is clicked
defaultLinkTarget	'_blank' | '_self' | '_parent' | '_top'	Default target for links in messages
hideRunChrome	boolean	Do not render the built-in docked Task / Subagent panels — place them yourself, see Docking Panels

Sandbox​

Prop	Type	Description
fileExplorer	'builtin' | 'off'	The built-in File Explorer aside; defaults to 'builtin'. Set 'off' to place <FileExplorerPanel> yourself. See File Explorer
autoRevealOnOpenFileCard	boolean	Whether an arriving open-file card auto-reveals the aside (default true); suppressed while a file has unsaved edits
fileExplorerBasePath	string	Override the tree root (absolute path) instead of the sandbox's workingDirectory
onSandboxOpenBrowser	(sandboxName) => void	Take over a sandbox://<name>/open-browser card; when set the SDK defers to you. See Handoff Cards
onSandboxOpenFile	(sandboxName, absolutePath) => void	Take over a sandbox://<name>/open-file card. Additive, not a replacement — the built-in aside is still revealed unless you also set fileExplorer="off"
sandboxBrowserOpenTarget	'_blank' | '_self' | '_parent' | '_top'	Where the default open-browser handler opens the tab; defaults to '_blank'

Auth​

Prop	Type	Description
authState	AuthState	Current auth state — see values below and Auth demo
onApiKeySubmit	(apiKey: string) => Promise<void>	Fired when the user submits an API key
onAuthError	(error: { isAuthError, isBotProviderError, errorDetail }) => void	Auth error callback

AuthState possible values: 'loading' | 'needApiKey' | 'authenticated' | 'error' | 'invalidApiKey' | 'subscriptionExpired' | 'botNotFound'

ClientConfig Fields​

The config prop is of type ClientConfig:

Field	Type	Description
botProviderEndpoint	string	Required. Bot provider base URL
endpoint	string	@deprecated — use botProviderEndpoint
apiKey	string	Static API key
customHeaders	Record<string, string>	Custom HTTP headers (e.g. Authorization: Bearer ...)
transformSsePayload	(payload) => payload	Mutate the SSE payload before sending
debugMode	boolean	Enable debug logs
onRunInit / onMessage / onToolCall / onProcess / onRunDone / onRunError	EventHandler	Per-SSE-event handlers

Setting botProviderEndpoint to the literal string "skip" enables preview mode: no connection is established, only initMessages are rendered. Many demos on this site use preview mode.

See Also​

• useChannel hook — build your own UI without <Chatbot>
• ConversationMessage type — the message union shape

Further Reading​

For the complete SDK API reference, see the Asgard developer docs:

• SDK Overview
• JavaScript SDK
• React SDK