對話 Widget
建立 Web Chat
POST /api/v1/web-chats/
請求內容
請求參數
avatar
string (uri)
否
logo
string (uri)
否
description
string
否
cover
string (uri)
否
backUrl
string
否
isActive
boolean
否
theme
object
是
theme.primaryColor
string
否
theme.navbarTextColor
string
否
theme.conversationBackgroundColor
string
否
theme.chatbotMessageTextColor
string
否
theme.userMessageTextColor
string
否
theme.chatbotMessageBackgroundColor
string
否
theme.userMessageBackgroundColor
string
否
theme.chatbotMessageBackgroundShadowEnabled
boolean
否
theme.userMessageBackgroundShadowEnabled
boolean
否
theme.chatbotMessageGradientEnabled
boolean
否
theme.userMessageGradientEnabled
boolean
否
darkTheme
object
是
darkTheme.primaryColor
string
否
darkTheme.navbarTextColor
string
否
darkTheme.conversationBackgroundColor
string
否
darkTheme.chatbotMessageTextColor
string
否
darkTheme.userMessageTextColor
string
否
darkTheme.chatbotMessageBackgroundColor
string
否
darkTheme.userMessageBackgroundColor
string
否
darkTheme.chatbotMessageBackgroundShadowEnabled
boolean
否
darkTheme.userMessageBackgroundShadowEnabled
boolean
否
darkTheme.chatbotMessageGradientEnabled
boolean
否
darkTheme.userMessageGradientEnabled
boolean
否
enableFileUpload
boolean
否
enableDisplayCitations
boolean
否
toolDisplayMode
string (enum: full, compact, hidden)
否
full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking
boolean
否
enableUserThinkingControl
boolean
否
enableDisplayQueryMetadata
boolean
否
enableDisplayHookMarkers
boolean
否
hookMarkerTextInputModify
string
否
hookMarkerTextOutputModify
string
否
hookMarkerTextInputBlock
string
否
hookMarkerTextOutputBlock
string
否
enableShareConversation
boolean
否
enableLocation
boolean
否
enableShowPoweredBy
boolean
否
poweredByLogo
string (uri)
否
enableAnonymous
boolean
否
enableDisplayPreviousConversation
boolean
否
enableDisplayConversationHistory
boolean
否
enableConversationTimer
boolean
否
conversationTimerDuration
integer
否
計時器逾時時長,範圍 3-60 分鐘
enableAutoNewConversationOnTimeout
boolean
否
enableSatisfactionSurvey
boolean
否
satisfactionSurveyDelayMinutes
integer
否
最後一則 AI 回覆後幾分鐘彈出問卷,範圍 1-60 分鐘
satisfactionSurveyPrompt
string
否
自訂問卷標題文字,留空則使用前端多語系預設文字
enableThemeModeToggle
boolean
否
enableDisplayFontSizeSwitch
boolean
否
defaultThemeMode
object
否
enableDownloadCitations
boolean
否
customDomain
object (含 3 個屬性: id, domain, status)
否
customDomain.domain
string
是
enableDisplayChatbotAvatar
boolean
否
enableDisplayChatbotName
boolean
否
buttonIcon
string (uri)
否
conversationStartersDisplayCount
integer
否
preChatFormEnabled
boolean
否
preChatFormFields
object
否
preChatFormTitle
object
否
preChatFormSubtitle
object
否
loadingDisplayMode
object
否
Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale
object
否
Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale
object
否
Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds
integer
否
How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset
boolean
否
True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl
string (uri)
否
loadingAnimationAssetUrlsByStage
object
否
Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy
boolean
否
Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl
string (uri)
否
toolCardCompletedIconUrl
string (uri)
否
請求結構範例
請求範例值
程式碼範例
回應內容
狀態碼: 201
回應結構範例
回應範例值
列出 Web Chat
GET /api/v1/web-chats/
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
取得特定 Web Chat
GET /api/v1/web-chats/{id}/
參數
id
✅
string
A UUID string identifying this web chat.
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
更新 Web Chat
PUT /api/v1/web-chats/{id}/
參數
id
✅
string
A UUID string identifying this web chat.
請求內容
請求參數
avatar
string (uri)
否
logo
string (uri)
否
description
string
否
cover
string (uri)
否
backUrl
string
否
isActive
boolean
否
theme
object
是
theme.primaryColor
string
否
theme.navbarTextColor
string
否
theme.conversationBackgroundColor
string
否
theme.chatbotMessageTextColor
string
否
theme.userMessageTextColor
string
否
theme.chatbotMessageBackgroundColor
string
否
theme.userMessageBackgroundColor
string
否
theme.chatbotMessageBackgroundShadowEnabled
boolean
否
theme.userMessageBackgroundShadowEnabled
boolean
否
theme.chatbotMessageGradientEnabled
boolean
否
theme.userMessageGradientEnabled
boolean
否
darkTheme
object
是
darkTheme.primaryColor
string
否
darkTheme.navbarTextColor
string
否
darkTheme.conversationBackgroundColor
string
否
darkTheme.chatbotMessageTextColor
string
否
darkTheme.userMessageTextColor
string
否
darkTheme.chatbotMessageBackgroundColor
string
否
darkTheme.userMessageBackgroundColor
string
否
darkTheme.chatbotMessageBackgroundShadowEnabled
boolean
否
darkTheme.userMessageBackgroundShadowEnabled
boolean
否
darkTheme.chatbotMessageGradientEnabled
boolean
否
darkTheme.userMessageGradientEnabled
boolean
否
enableFileUpload
boolean
否
enableDisplayCitations
boolean
否
toolDisplayMode
string (enum: full, compact, hidden)
否
full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking
boolean
否
enableUserThinkingControl
boolean
否
enableDisplayQueryMetadata
boolean
否
enableDisplayHookMarkers
boolean
否
hookMarkerTextInputModify
string
否
hookMarkerTextOutputModify
string
否
hookMarkerTextInputBlock
string
否
hookMarkerTextOutputBlock
string
否
enableShareConversation
boolean
否
enableLocation
boolean
否
enableShowPoweredBy
boolean
否
poweredByLogo
string (uri)
否
enableAnonymous
boolean
否
enableDisplayPreviousConversation
boolean
否
enableDisplayConversationHistory
boolean
否
enableConversationTimer
boolean
否
conversationTimerDuration
integer
否
計時器逾時時長,範圍 3-60 分鐘
enableAutoNewConversationOnTimeout
boolean
否
enableSatisfactionSurvey
boolean
否
satisfactionSurveyDelayMinutes
integer
否
最後一則 AI 回覆後幾分鐘彈出問卷,範圍 1-60 分鐘
satisfactionSurveyPrompt
string
否
自訂問卷標題文字,留空則使用前端多語系預設文字
enableThemeModeToggle
boolean
否
enableDisplayFontSizeSwitch
boolean
否
defaultThemeMode
object
否
enableDownloadCitations
boolean
否
customDomain
object (含 3 個屬性: id, domain, status)
否
customDomain.domain
string
是
enableDisplayChatbotAvatar
boolean
否
enableDisplayChatbotName
boolean
否
buttonIcon
string (uri)
否
conversationStartersDisplayCount
integer
否
preChatFormEnabled
boolean
否
preChatFormFields
object
否
preChatFormTitle
object
否
preChatFormSubtitle
object
否
loadingDisplayMode
object
否
Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale
object
否
Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale
object
否
Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds
integer
否
How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset
boolean
否
True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl
string (uri)
否
loadingAnimationAssetUrlsByStage
object
否
Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy
boolean
否
Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl
string (uri)
否
toolCardCompletedIconUrl
string (uri)
否
請求結構範例
請求範例值
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
部分更新 Web Chat
PATCH /api/v1/web-chats/{id}/
參數
id
✅
string
A UUID string identifying this web chat.
請求內容
請求參數
avatar
string (uri)
否
logo
string (uri)
否
description
string
否
cover
string (uri)
否
backUrl
string
否
isActive
boolean
否
theme
object
否
theme.primaryColor
string
否
theme.navbarTextColor
string
否
theme.conversationBackgroundColor
string
否
theme.chatbotMessageTextColor
string
否
theme.userMessageTextColor
string
否
theme.chatbotMessageBackgroundColor
string
否
theme.userMessageBackgroundColor
string
否
theme.chatbotMessageBackgroundShadowEnabled
boolean
否
theme.userMessageBackgroundShadowEnabled
boolean
否
theme.chatbotMessageGradientEnabled
boolean
否
theme.userMessageGradientEnabled
boolean
否
darkTheme
object
否
darkTheme.primaryColor
string
否
darkTheme.navbarTextColor
string
否
darkTheme.conversationBackgroundColor
string
否
darkTheme.chatbotMessageTextColor
string
否
darkTheme.userMessageTextColor
string
否
darkTheme.chatbotMessageBackgroundColor
string
否
darkTheme.userMessageBackgroundColor
string
否
darkTheme.chatbotMessageBackgroundShadowEnabled
boolean
否
darkTheme.userMessageBackgroundShadowEnabled
boolean
否
darkTheme.chatbotMessageGradientEnabled
boolean
否
darkTheme.userMessageGradientEnabled
boolean
否
enableFileUpload
boolean
否
enableDisplayCitations
boolean
否
toolDisplayMode
string (enum: full, compact, hidden)
否
full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking
boolean
否
enableUserThinkingControl
boolean
否
enableDisplayQueryMetadata
boolean
否
enableDisplayHookMarkers
boolean
否
hookMarkerTextInputModify
string
否
hookMarkerTextOutputModify
string
否
hookMarkerTextInputBlock
string
否
hookMarkerTextOutputBlock
string
否
enableShareConversation
boolean
否
enableLocation
boolean
否
enableShowPoweredBy
boolean
否
poweredByLogo
string (uri)
否
enableAnonymous
boolean
否
enableDisplayPreviousConversation
boolean
否
enableDisplayConversationHistory
boolean
否
enableConversationTimer
boolean
否
conversationTimerDuration
integer
否
計時器逾時時長,範圍 3-60 分鐘
enableAutoNewConversationOnTimeout
boolean
否
enableSatisfactionSurvey
boolean
否
satisfactionSurveyDelayMinutes
integer
否
最後一則 AI 回覆後幾分鐘彈出問卷,範圍 1-60 分鐘
satisfactionSurveyPrompt
string
否
自訂問卷標題文字,留空則使用前端多語系預設文字
enableThemeModeToggle
boolean
否
enableDisplayFontSizeSwitch
boolean
否
defaultThemeMode
object
否
enableDownloadCitations
boolean
否
customDomain
object (含 3 個屬性: id, domain, status)
否
customDomain.domain
string
是
enableDisplayChatbotAvatar
boolean
否
enableDisplayChatbotName
boolean
否
buttonIcon
string (uri)
否
conversationStartersDisplayCount
integer
否
preChatFormEnabled
boolean
否
preChatFormFields
object
否
preChatFormTitle
object
否
preChatFormSubtitle
object
否
loadingDisplayMode
object
否
Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale
object
否
Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale
object
否
Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds
integer
否
How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset
boolean
否
True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl
string (uri)
否
loadingAnimationAssetUrlsByStage
object
否
Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy
boolean
否
Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl
string (uri)
否
toolCardCompletedIconUrl
string (uri)
否
請求結構範例
請求範例值
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
設定聯絡人憑證
POST /api/v1/web-chats/{id}/setup-contact-credentials/
參數
id
✅
string
A UUID string identifying this web chat.
請求內容
請求參數
sourceId
string
是
Unique identifier for the contact
name
string
否
Contact display name
mcpCredentials
object (含 2 個屬性: toolId, headers)
否
MCP credentials configuration
mcpCredentials.toolId
string (uuid)
是
MCP Tool ID
mcpCredentials.headers
object
否
Authentication headers
embedOrigin
string
否
Origin of the embedding page (forwarded by the web chat frontend) for allowlist validation
ts
integer
否
Unix timestamp (seconds, UTC) the signature was computed with. Required when the inbox login settings enable Source ID access with signature verification.
sig
string
否
Hex HMAC-SHA256 of "{webChatId}.{sourceId}.{ts}" computed by the embedding site backend
請求結構範例
請求範例值
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
狀態碼: 400 - No response body
取得語音助理 Token
POST /api/v1/web-chats/{id}/voice-agent/token/
參數
id
✅
string
A UUID string identifying this web chat.
請求內容
請求參數
avatar
string (uri)
否
logo
string (uri)
否
description
string
否
cover
string (uri)
否
backUrl
string
否
isActive
boolean
否
theme
object
是
theme.primaryColor
string
否
theme.navbarTextColor
string
否
theme.conversationBackgroundColor
string
否
theme.chatbotMessageTextColor
string
否
theme.userMessageTextColor
string
否
theme.chatbotMessageBackgroundColor
string
否
theme.userMessageBackgroundColor
string
否
theme.chatbotMessageBackgroundShadowEnabled
boolean
否
theme.userMessageBackgroundShadowEnabled
boolean
否
theme.chatbotMessageGradientEnabled
boolean
否
theme.userMessageGradientEnabled
boolean
否
darkTheme
object
是
darkTheme.primaryColor
string
否
darkTheme.navbarTextColor
string
否
darkTheme.conversationBackgroundColor
string
否
darkTheme.chatbotMessageTextColor
string
否
darkTheme.userMessageTextColor
string
否
darkTheme.chatbotMessageBackgroundColor
string
否
darkTheme.userMessageBackgroundColor
string
否
darkTheme.chatbotMessageBackgroundShadowEnabled
boolean
否
darkTheme.userMessageBackgroundShadowEnabled
boolean
否
darkTheme.chatbotMessageGradientEnabled
boolean
否
darkTheme.userMessageGradientEnabled
boolean
否
enableFileUpload
boolean
否
enableDisplayCitations
boolean
否
toolDisplayMode
string (enum: full, compact, hidden)
否
full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking
boolean
否
enableUserThinkingControl
boolean
否
enableDisplayQueryMetadata
boolean
否
enableDisplayHookMarkers
boolean
否
hookMarkerTextInputModify
string
否
hookMarkerTextOutputModify
string
否
hookMarkerTextInputBlock
string
否
hookMarkerTextOutputBlock
string
否
enableShareConversation
boolean
否
enableLocation
boolean
否
enableShowPoweredBy
boolean
否
poweredByLogo
string (uri)
否
enableAnonymous
boolean
否
enableDisplayPreviousConversation
boolean
否
enableDisplayConversationHistory
boolean
否
enableConversationTimer
boolean
否
conversationTimerDuration
integer
否
計時器逾時時長,範圍 3-60 分鐘
enableAutoNewConversationOnTimeout
boolean
否
enableSatisfactionSurvey
boolean
否
satisfactionSurveyDelayMinutes
integer
否
最後一則 AI 回覆後幾分鐘彈出問卷,範圍 1-60 分鐘
satisfactionSurveyPrompt
string
否
自訂問卷標題文字,留空則使用前端多語系預設文字
enableThemeModeToggle
boolean
否
enableDisplayFontSizeSwitch
boolean
否
defaultThemeMode
object
否
enableDownloadCitations
boolean
否
customDomain
object (含 3 個屬性: id, domain, status)
否
customDomain.domain
string
是
enableDisplayChatbotAvatar
boolean
否
enableDisplayChatbotName
boolean
否
buttonIcon
string (uri)
否
conversationStartersDisplayCount
integer
否
preChatFormEnabled
boolean
否
preChatFormFields
object
否
preChatFormTitle
object
否
preChatFormSubtitle
object
否
loadingDisplayMode
object
否
Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale
object
否
Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale
object
否
Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds
integer
否
How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset
boolean
否
True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl
string (uri)
否
loadingAnimationAssetUrlsByStage
object
否
Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy
boolean
否
Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl
string (uri)
否
toolCardCompletedIconUrl
string (uri)
否
請求結構範例
請求範例值
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
上傳批次 QA 檔案
POST /api/v1/web-chats/{webchatPk}/batch-qas/
參數
webchatPk
✅
string
請求內容
請求參數
file
string (uri)
是
請求結構範例
請求範例值
程式碼範例
回應內容
狀態碼: 201
回應結構範例
回應範例值
匯出批次 QA 為 Excel
GET /api/v1/web-chats/{webchatPk}/batch-qas/{id}/export-excel/
參數
id
✅
string
A UUID string identifying this Chatbot 批次問答檔案.
webchatPk
✅
string
程式碼範例
回應內容
200
Excel 檔案下載
取得 LLM 使用統計
GET /api/v1/chatbots/{chatbotPk}/llm-usage-statistics/
參數
chatbotPk
✅
string
A UUID string identifying this Chatbot ID
endDate
❌
string
結束日期,格式: YYYY-MM-DD
startDate
✅
string
開始日期,格式: YYYY-MM-DD
timeGranularity
✅
string
時間粒度 (day/month)
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
狀態碼: 400
回應結構範例
回應範例值
取得 AI 助理統計數據
GET /api/v1/chatbots/{chatbotPk}/statistics/
參數
chatbotPk
✅
string
A UUID string identifying this Chatbot ID
datetimeFrom
❌
string
開始時間
datetimeTo
❌
string
結束時間
timeGranularity
❌
string
時間粒度 (hour/day/month)
程式碼範例
回應內容
狀態碼: 200
回應結構範例
回應範例值
最後更新於
這有幫助嗎?
