> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/api-reference/dui-hua-widget.md). # 對話 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; | | enableAskOptionButtons | boolean | 否 | 開啟後 ask\_user\_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 | | 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) | 否 | | **請求結構範例** ```typescript { "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "conversationStartersDisplayCount"?: integer // 非必填 "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 } ``` **請求範例值** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // 請求內容 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/", data, config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # 請求內容 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.post(url, json=data, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 201** **回應結構範例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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 // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填) "accessType": { } "enableThemeModeToggle"?: boolean // 非必填 "enableDisplayFontSizeSwitch"?: boolean // 非必填 "defaultThemeMode"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 非必填 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **回應範例值** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應字串", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "回應字串", "cover": "https://example.com/file.jpg", "backUrl": "回應字串", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "回應字串" ], "theme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "回應字串", "hookMarkerTextOutputModify": "回應字串", "hookMarkerTextInputBlock": "回應字串", "hookMarkerTextOutputBlock": "回應字串", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "回應字串", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "回應字串", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } } ``` *** ### 列出 Web Chat GET `/api/v1/web-chats/` #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/web-chats/", config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/web-chats/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript [ { "id": string (uuid) "avatar"?: string (uri) // 非必填 "name": string } ] ``` **回應範例值** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "avatar": "https://example.com/file.jpg", "name": "回應字串" } ] ``` *** ### 取得特定 Web Chat GET `/api/v1/web-chats/{id}/` #### 參數 | 參數名稱 | 必填 | 類型 | 說明 | | ---- | -- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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 // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填) "accessType": { } "enableThemeModeToggle"?: boolean // 非必填 "enableDisplayFontSizeSwitch"?: boolean // 非必填 "defaultThemeMode"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 非必填 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **回應範例值** ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "測試 doc", "avatar": "https://example.com/static/images/default-chatbot-avatar.png", "logo": null, "description": "", "cover": null, "backUrl": "", "isActive": true, "enableSpeech": false, "displayGreeting": null, "displayConversationStarters": [], "theme": { "primaryColor": "#3854d8", "dialogColor": "#ddeaf6", "navbarTextColor": "#ffffff" }, "enableFileUpload": true, "enableDisplayCitations": true, "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": true, "poweredByLogo": null, "accessType": "web", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "測試 doc", "signAuth": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "signSource": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "accessType": "keycloak" }, "signParams": { "keycloak": { "url": "example.com", "realm": "example", "clientId": "example" } } } } } ``` *** ### 更新 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; | | enableAskOptionButtons | boolean | 否 | 開啟後 ask\_user\_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 | | 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) | 否 | | **請求結構範例** ```typescript { "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "conversationStartersDisplayCount"?: integer // 非必填 "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 } ``` **請求範例值** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X PUT "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // 請求內容 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.put("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # 請求內容 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.put(url, json=data, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php put("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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 // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填) "accessType": { } "enableThemeModeToggle"?: boolean // 非必填 "enableDisplayFontSizeSwitch"?: boolean // 非必填 "defaultThemeMode"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 非必填 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **回應範例值** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應字串", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "回應字串", "cover": "https://example.com/file.jpg", "backUrl": "回應字串", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "回應字串" ], "theme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "回應字串", "hookMarkerTextOutputModify": "回應字串", "hookMarkerTextInputBlock": "回應字串", "hookMarkerTextOutputBlock": "回應字串", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "回應字串", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "回應字串", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } } ``` *** ### 部分更新 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; | | enableAskOptionButtons | boolean | 否 | 開啟後 ask\_user\_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 | | 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) | 否 | | **請求結構範例** ```typescript { "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "theme"?: { // 非必填 { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme"?: { // 非必填 { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "conversationStartersDisplayCount"?: integer // 非必填 "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 } ``` **請求範例值** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // 請求內容 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.patch("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # 請求內容 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.patch(url, json=data, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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 // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填) "accessType": { } "enableThemeModeToggle"?: boolean // 非必填 "enableDisplayFontSizeSwitch"?: boolean // 非必填 "defaultThemeMode"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 非必填 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **回應範例值** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應字串", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "回應字串", "cover": "https://example.com/file.jpg", "backUrl": "回應字串", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "回應字串" ], "theme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "回應字串", "hookMarkerTextOutputModify": "回應字串", "hookMarkerTextInputBlock": "回應字串", "hookMarkerTextOutputBlock": "回應字串", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "回應字串", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "回應字串", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } } ``` *** ### 設定聯絡人憑證 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 | **請求結構範例** ```typescript { "sourceId": string // Unique identifier for the contact "name"?: string // Contact display name (非必填) "mcpCredentials"?: // MCP credentials configuration (非必填) { "toolId": string (uuid) // MCP Tool ID "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 (非必填) } ``` **請求範例值** ```json { "sourceId": "範例字串", "name": "範例名稱", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "範例字串", "ts": 123, "sig": "範例字串" } ``` #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sourceId": "範例字串", "name": "範例名稱", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "範例字串", "ts": 123, "sig": "範例字串" }' # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // 請求內容 (payload) const data = { "sourceId": "範例字串", "name": "範例名稱", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "範例字串", "ts": 123, "sig": "範例字串" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/", data, config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # 請求內容 (payload) data = { "sourceId": "範例字串", "name": "範例名稱", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "範例字串", "ts": 123, "sig": "範例字串" } response = requests.post(url, json=data, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => { "sourceId": "範例字串", "name": "範例名稱", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "範例字串", "ts": 123, "sig": "範例字串" } ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript { "contactId": string (uuid) // The created or existing contact ID "created": boolean // Whether the contact was created by this call. False means an existing contact matched the source_id; in that case the request name is not applied (update names via PATCH /contacts/{id}/). } ``` **回應範例值** ```json { "contactId": "550e8400-e29b-41d4-a716-446655440000", "created": false } ``` **狀態碼: 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; | | enableAskOptionButtons | boolean | 否 | 開啟後 ask\_user\_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 | | 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) | 否 | | **請求結構範例** ```typescript { "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "conversationStartersDisplayCount"?: integer // 非必填 "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 } ``` **請求範例值** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // 請求內容 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/", data, config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # 請求內容 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.post(url, json=data, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "範例字串", "cover": "https://example.com/file.jpg", "backUrl": "範例字串", "isActive": true, "theme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "範例字串", "navbarTextColor": "範例字串", "conversationBackgroundColor": "範例字串", "chatbotMessageTextColor": "範例字串", "userMessageTextColor": "範例字串", "chatbotMessageBackgroundColor": "範例字串", "userMessageBackgroundColor": "範例字串", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "範例字串", "hookMarkerTextOutputModify": "範例字串", "hookMarkerTextInputBlock": "範例字串", "hookMarkerTextOutputBlock": "範例字串", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "範例字串", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "範例字串" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 非必填 "logo"?: string (uri) // 非必填 "description"?: string // 非必填 "cover"?: string (uri) // 非必填 "backUrl"?: string // 非必填 "isActive"?: boolean // 非必填 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "darkTheme": { { "primaryColor"?: string // 非必填 "navbarTextColor"?: string // 非必填 "conversationBackgroundColor"?: string // 非必填 "chatbotMessageTextColor"?: string // 非必填 "userMessageTextColor"?: string // 非必填 "chatbotMessageBackgroundColor"?: string // 非必填 "userMessageBackgroundColor"?: string // 非必填 "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填 "userMessageBackgroundShadowEnabled"?: boolean // 非必填 "chatbotMessageGradientEnabled"?: boolean // 非必填 "userMessageGradientEnabled"?: boolean // 非必填 } } "enableFileUpload"?: boolean // 非必填 "enableDisplayCitations"?: boolean // 非必填 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (非必填) "enableAskOptionButtons"?: boolean // 開啟後 ask_user_question 選項以按鈕列浮在輸入框上方（輸入框保持可用）；關閉則維持現行覆蓋式面板。灰度開關，可隨時關閉回退。 (非必填) "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 // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填) "accessType": { } "enableThemeModeToggle"?: boolean // 非必填 "enableDisplayFontSizeSwitch"?: boolean // 非必填 "defaultThemeMode"?: // 非必填 { } "enableDownloadCitations"?: boolean // 非必填 "customDomain"?: // 非必填 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 非必填 "enableDisplayChatbotName"?: boolean // 非必填 "buttonIcon"?: string (uri) // 非必填 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 非必填 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 非必填 "preChatFormFields"?: object // 非必填 "preChatFormTitle"?: object // 非必填 "preChatFormSubtitle"?: object // 非必填 "loadingDisplayMode"?: // 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 behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (非必填) { } "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 and never blocks a reply. (非必填) "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. Empty means no long-wait line is shown. (非必填) "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 empty. (非必填) "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. Thinking / analyzing / long-wait stages are unaffected. (非必填) "toolCardRunningIconUrl"?: string (uri) // 非必填 "toolCardCompletedIconUrl"?: string (uri) // 非必填 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **回應範例值** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應字串", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "回應字串", "cover": "https://example.com/file.jpg", "backUrl": "回應字串", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "回應字串" ], "theme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "回應字串", "navbarTextColor": "回應字串", "conversationBackgroundColor": "回應字串", "chatbotMessageTextColor": "回應字串", "userMessageTextColor": "回應字串", "chatbotMessageBackgroundColor": "回應字串", "userMessageBackgroundColor": "回應字串", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "回應字串", "hookMarkerTextOutputModify": "回應字串", "hookMarkerTextInputBlock": "回應字串", "hookMarkerTextOutputBlock": "回應字串", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "回應字串", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "回應字串", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "回應範例名稱", "description": "回應範例描述" } } ``` *** ### 上傳批次 QA 檔案 POST `/api/v1/web-chats/{webchatPk}/batch-qas/` #### 參數 | 參數名稱 | 必填 | 類型 | 說明 | | ----------- | -- | ------ | -- | | `webchatPk` | ✅ | string | | #### 請求內容 **請求參數** | 欄位 | 類型 | 必填 | 說明 | | ---- | ------------ | -- | -- | | file | string (uri) | 是 | | **請求結構範例** ```typescript { "file": string (uri) } ``` **請求範例值** ```json { "file": "https://example.com/file.jpg" } ``` #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "file": "https://example.com/file.jpg" }' # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // 請求內容 (payload) const data = { "file": "https://example.com/file.jpg" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/", data, config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # 請求內容 (payload) data = { "file": "https://example.com/file.jpg" } response = requests.post(url, json=data, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => { "file": "https://example.com/file.jpg" } ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 201** **回應結構範例** ```typescript { "id": string (uuid) "file": string (uri) "createdAt": string (timestamp) } ``` **回應範例值** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "file": "https://example.com/file.jpg", "createdAt": "回應字串" } ``` *** ### 匯出批次 QA 為 Excel GET `/api/v1/web-chats/{webchatPk}/batch-qas/{id}/export-excel/` #### 參數 | 參數名稱 | 必填 | 類型 | 說明 | | ----------- | -- | ------ | ---------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Chatbot 批次問答檔案. | | `webchatPk` | ✅ | string | | #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/", config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 | 狀態碼 | 說明 | | --- | ---------- | | 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) | #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day" \ -H "Authorization: Api-Key YOUR_API_KEY" # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript [ { "date": string (date) } ] ``` **回應範例值** ```json [ [ { "totalWordsCount": 511, "month": "2025-03-01", "llmDetails": [ { "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b", "wordsCount": 511, "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383", "llmModelName": "GPT-4o-2024-08-06", "llmModelProvider": "openai" } ] } ] ] ``` **狀態碼: 400** **回應結構範例** ```typescript { "detail"?: string // 非必填 "valid_types"?: [ // 非必填 string ] } ``` **回應範例值** ```json [ [ { "totalWordsCount": 511, "month": "2025-03-01", "llmDetails": [ { "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b", "wordsCount": 511, "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383", "llmModelName": "GPT-4o-2024-08-06", "llmModelProvider": "openai" } ] } ] ] ``` *** ### 取得 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) | #### 程式碼範例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # 呼叫 API 示例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example" \ -H "Authorization: Api-Key YOUR_API_KEY" # 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // 設定請求標頭 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example", config) .then(response => { console.log('成功取得回應:'); console.log(response.data); }) .catch(error => { console.error('請求發生錯誤:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("成功取得回應:") print(response.json()) except Exception as e: print("請求發生錯誤:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "成功取得回應:\n"; print_r($data); } catch (Exception $e) { echo '請求發生錯誤: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 回應內容 **狀態碼: 200** **回應結構範例** ```typescript [ { "datetime": integer // 時間戳（毫秒） "messagesCount": integer // 訊息數量 "conversationsCount": integer // 對話數量 "likesCount": integer // 按讚數量 "dislikesCount": integer // 不喜歡數量 } ] ``` **回應範例值** ```json [ { "datetime": 456, "messagesCount": 456, "conversationsCount": 456, "likesCount": 456, "dislikesCount": 456 } ] ``` *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/api/api-reference/dui-hua-widget.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.