> 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 <a href="#web-chats-create" id="web-chats-create"></a>

POST `/api/v1/web-chats/`

#### 請求內容

**請求參數**

| 欄位                                              | 類型                                   | 必填 | 說明                                                                                                                                                                                                            |
| ----------------------------------------------- | ------------------------------------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| avatar                                          | string (uri)                         | 否  |                                                                                                                                                                                                               |
| logo                                            | string (uri)                         | 否  |                                                                                                                                                                                                               |
| description                                     | string                               | 否  |                                                                                                                                                                                                               |
| cover                                           | string (uri)                         | 否  |                                                                                                                                                                                                               |
| backUrl                                         | string                               | 否  |                                                                                                                                                                                                               |
| isActive                                        | boolean                              | 否  |                                                                                                                                                                                                               |
| speechPhrases                                   | array\[string]                       | 否  | Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted.          |
| enableVoiceInput                                | boolean                              | 否  | Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms ...   |
| 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                              | 否  | When on, ask\_user\_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any ti... |
| enableConversationHandoff                       | boolean                              | 否  | When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (glob...   |
| enableDisplayContextUsage                       | boolean                              | 否  | When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), a...   |
| enableDisplayThinking                           | boolean                              | 否  |                                                                                                                                                                                                               |
| enableUserThinkingControl                       | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayQueryMetadata                      | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayHookMarkers                        | boolean                              | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputModify                       | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputModify                      | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputBlock                        | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputBlock                       | string                               | 否  |                                                                                                                                                                                                               |
| enableShareConversation                         | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowConnectedServices                     | boolean                              | 否  |                                                                                                                                                                                                               |
| enableLocation                                  | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowPoweredBy                             | boolean                              | 否  |                                                                                                                                                                                                               |
| poweredByLogo                                   | string (uri)                         | 否  |                                                                                                                                                                                                               |
| enableAnonymous                                 | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                                                                                                                                                                               |
| enableConversationTimer                         | boolean                              | 否  |                                                                                                                                                                                                               |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                                                                                                                                                                            |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                                                                                                                                                                               |
| enableClearConversationOnTimeout                | boolean                              | 否  | Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared,...   |
| enableSatisfactionSurvey                        | boolean                              | 否  |                                                                                                                                                                                                               |
| satisfactionSurveyDelayMinutes                  | integer                              | 否  | Minutes after the last AI reply before the survey pops up, 1-60 minutes                                                                                                                                       |
| satisfactionSurveyPrompt                        | string                               | 否  | Custom survey title text; leave empty to use the localized default text of the front end                                                                                                                      |
| 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 // 非必填
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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,
  "speechPhrases": [
    "範例字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": true,
  "enableDisplayContextUsage": true,
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableShowConnectedServices": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
        "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": True,
    "enableDisplayContextUsage": True,
    "enableDisplayThinking": True,
    "enableUserThinkingControl": True,
    "enableDisplayQueryMetadata": True,
    "enableDisplayHookMarkers": True,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": True,
    "enableShowConnectedServices": True,
    "enableLocation": True,
    "enableShowPoweredBy": True,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": True,
    "enableDisplayPreviousConversation": True,
    "enableDisplayConversationHistory": True,
    "enableConversationTimer": True,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": True,
    "enableClearConversationOnTimeout": 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": None,
    "preChatFormTitle": None,
    "preChatFormSubtitle": None,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": None,
    "loadingLongWaitCopyByLocale": None,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": True,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": None,
    "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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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,
            'speechPhrases' => [
                '範例字串'
            ],
            'enableVoiceInput' => 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,
            'enableConversationHandoff' => true,
            'enableDisplayContextUsage' => true,
            'enableDisplayThinking' => true,
            'enableUserThinkingControl' => true,
            'enableDisplayQueryMetadata' => true,
            'enableDisplayHookMarkers' => true,
            'hookMarkerTextInputModify' => '範例字串',
            'hookMarkerTextOutputModify' => '範例字串',
            'hookMarkerTextInputBlock' => '範例字串',
            'hookMarkerTextOutputBlock' => '範例字串',
            'enableShareConversation' => true,
            'enableShowConnectedServices' => true,
            'enableLocation' => true,
            'enableShowPoweredBy' => true,
            'poweredByLogo' => 'https://example.com/file.jpg',
            'enableAnonymous' => true,
            'enableDisplayPreviousConversation' => true,
            'enableDisplayConversationHistory' => true,
            'enableConversationTimer' => true,
            'conversationTimerDuration' => 123,
            'enableAutoNewConversationOnTimeout' => true,
            'enableClearConversationOnTimeout' => true,
            'enableSatisfactionSurvey' => true,
            'satisfactionSurveyDelayMinutes' => 123,
            'satisfactionSurveyPrompt' => '範例字串',
            'enableThemeModeToggle' => true,
            'enableDisplayFontSizeSwitch' => true,
            'defaultThemeMode' => new \stdClass(),
            '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' => new \stdClass(),
            '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
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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 this page may offer voice (read-only)
  "voiceEntryRedirect": object // Where this text web chat's old ?mode=voice link goes once the organization has voice agent entries: {state: 'redirect', url} or {state: 'moved'}; null before, and when the link stays on this page behind its sign-in (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,
  "speechPhrases": [
    "回應字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": false,
  "enableDisplayContextUsage": false,
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableShowConnectedServices": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableClearConversationOnTimeout": 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,
  "voiceEntryRedirect": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "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 <a href="#web-chats-list" id="web-chats-list"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 <a href="#web-chats-retrieve" id="web-chats-retrieve"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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 this page may offer voice (read-only)
  "voiceEntryRedirect": object // Where this text web chat's old ?mode=voice link goes once the organization has voice agent entries: {state: 'redirect', url} or {state: 'moved'}; null before, and when the link stays on this page behind its sign-in (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 <a href="#web-chats-update" id="web-chats-update"></a>

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                              | 否  |                                                                                                                                                                                                               |
| speechPhrases                                   | array\[string]                       | 否  | Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted.          |
| enableVoiceInput                                | boolean                              | 否  | Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms ...   |
| 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                              | 否  | When on, ask\_user\_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any ti... |
| enableConversationHandoff                       | boolean                              | 否  | When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (glob...   |
| enableDisplayContextUsage                       | boolean                              | 否  | When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), a...   |
| enableDisplayThinking                           | boolean                              | 否  |                                                                                                                                                                                                               |
| enableUserThinkingControl                       | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayQueryMetadata                      | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayHookMarkers                        | boolean                              | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputModify                       | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputModify                      | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputBlock                        | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputBlock                       | string                               | 否  |                                                                                                                                                                                                               |
| enableShareConversation                         | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowConnectedServices                     | boolean                              | 否  |                                                                                                                                                                                                               |
| enableLocation                                  | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowPoweredBy                             | boolean                              | 否  |                                                                                                                                                                                                               |
| poweredByLogo                                   | string (uri)                         | 否  |                                                                                                                                                                                                               |
| enableAnonymous                                 | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                                                                                                                                                                               |
| enableConversationTimer                         | boolean                              | 否  |                                                                                                                                                                                                               |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                                                                                                                                                                            |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                                                                                                                                                                               |
| enableClearConversationOnTimeout                | boolean                              | 否  | Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared,...   |
| enableSatisfactionSurvey                        | boolean                              | 否  |                                                                                                                                                                                                               |
| satisfactionSurveyDelayMinutes                  | integer                              | 否  | Minutes after the last AI reply before the survey pops up, 1-60 minutes                                                                                                                                       |
| satisfactionSurveyPrompt                        | string                               | 否  | Custom survey title text; leave empty to use the localized default text of the front end                                                                                                                      |
| 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 // 非必填
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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,
  "speechPhrases": [
    "範例字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": true,
  "enableDisplayContextUsage": true,
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableShowConnectedServices": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
        "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": True,
    "enableDisplayContextUsage": True,
    "enableDisplayThinking": True,
    "enableUserThinkingControl": True,
    "enableDisplayQueryMetadata": True,
    "enableDisplayHookMarkers": True,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": True,
    "enableShowConnectedServices": True,
    "enableLocation": True,
    "enableShowPoweredBy": True,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": True,
    "enableDisplayPreviousConversation": True,
    "enableDisplayConversationHistory": True,
    "enableConversationTimer": True,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": True,
    "enableClearConversationOnTimeout": 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": None,
    "preChatFormTitle": None,
    "preChatFormSubtitle": None,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": None,
    "loadingLongWaitCopyByLocale": None,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": True,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": None,
    "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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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,
            'speechPhrases' => [
                '範例字串'
            ],
            'enableVoiceInput' => 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,
            'enableConversationHandoff' => true,
            'enableDisplayContextUsage' => true,
            'enableDisplayThinking' => true,
            'enableUserThinkingControl' => true,
            'enableDisplayQueryMetadata' => true,
            'enableDisplayHookMarkers' => true,
            'hookMarkerTextInputModify' => '範例字串',
            'hookMarkerTextOutputModify' => '範例字串',
            'hookMarkerTextInputBlock' => '範例字串',
            'hookMarkerTextOutputBlock' => '範例字串',
            'enableShareConversation' => true,
            'enableShowConnectedServices' => true,
            'enableLocation' => true,
            'enableShowPoweredBy' => true,
            'poweredByLogo' => 'https://example.com/file.jpg',
            'enableAnonymous' => true,
            'enableDisplayPreviousConversation' => true,
            'enableDisplayConversationHistory' => true,
            'enableConversationTimer' => true,
            'conversationTimerDuration' => 123,
            'enableAutoNewConversationOnTimeout' => true,
            'enableClearConversationOnTimeout' => true,
            'enableSatisfactionSurvey' => true,
            'satisfactionSurveyDelayMinutes' => 123,
            'satisfactionSurveyPrompt' => '範例字串',
            'enableThemeModeToggle' => true,
            'enableDisplayFontSizeSwitch' => true,
            'defaultThemeMode' => new \stdClass(),
            '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' => new \stdClass(),
            '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
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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 this page may offer voice (read-only)
  "voiceEntryRedirect": object // Where this text web chat's old ?mode=voice link goes once the organization has voice agent entries: {state: 'redirect', url} or {state: 'moved'}; null before, and when the link stays on this page behind its sign-in (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,
  "speechPhrases": [
    "回應字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": false,
  "enableDisplayContextUsage": false,
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableShowConnectedServices": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableClearConversationOnTimeout": 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,
  "voiceEntryRedirect": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "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 <a href="#web-chats-partial-update" id="web-chats-partial-update"></a>

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                              | 否  |                                                                                                                                                                                                               |
| speechPhrases                                   | array\[string]                       | 否  | Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted.          |
| enableVoiceInput                                | boolean                              | 否  | Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms ...   |
| 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                              | 否  | When on, ask\_user\_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any ti... |
| enableConversationHandoff                       | boolean                              | 否  | When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (glob...   |
| enableDisplayContextUsage                       | boolean                              | 否  | When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), a...   |
| enableDisplayThinking                           | boolean                              | 否  |                                                                                                                                                                                                               |
| enableUserThinkingControl                       | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayQueryMetadata                      | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayHookMarkers                        | boolean                              | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputModify                       | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputModify                      | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputBlock                        | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputBlock                       | string                               | 否  |                                                                                                                                                                                                               |
| enableShareConversation                         | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowConnectedServices                     | boolean                              | 否  |                                                                                                                                                                                                               |
| enableLocation                                  | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowPoweredBy                             | boolean                              | 否  |                                                                                                                                                                                                               |
| poweredByLogo                                   | string (uri)                         | 否  |                                                                                                                                                                                                               |
| enableAnonymous                                 | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                                                                                                                                                                               |
| enableConversationTimer                         | boolean                              | 否  |                                                                                                                                                                                                               |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                                                                                                                                                                            |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                                                                                                                                                                               |
| enableClearConversationOnTimeout                | boolean                              | 否  | Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared,...   |
| enableSatisfactionSurvey                        | boolean                              | 否  |                                                                                                                                                                                                               |
| satisfactionSurveyDelayMinutes                  | integer                              | 否  | Minutes after the last AI reply before the survey pops up, 1-60 minutes                                                                                                                                       |
| satisfactionSurveyPrompt                        | string                               | 否  | Custom survey title text; leave empty to use the localized default text of the front end                                                                                                                      |
| 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 // 非必填
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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,
  "speechPhrases": [
    "範例字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": true,
  "enableDisplayContextUsage": true,
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableShowConnectedServices": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
        "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": True,
    "enableDisplayContextUsage": True,
    "enableDisplayThinking": True,
    "enableUserThinkingControl": True,
    "enableDisplayQueryMetadata": True,
    "enableDisplayHookMarkers": True,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": True,
    "enableShowConnectedServices": True,
    "enableLocation": True,
    "enableShowPoweredBy": True,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": True,
    "enableDisplayPreviousConversation": True,
    "enableDisplayConversationHistory": True,
    "enableConversationTimer": True,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": True,
    "enableClearConversationOnTimeout": 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": None,
    "preChatFormTitle": None,
    "preChatFormSubtitle": None,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": None,
    "loadingLongWaitCopyByLocale": None,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": True,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": None,
    "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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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,
            'speechPhrases' => [
                '範例字串'
            ],
            'enableVoiceInput' => 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,
            'enableConversationHandoff' => true,
            'enableDisplayContextUsage' => true,
            'enableDisplayThinking' => true,
            'enableUserThinkingControl' => true,
            'enableDisplayQueryMetadata' => true,
            'enableDisplayHookMarkers' => true,
            'hookMarkerTextInputModify' => '範例字串',
            'hookMarkerTextOutputModify' => '範例字串',
            'hookMarkerTextInputBlock' => '範例字串',
            'hookMarkerTextOutputBlock' => '範例字串',
            'enableShareConversation' => true,
            'enableShowConnectedServices' => true,
            'enableLocation' => true,
            'enableShowPoweredBy' => true,
            'poweredByLogo' => 'https://example.com/file.jpg',
            'enableAnonymous' => true,
            'enableDisplayPreviousConversation' => true,
            'enableDisplayConversationHistory' => true,
            'enableConversationTimer' => true,
            'conversationTimerDuration' => 123,
            'enableAutoNewConversationOnTimeout' => true,
            'enableClearConversationOnTimeout' => true,
            'enableSatisfactionSurvey' => true,
            'satisfactionSurveyDelayMinutes' => 123,
            'satisfactionSurveyPrompt' => '範例字串',
            'enableThemeModeToggle' => true,
            'enableDisplayFontSizeSwitch' => true,
            'defaultThemeMode' => new \stdClass(),
            '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' => new \stdClass(),
            '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
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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 this page may offer voice (read-only)
  "voiceEntryRedirect": object // Where this text web chat's old ?mode=voice link goes once the organization has voice agent entries: {state: 'redirect', url} or {state: 'moved'}; null before, and when the link stays on this page behind its sign-in (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,
  "speechPhrases": [
    "回應字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": false,
  "enableDisplayContextUsage": false,
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableShowConnectedServices": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableClearConversationOnTimeout": 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,
  "voiceEntryRedirect": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "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": "回應範例描述"
  }
}
```

***

### 設定聯絡人憑證 <a href="#web-chats-setup-contact-credentials-create" id="web-chats-setup-contact-credentials-create"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => new \stdClass()
            ],
            '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 <a href="#web-chats-voice-agent-token-create" id="web-chats-voice-agent-token-create"></a>

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                              | 否  |                                                                                                                                                                                                               |
| speechPhrases                                   | array\[string]                       | 否  | Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted.          |
| enableVoiceInput                                | boolean                              | 否  | Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms ...   |
| 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                              | 否  | When on, ask\_user\_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any ti... |
| enableConversationHandoff                       | boolean                              | 否  | When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (glob...   |
| enableDisplayContextUsage                       | boolean                              | 否  | When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), a...   |
| enableDisplayThinking                           | boolean                              | 否  |                                                                                                                                                                                                               |
| enableUserThinkingControl                       | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayQueryMetadata                      | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayHookMarkers                        | boolean                              | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputModify                       | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputModify                      | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextInputBlock                        | string                               | 否  |                                                                                                                                                                                                               |
| hookMarkerTextOutputBlock                       | string                               | 否  |                                                                                                                                                                                                               |
| enableShareConversation                         | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowConnectedServices                     | boolean                              | 否  |                                                                                                                                                                                                               |
| enableLocation                                  | boolean                              | 否  |                                                                                                                                                                                                               |
| enableShowPoweredBy                             | boolean                              | 否  |                                                                                                                                                                                                               |
| poweredByLogo                                   | string (uri)                         | 否  |                                                                                                                                                                                                               |
| enableAnonymous                                 | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                                                                                                                                                                               |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                                                                                                                                                                               |
| enableConversationTimer                         | boolean                              | 否  |                                                                                                                                                                                                               |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                                                                                                                                                                            |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                                                                                                                                                                               |
| enableClearConversationOnTimeout                | boolean                              | 否  | Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared,...   |
| enableSatisfactionSurvey                        | boolean                              | 否  |                                                                                                                                                                                                               |
| satisfactionSurveyDelayMinutes                  | integer                              | 否  | Minutes after the last AI reply before the survey pops up, 1-60 minutes                                                                                                                                       |
| satisfactionSurveyPrompt                        | string                               | 否  | Custom survey title text; leave empty to use the localized default text of the front end                                                                                                                      |
| 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 // 非必填
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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,
  "speechPhrases": [
    "範例字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": true,
  "enableDisplayContextUsage": true,
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableShowConnectedServices": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
      "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": true,
    "enableDisplayContextUsage": true,
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableShowConnectedServices": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableClearConversationOnTimeout": 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,
    "speechPhrases": [
        "範例字串"
    ],
    "enableVoiceInput": 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,
    "enableConversationHandoff": True,
    "enableDisplayContextUsage": True,
    "enableDisplayThinking": True,
    "enableUserThinkingControl": True,
    "enableDisplayQueryMetadata": True,
    "enableDisplayHookMarkers": True,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": True,
    "enableShowConnectedServices": True,
    "enableLocation": True,
    "enableShowPoweredBy": True,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": True,
    "enableDisplayPreviousConversation": True,
    "enableDisplayConversationHistory": True,
    "enableConversationTimer": True,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": True,
    "enableClearConversationOnTimeout": 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": None,
    "preChatFormTitle": None,
    "preChatFormSubtitle": None,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": None,
    "loadingLongWaitCopyByLocale": None,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": True,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": None,
    "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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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,
            'speechPhrases' => [
                '範例字串'
            ],
            'enableVoiceInput' => 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,
            'enableConversationHandoff' => true,
            'enableDisplayContextUsage' => true,
            'enableDisplayThinking' => true,
            'enableUserThinkingControl' => true,
            'enableDisplayQueryMetadata' => true,
            'enableDisplayHookMarkers' => true,
            'hookMarkerTextInputModify' => '範例字串',
            'hookMarkerTextOutputModify' => '範例字串',
            'hookMarkerTextInputBlock' => '範例字串',
            'hookMarkerTextOutputBlock' => '範例字串',
            'enableShareConversation' => true,
            'enableShowConnectedServices' => true,
            'enableLocation' => true,
            'enableShowPoweredBy' => true,
            'poweredByLogo' => 'https://example.com/file.jpg',
            'enableAnonymous' => true,
            'enableDisplayPreviousConversation' => true,
            'enableDisplayConversationHistory' => true,
            'enableConversationTimer' => true,
            'conversationTimerDuration' => 123,
            'enableAutoNewConversationOnTimeout' => true,
            'enableClearConversationOnTimeout' => true,
            'enableSatisfactionSurvey' => true,
            'satisfactionSurveyDelayMinutes' => 123,
            'satisfactionSurveyPrompt' => '範例字串',
            'enableThemeModeToggle' => true,
            'enableDisplayFontSizeSwitch' => true,
            'defaultThemeMode' => new \stdClass(),
            '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' => new \stdClass(),
            '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
  "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (非必填)
    string
  ]
  "enableVoiceInput"?: boolean // Recordings are recognized by the platform default speech recognition engine and filled into the input box without being sent, billed by the seconds recorded. Applies to website and internal platforms except MaiGPT, which follows the MaiGPT voice input permission. (非必填)
  "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 // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (非必填)
  "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (非必填)
  "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableShowConnectedServices"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (非必填)
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (非必填)
  "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (非必填)
  "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 this page may offer voice (read-only)
  "voiceEntryRedirect": object // Where this text web chat's old ?mode=voice link goes once the organization has voice agent entries: {state: 'redirect', url} or {state: 'moved'}; null before, and when the link stays on this page behind its sign-in (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,
  "speechPhrases": [
    "回應字串"
  ],
  "enableVoiceInput": 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,
  "enableConversationHandoff": false,
  "enableDisplayContextUsage": false,
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableShowConnectedServices": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableClearConversationOnTimeout": 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,
  "voiceEntryRedirect": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "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 檔案 <a href="#web-chats-batch-qas-create" id="web-chats-batch-qas-create"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 <a href="#web-chats-batch-qas-export-excel-retrieve" id="web-chats-batch-qas-export-excel-retrieve"></a>

GET `/api/v1/web-chats/{webchatPk}/batch-qas/{id}/export-excel/`

#### 參數

| 參數名稱        | 必填 | 類型     | 說明                                                    |
| ----------- | -- | ------ | ----------------------------------------------------- |
| `id`        | ✅  | string | A UUID string identifying this Chatbot Batch QA File. |
| `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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 使用統計 <a href="#chatbots-llm-usage-statistics-list" id="chatbots-llm-usage-statistics-list"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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
[
  {
    "llmDetails": [
      {
        "chatbotId": string (uuid)
        "wordsCount": integer
        "inputTokenUsage": integer
        "outputTokenUsage": integer
        "cacheCreationInputTokens": integer
        "cacheReadInputTokens": integer
        "totalTokenUsage": integer
        "llmModelId": string (uuid)
        "llmModelName": string
        "llmModelProvider": string
      }
    ]
    "date"?: string (date) // time_granularity=day 時的日期 (非必填)
    "month"?: string (date) // time_granularity=month 時的月份（當月 1 日） (非必填)
    "totalWordsCount": integer
    "totalInputTokenUsage": integer
    "totalOutputTokenUsage": integer
    "totalCacheCreationInputTokens": integer
    "totalCacheReadInputTokens": integer
    "totalTokenUsage": integer
  }
]
```

**回應範例值**

```json
[
  [
    {
      "totalWordsCount": 511,
      "totalInputTokenUsage": 1200,
      "totalOutputTokenUsage": 300,
      "totalCacheCreationInputTokens": 0,
      "totalCacheReadInputTokens": 0,
      "totalTokenUsage": 1500,
      "month": "2025-03-01",
      "llmDetails": [
        {
          "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b",
          "wordsCount": 511,
          "inputTokenUsage": 1200,
          "outputTokenUsage": 300,
          "cacheCreationInputTokens": 0,
          "cacheReadInputTokens": 0,
          "totalTokenUsage": 1500,
          "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383",
          "llmModelName": "GPT-4o-2024-08-06",
          "llmModelProvider": "openai"
        }
      ]
    }
  ]
]
```

**狀態碼: 400**

**回應結構範例**

```typescript
{
  "detail"?: string // 非必填
  "valid_types"?: [ // 非必填
    string
  ]
}
```

**回應範例值**

```json
[
  [
    {
      "totalWordsCount": 511,
      "totalInputTokenUsage": 1200,
      "totalOutputTokenUsage": 300,
      "totalCacheCreationInputTokens": 0,
      "totalCacheReadInputTokens": 0,
      "totalTokenUsage": 1500,
      "month": "2025-03-01",
      "llmDetails": [
        {
          "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b",
          "wordsCount": 511,
          "inputTokenUsage": 1200,
          "outputTokenUsage": 300,
          "cacheCreationInputTokens": 0,
          "cacheReadInputTokens": 0,
          "totalTokenUsage": 1500,
          "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383",
          "llmModelName": "GPT-4o-2024-08-06",
          "llmModelProvider": "openai"
        }
      ]
    }
  ]
]
```

***

### 取得 AI 助理統計數據 <a href="#chatbots-statistics-list" id="chatbots-statistics-list"></a>

GET `/api/v1/chatbots/{chatbotPk}/statistics/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明                                        |
| ----------------- | -- | ------ | ----------------------------------------- |
| `chatbotPk`       | ✅  | string | A UUID string identifying this Chatbot ID |
| `endDate`         | ❌  | string | 結束日期 (YYYY-MM-DD)，預設今天                    |
| `startDate`       | ❌  | string | 開始日期 (YYYY-MM-DD)，預設今天                    |
| `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/?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/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/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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/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
[
  {
    "datetime": string // 時間戳（毫秒，字串）
    "messagesCount": integer // 訊息數量
    "conversationsCount": integer // 對話數量
    "avgMessagesPerConversation": number (double) // 平均每對話訊息數
    "avgLikesPerFeedback": number (double) // 滿意度：讚數 / (讚數 + 倒讚數)，無回饋時為 0
    "likesCount": integer // 讚數（不含開場白的回饋；日／月為區間加總）
    "dislikesCount": integer // 倒讚數（不含開場白的回饋；日／月為區間加總）
  }
]
```

**回應範例值**

```json
[
  {
    "datetime": "回應字串",
    "messagesCount": 456,
    "conversationsCount": 456,
    "avgMessagesPerConversation": 456,
    "avgLikesPerFeedback": 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/api-reference/dui-hua-widget.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
