對話 Widget

建立 Web Chat

POST /api/v1/web-chats/

請求內容

請求參數

欄位	類型	必填	說明
avatar	string (uri)	否
logo	string (uri)	否
description	string	否
cover	string (uri)	否
backUrl	string	否
isActive	boolean	否
theme	object	是
theme.primaryColor	string	否
theme.navbarTextColor	string	否
theme.conversationBackgroundColor	string	否
theme.chatbotMessageTextColor	string	否
theme.userMessageTextColor	string	否
theme.chatbotMessageBackgroundColor	string	否
theme.userMessageBackgroundColor	string	否
theme.chatbotMessageBackgroundShadowEnabled	boolean	否
theme.userMessageBackgroundShadowEnabled	boolean	否
theme.chatbotMessageGradientEnabled	boolean	否
theme.userMessageGradientEnabled	boolean	否
darkTheme	object	是
darkTheme.primaryColor	string	否
darkTheme.navbarTextColor	string	否
darkTheme.conversationBackgroundColor	string	否
darkTheme.chatbotMessageTextColor	string	否
darkTheme.userMessageTextColor	string	否
darkTheme.chatbotMessageBackgroundColor	string	否
darkTheme.userMessageBackgroundColor	string	否
darkTheme.chatbotMessageBackgroundShadowEnabled	boolean	否
darkTheme.userMessageBackgroundShadowEnabled	boolean	否
darkTheme.chatbotMessageGradientEnabled	boolean	否
darkTheme.userMessageGradientEnabled	boolean	否
enableFileUpload	boolean	否
enableDisplayCitations	boolean	否
toolDisplayMode	string (enum: full, compact, hidden)	否	full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking	boolean	否
enableUserThinkingControl	boolean	否
enableDisplayQueryMetadata	boolean	否
enableDisplayHookMarkers	boolean	否
hookMarkerTextInputModify	string	否
hookMarkerTextOutputModify	string	否
hookMarkerTextInputBlock	string	否
hookMarkerTextOutputBlock	string	否
enableShareConversation	boolean	否
enableLocation	boolean	否
enableShowPoweredBy	boolean	否
poweredByLogo	string (uri)	否
enableAnonymous	boolean	否
enableDisplayPreviousConversation	boolean	否
enableDisplayConversationHistory	boolean	否
enableConversationTimer	boolean	否
conversationTimerDuration	integer	否	計時器逾時時長，範圍 3-60 分鐘
enableAutoNewConversationOnTimeout	boolean	否
enableSatisfactionSurvey	boolean	否
satisfactionSurveyDelayMinutes	integer	否	最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘
satisfactionSurveyPrompt	string	否	自訂問卷標題文字，留空則使用前端多語系預設文字
enableThemeModeToggle	boolean	否
enableDisplayFontSizeSwitch	boolean	否
defaultThemeMode	object	否
enableDownloadCitations	boolean	否
customDomain	object (含 3 個屬性: id, domain, status)	否
customDomain.domain	string	是
enableDisplayChatbotAvatar	boolean	否
enableDisplayChatbotName	boolean	否
buttonIcon	string (uri)	否
conversationStartersDisplayCount	integer	否
preChatFormEnabled	boolean	否
preChatFormFields	object	否
preChatFormTitle	object	否
preChatFormSubtitle	object	否
loadingDisplayMode	object	否	Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale	object	否	Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale	object	否	Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds	integer	否	How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset	boolean	否	True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl	string (uri)	否
loadingAnimationAssetUrlsByStage	object	否	Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy	boolean	否	Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl	string (uri)	否
toolCardCompletedIconUrl	string (uri)	否

請求結構範例

{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "conversationStartersDisplayCount"?: integer // 非必填
  "preChatFormEnabled"?: boolean // 非必填
  "preChatFormFields"?: object // 非必填
  "preChatFormTitle"?: object // 非必填
  "preChatFormSubtitle"?: object // 非必填
  "loadingDisplayMode"?:  // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed.

* `narrative` - Narrative copy
* `brand_animation` - Brand animation (非必填)
  {
  }
  "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (非必填)
  "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (非必填)
  "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (非必填)
  "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (非必填)
  "loadingAnimationSharedAssetUrl"?: string (uri) // 非必填
  "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (非必填)
  "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (非必填)
  "toolCardRunningIconUrl"?: string (uri) // 非必填
  "toolCardCompletedIconUrl"?: string (uri) // 非必填
}

請求範例值

{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableSatisfactionSurvey": true,
  "satisfactionSurveyDelayMinutes": 123,
  "satisfactionSurveyPrompt": "範例字串",
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "buttonIcon": "https://example.com/file.jpg",
  "conversationStartersDisplayCount": 123,
  "preChatFormEnabled": true,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 123,
  "loadingAnimationUseSharedAsset": true,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": true,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/web-chats/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  };

axios.post("https://api.maiagent.ai/api/v1/web-chats/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/web-chats/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableDisplayHookMarkers": true,
      "hookMarkerTextInputModify": "範例字串",
      "hookMarkerTextOutputModify": "範例字串",
      "hookMarkerTextInputBlock": "範例字串",
      "hookMarkerTextOutputBlock": "範例字串",
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableSatisfactionSurvey": true,
      "satisfactionSurveyDelayMinutes": 123,
      "satisfactionSurveyPrompt": "範例字串",
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "buttonIcon": "https://example.com/file.jpg",
      "conversationStartersDisplayCount": 123,
      "preChatFormEnabled": true,
      "preChatFormFields": null,
      "preChatFormTitle": null,
      "preChatFormSubtitle": null,
      "loadingDisplayMode": {},
      "loadingStageCopyByLocale": null,
      "loadingLongWaitCopyByLocale": null,
      "loadingLongWaitThresholdSeconds": 123,
      "loadingAnimationUseSharedAsset": true,
      "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
      "loadingAnimationAssetUrlsByStage": null,
      "loadingTypingShowCopy": true,
      "toolCardRunningIconUrl": "https://example.com/file.jpg",
      "toolCardCompletedIconUrl": "https://example.com/file.jpg"
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

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,
            "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",
            "enableDisplayThinking": true,
            "enableUserThinkingControl": true,
            "enableDisplayQueryMetadata": true,
            "enableDisplayHookMarkers": true,
            "hookMarkerTextInputModify": "範例字串",
            "hookMarkerTextOutputModify": "範例字串",
            "hookMarkerTextInputBlock": "範例字串",
            "hookMarkerTextOutputBlock": "範例字串",
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableSatisfactionSurvey": true,
            "satisfactionSurveyDelayMinutes": 123,
            "satisfactionSurveyPrompt": "範例字串",
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "buttonIcon": "https://example.com/file.jpg",
            "conversationStartersDisplayCount": 123,
            "preChatFormEnabled": true,
            "preChatFormFields": null,
            "preChatFormTitle": null,
            "preChatFormSubtitle": null,
            "loadingDisplayMode": {},
            "loadingStageCopyByLocale": null,
            "loadingLongWaitCopyByLocale": null,
            "loadingLongWaitThresholdSeconds": 123,
            "loadingAnimationUseSharedAsset": true,
            "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
            "loadingAnimationAssetUrlsByStage": null,
            "loadingTypingShowCopy": true,
            "toolCardRunningIconUrl": "https://example.com/file.jpg",
            "toolCardCompletedIconUrl": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot.
  "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only)
  "conversationStartersDisplayCount"?: integer // 非必填
  "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option.
  "tools": [ // Expose chatbot tools to SDK for the tool_mask selector.

Name resolution prefers ``display_name`` (set on MCP tools, where
``name`` is null) and falls back to ``name`` for API tools where
``display_name`` is null. Tools missing both are skipped — SDK
should never show an unnamed tool to a contact.
    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
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableSatisfactionSurvey": false,
  "satisfactionSurveyDelayMinutes": 456,
  "satisfactionSurveyPrompt": "回應字串",
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "buttonIcon": "https://example.com/file.jpg",
  "enableCodeInterpreter": false,
  "voiceAgentEnabled": false,
  "conversationStartersDisplayCount": 456,
  "includeGreetingInContext": false,
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "preChatFormEnabled": false,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 456,
  "loadingAnimationUseSharedAsset": false,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": false,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}

---

列出 Web Chat

GET /api/v1/web-chats/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/web-chats/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

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);
  });

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)

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();
}
?>

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id": string (uuid)
    "avatar"?: string (uri) // 非必填
    "name": string
  }
]

回應範例值

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "avatar": "https://example.com/file.jpg",
    "name": "回應字串"
  }
]

---

取得特定 Web Chat

GET /api/v1/web-chats/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this web chat.

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

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();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot.
  "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only)
  "conversationStartersDisplayCount"?: integer // 非必填
  "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option.
  "tools": [ // Expose chatbot tools to SDK for the tool_mask selector.

Name resolution prefers ``display_name`` (set on MCP tools, where
``name`` is null) and falls back to ``name`` for API tools where
``display_name`` is null. Tools missing both are skipped — SDK
should never show an unnamed tool to a contact.
    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
}

回應範例值

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "測試 doc",
  "avatar": "https://example.com/static/images/default-chatbot-avatar.png",
  "logo": null,
  "description": "",
  "cover": null,
  "backUrl": "",
  "isActive": true,
  "enableSpeech": false,
  "displayGreeting": null,
  "displayConversationStarters": [],
  "theme": {
    "primaryColor": "#3854d8",
    "dialogColor": "#ddeaf6",
    "navbarTextColor": "#ffffff"
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": true,
  "poweredByLogo": null,
  "accessType": "web",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "測試 doc",
    "signAuth": {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "signSource": {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "accessType": "keycloak"
      },
      "signParams": {
        "keycloak": {
          "url": "example.com",
          "realm": "example",
          "clientId": "example"
        }
      }
    }
  }
}

---

更新 Web Chat

PUT /api/v1/web-chats/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this web chat.

請求內容

請求參數

欄位	類型	必填	說明
avatar	string (uri)	否
logo	string (uri)	否
description	string	否
cover	string (uri)	否
backUrl	string	否
isActive	boolean	否
theme	object	是
theme.primaryColor	string	否
theme.navbarTextColor	string	否
theme.conversationBackgroundColor	string	否
theme.chatbotMessageTextColor	string	否
theme.userMessageTextColor	string	否
theme.chatbotMessageBackgroundColor	string	否
theme.userMessageBackgroundColor	string	否
theme.chatbotMessageBackgroundShadowEnabled	boolean	否
theme.userMessageBackgroundShadowEnabled	boolean	否
theme.chatbotMessageGradientEnabled	boolean	否
theme.userMessageGradientEnabled	boolean	否
darkTheme	object	是
darkTheme.primaryColor	string	否
darkTheme.navbarTextColor	string	否
darkTheme.conversationBackgroundColor	string	否
darkTheme.chatbotMessageTextColor	string	否
darkTheme.userMessageTextColor	string	否
darkTheme.chatbotMessageBackgroundColor	string	否
darkTheme.userMessageBackgroundColor	string	否
darkTheme.chatbotMessageBackgroundShadowEnabled	boolean	否
darkTheme.userMessageBackgroundShadowEnabled	boolean	否
darkTheme.chatbotMessageGradientEnabled	boolean	否
darkTheme.userMessageGradientEnabled	boolean	否
enableFileUpload	boolean	否
enableDisplayCitations	boolean	否
toolDisplayMode	string (enum: full, compact, hidden)	否	full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking	boolean	否
enableUserThinkingControl	boolean	否
enableDisplayQueryMetadata	boolean	否
enableDisplayHookMarkers	boolean	否
hookMarkerTextInputModify	string	否
hookMarkerTextOutputModify	string	否
hookMarkerTextInputBlock	string	否
hookMarkerTextOutputBlock	string	否
enableShareConversation	boolean	否
enableLocation	boolean	否
enableShowPoweredBy	boolean	否
poweredByLogo	string (uri)	否
enableAnonymous	boolean	否
enableDisplayPreviousConversation	boolean	否
enableDisplayConversationHistory	boolean	否
enableConversationTimer	boolean	否
conversationTimerDuration	integer	否	計時器逾時時長，範圍 3-60 分鐘
enableAutoNewConversationOnTimeout	boolean	否
enableSatisfactionSurvey	boolean	否
satisfactionSurveyDelayMinutes	integer	否	最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘
satisfactionSurveyPrompt	string	否	自訂問卷標題文字，留空則使用前端多語系預設文字
enableThemeModeToggle	boolean	否
enableDisplayFontSizeSwitch	boolean	否
defaultThemeMode	object	否
enableDownloadCitations	boolean	否
customDomain	object (含 3 個屬性: id, domain, status)	否
customDomain.domain	string	是
enableDisplayChatbotAvatar	boolean	否
enableDisplayChatbotName	boolean	否
buttonIcon	string (uri)	否
conversationStartersDisplayCount	integer	否
preChatFormEnabled	boolean	否
preChatFormFields	object	否
preChatFormTitle	object	否
preChatFormSubtitle	object	否
loadingDisplayMode	object	否	Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale	object	否	Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale	object	否	Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds	integer	否	How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset	boolean	否	True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl	string (uri)	否
loadingAnimationAssetUrlsByStage	object	否	Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy	boolean	否	Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl	string (uri)	否
toolCardCompletedIconUrl	string (uri)	否

請求結構範例

{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "conversationStartersDisplayCount"?: integer // 非必填
  "preChatFormEnabled"?: boolean // 非必填
  "preChatFormFields"?: object // 非必填
  "preChatFormTitle"?: object // 非必填
  "preChatFormSubtitle"?: object // 非必填
  "loadingDisplayMode"?:  // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed.

* `narrative` - Narrative copy
* `brand_animation` - Brand animation (非必填)
  {
  }
  "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (非必填)
  "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (非必填)
  "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (非必填)
  "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (非必填)
  "loadingAnimationSharedAssetUrl"?: string (uri) // 非必填
  "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (非必填)
  "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (非必填)
  "toolCardRunningIconUrl"?: string (uri) // 非必填
  "toolCardCompletedIconUrl"?: string (uri) // 非必填
}

請求範例值

{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableSatisfactionSurvey": true,
  "satisfactionSurveyDelayMinutes": 123,
  "satisfactionSurveyPrompt": "範例字串",
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "buttonIcon": "https://example.com/file.jpg",
  "conversationStartersDisplayCount": 123,
  "preChatFormEnabled": true,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 123,
  "loadingAnimationUseSharedAsset": true,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": true,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  };

axios.put("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableDisplayHookMarkers": true,
      "hookMarkerTextInputModify": "範例字串",
      "hookMarkerTextOutputModify": "範例字串",
      "hookMarkerTextInputBlock": "範例字串",
      "hookMarkerTextOutputBlock": "範例字串",
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableSatisfactionSurvey": true,
      "satisfactionSurveyDelayMinutes": 123,
      "satisfactionSurveyPrompt": "範例字串",
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "buttonIcon": "https://example.com/file.jpg",
      "conversationStartersDisplayCount": 123,
      "preChatFormEnabled": true,
      "preChatFormFields": null,
      "preChatFormTitle": null,
      "preChatFormSubtitle": null,
      "loadingDisplayMode": {},
      "loadingStageCopyByLocale": null,
      "loadingLongWaitCopyByLocale": null,
      "loadingLongWaitThresholdSeconds": 123,
      "loadingAnimationUseSharedAsset": true,
      "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
      "loadingAnimationAssetUrlsByStage": null,
      "loadingTypingShowCopy": true,
      "toolCardRunningIconUrl": "https://example.com/file.jpg",
      "toolCardCompletedIconUrl": "https://example.com/file.jpg"
    }

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

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,
            "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",
            "enableDisplayThinking": true,
            "enableUserThinkingControl": true,
            "enableDisplayQueryMetadata": true,
            "enableDisplayHookMarkers": true,
            "hookMarkerTextInputModify": "範例字串",
            "hookMarkerTextOutputModify": "範例字串",
            "hookMarkerTextInputBlock": "範例字串",
            "hookMarkerTextOutputBlock": "範例字串",
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableSatisfactionSurvey": true,
            "satisfactionSurveyDelayMinutes": 123,
            "satisfactionSurveyPrompt": "範例字串",
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "buttonIcon": "https://example.com/file.jpg",
            "conversationStartersDisplayCount": 123,
            "preChatFormEnabled": true,
            "preChatFormFields": null,
            "preChatFormTitle": null,
            "preChatFormSubtitle": null,
            "loadingDisplayMode": {},
            "loadingStageCopyByLocale": null,
            "loadingLongWaitCopyByLocale": null,
            "loadingLongWaitThresholdSeconds": 123,
            "loadingAnimationUseSharedAsset": true,
            "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
            "loadingAnimationAssetUrlsByStage": null,
            "loadingTypingShowCopy": true,
            "toolCardRunningIconUrl": "https://example.com/file.jpg",
            "toolCardCompletedIconUrl": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot.
  "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only)
  "conversationStartersDisplayCount"?: integer // 非必填
  "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option.
  "tools": [ // Expose chatbot tools to SDK for the tool_mask selector.

Name resolution prefers ``display_name`` (set on MCP tools, where
``name`` is null) and falls back to ``name`` for API tools where
``display_name`` is null. Tools missing both are skipped — SDK
should never show an unnamed tool to a contact.
    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
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableSatisfactionSurvey": false,
  "satisfactionSurveyDelayMinutes": 456,
  "satisfactionSurveyPrompt": "回應字串",
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "buttonIcon": "https://example.com/file.jpg",
  "enableCodeInterpreter": false,
  "voiceAgentEnabled": false,
  "conversationStartersDisplayCount": 456,
  "includeGreetingInContext": false,
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "preChatFormEnabled": false,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 456,
  "loadingAnimationUseSharedAsset": false,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": false,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}

---

部分更新 Web Chat

PATCH /api/v1/web-chats/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this web chat.

請求內容

請求參數

欄位	類型	必填	說明
avatar	string (uri)	否
logo	string (uri)	否
description	string	否
cover	string (uri)	否
backUrl	string	否
isActive	boolean	否
theme	object	否
theme.primaryColor	string	否
theme.navbarTextColor	string	否
theme.conversationBackgroundColor	string	否
theme.chatbotMessageTextColor	string	否
theme.userMessageTextColor	string	否
theme.chatbotMessageBackgroundColor	string	否
theme.userMessageBackgroundColor	string	否
theme.chatbotMessageBackgroundShadowEnabled	boolean	否
theme.userMessageBackgroundShadowEnabled	boolean	否
theme.chatbotMessageGradientEnabled	boolean	否
theme.userMessageGradientEnabled	boolean	否
darkTheme	object	否
darkTheme.primaryColor	string	否
darkTheme.navbarTextColor	string	否
darkTheme.conversationBackgroundColor	string	否
darkTheme.chatbotMessageTextColor	string	否
darkTheme.userMessageTextColor	string	否
darkTheme.chatbotMessageBackgroundColor	string	否
darkTheme.userMessageBackgroundColor	string	否
darkTheme.chatbotMessageBackgroundShadowEnabled	boolean	否
darkTheme.userMessageBackgroundShadowEnabled	boolean	否
darkTheme.chatbotMessageGradientEnabled	boolean	否
darkTheme.userMessageGradientEnabled	boolean	否
enableFileUpload	boolean	否
enableDisplayCitations	boolean	否
toolDisplayMode	string (enum: full, compact, hidden)	否	full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking	boolean	否
enableUserThinkingControl	boolean	否
enableDisplayQueryMetadata	boolean	否
enableDisplayHookMarkers	boolean	否
hookMarkerTextInputModify	string	否
hookMarkerTextOutputModify	string	否
hookMarkerTextInputBlock	string	否
hookMarkerTextOutputBlock	string	否
enableShareConversation	boolean	否
enableLocation	boolean	否
enableShowPoweredBy	boolean	否
poweredByLogo	string (uri)	否
enableAnonymous	boolean	否
enableDisplayPreviousConversation	boolean	否
enableDisplayConversationHistory	boolean	否
enableConversationTimer	boolean	否
conversationTimerDuration	integer	否	計時器逾時時長，範圍 3-60 分鐘
enableAutoNewConversationOnTimeout	boolean	否
enableSatisfactionSurvey	boolean	否
satisfactionSurveyDelayMinutes	integer	否	最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘
satisfactionSurveyPrompt	string	否	自訂問卷標題文字，留空則使用前端多語系預設文字
enableThemeModeToggle	boolean	否
enableDisplayFontSizeSwitch	boolean	否
defaultThemeMode	object	否
enableDownloadCitations	boolean	否
customDomain	object (含 3 個屬性: id, domain, status)	否
customDomain.domain	string	是
enableDisplayChatbotAvatar	boolean	否
enableDisplayChatbotName	boolean	否
buttonIcon	string (uri)	否
conversationStartersDisplayCount	integer	否
preChatFormEnabled	boolean	否
preChatFormFields	object	否
preChatFormTitle	object	否
preChatFormSubtitle	object	否
loadingDisplayMode	object	否	Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale	object	否	Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale	object	否	Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds	integer	否	How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset	boolean	否	True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl	string (uri)	否
loadingAnimationAssetUrlsByStage	object	否	Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy	boolean	否	Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl	string (uri)	否
toolCardCompletedIconUrl	string (uri)	否

請求結構範例

{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme"?: { // 非必填
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme"?: { // 非必填
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "conversationStartersDisplayCount"?: integer // 非必填
  "preChatFormEnabled"?: boolean // 非必填
  "preChatFormFields"?: object // 非必填
  "preChatFormTitle"?: object // 非必填
  "preChatFormSubtitle"?: object // 非必填
  "loadingDisplayMode"?:  // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed.

* `narrative` - Narrative copy
* `brand_animation` - Brand animation (非必填)
  {
  }
  "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (非必填)
  "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (非必填)
  "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (非必填)
  "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (非必填)
  "loadingAnimationSharedAssetUrl"?: string (uri) // 非必填
  "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (非必填)
  "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (非必填)
  "toolCardRunningIconUrl"?: string (uri) // 非必填
  "toolCardCompletedIconUrl"?: string (uri) // 非必填
}

請求範例值

{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableSatisfactionSurvey": true,
  "satisfactionSurveyDelayMinutes": 123,
  "satisfactionSurveyPrompt": "範例字串",
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "buttonIcon": "https://example.com/file.jpg",
  "conversationStartersDisplayCount": 123,
  "preChatFormEnabled": true,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 123,
  "loadingAnimationUseSharedAsset": true,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": true,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  };

axios.patch("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableDisplayHookMarkers": true,
      "hookMarkerTextInputModify": "範例字串",
      "hookMarkerTextOutputModify": "範例字串",
      "hookMarkerTextInputBlock": "範例字串",
      "hookMarkerTextOutputBlock": "範例字串",
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableSatisfactionSurvey": true,
      "satisfactionSurveyDelayMinutes": 123,
      "satisfactionSurveyPrompt": "範例字串",
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "buttonIcon": "https://example.com/file.jpg",
      "conversationStartersDisplayCount": 123,
      "preChatFormEnabled": true,
      "preChatFormFields": null,
      "preChatFormTitle": null,
      "preChatFormSubtitle": null,
      "loadingDisplayMode": {},
      "loadingStageCopyByLocale": null,
      "loadingLongWaitCopyByLocale": null,
      "loadingLongWaitThresholdSeconds": 123,
      "loadingAnimationUseSharedAsset": true,
      "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
      "loadingAnimationAssetUrlsByStage": null,
      "loadingTypingShowCopy": true,
      "toolCardRunningIconUrl": "https://example.com/file.jpg",
      "toolCardCompletedIconUrl": "https://example.com/file.jpg"
    }

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

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,
            "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",
            "enableDisplayThinking": true,
            "enableUserThinkingControl": true,
            "enableDisplayQueryMetadata": true,
            "enableDisplayHookMarkers": true,
            "hookMarkerTextInputModify": "範例字串",
            "hookMarkerTextOutputModify": "範例字串",
            "hookMarkerTextInputBlock": "範例字串",
            "hookMarkerTextOutputBlock": "範例字串",
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableSatisfactionSurvey": true,
            "satisfactionSurveyDelayMinutes": 123,
            "satisfactionSurveyPrompt": "範例字串",
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "buttonIcon": "https://example.com/file.jpg",
            "conversationStartersDisplayCount": 123,
            "preChatFormEnabled": true,
            "preChatFormFields": null,
            "preChatFormTitle": null,
            "preChatFormSubtitle": null,
            "loadingDisplayMode": {},
            "loadingStageCopyByLocale": null,
            "loadingLongWaitCopyByLocale": null,
            "loadingLongWaitThresholdSeconds": 123,
            "loadingAnimationUseSharedAsset": true,
            "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
            "loadingAnimationAssetUrlsByStage": null,
            "loadingTypingShowCopy": true,
            "toolCardRunningIconUrl": "https://example.com/file.jpg",
            "toolCardCompletedIconUrl": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot.
  "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only)
  "conversationStartersDisplayCount"?: integer // 非必填
  "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option.
  "tools": [ // Expose chatbot tools to SDK for the tool_mask selector.

Name resolution prefers ``display_name`` (set on MCP tools, where
``name`` is null) and falls back to ``name`` for API tools where
``display_name`` is null. Tools missing both are skipped — SDK
should never show an unnamed tool to a contact.
    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
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableSatisfactionSurvey": false,
  "satisfactionSurveyDelayMinutes": 456,
  "satisfactionSurveyPrompt": "回應字串",
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "buttonIcon": "https://example.com/file.jpg",
  "enableCodeInterpreter": false,
  "voiceAgentEnabled": false,
  "conversationStartersDisplayCount": 456,
  "includeGreetingInContext": false,
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "preChatFormEnabled": false,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 456,
  "loadingAnimationUseSharedAsset": false,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": false,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}

---

設定聯絡人憑證

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

請求結構範例

{
  "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 (非必填)
}

請求範例值

{
  "sourceId": "範例字串",
  "name": "範例名稱",
  "mcpCredentials": {
    "toolId": "550e8400-e29b-41d4-a716-446655440000",
    "headers": {}
  },
  "embedOrigin": "範例字串",
  "ts": 123,
  "sig": "範例字串"
}

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

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": {}
            },
            "embedOrigin": "範例字串",
            "ts": 123,
            "sig": "範例字串"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "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}/).
}

回應範例值

{
  "contactId": "550e8400-e29b-41d4-a716-446655440000",
  "created": false
}

狀態碼: 400 - No response body

---

取得語音助理 Token

POST /api/v1/web-chats/{id}/voice-agent/token/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this web chat.

請求內容

請求參數

欄位	類型	必填	說明
avatar	string (uri)	否
logo	string (uri)	否
description	string	否
cover	string (uri)	否
backUrl	string	否
isActive	boolean	否
theme	object	是
theme.primaryColor	string	否
theme.navbarTextColor	string	否
theme.conversationBackgroundColor	string	否
theme.chatbotMessageTextColor	string	否
theme.userMessageTextColor	string	否
theme.chatbotMessageBackgroundColor	string	否
theme.userMessageBackgroundColor	string	否
theme.chatbotMessageBackgroundShadowEnabled	boolean	否
theme.userMessageBackgroundShadowEnabled	boolean	否
theme.chatbotMessageGradientEnabled	boolean	否
theme.userMessageGradientEnabled	boolean	否
darkTheme	object	是
darkTheme.primaryColor	string	否
darkTheme.navbarTextColor	string	否
darkTheme.conversationBackgroundColor	string	否
darkTheme.chatbotMessageTextColor	string	否
darkTheme.userMessageTextColor	string	否
darkTheme.chatbotMessageBackgroundColor	string	否
darkTheme.userMessageBackgroundColor	string	否
darkTheme.chatbotMessageBackgroundShadowEnabled	boolean	否
darkTheme.userMessageBackgroundShadowEnabled	boolean	否
darkTheme.chatbotMessageGradientEnabled	boolean	否
darkTheme.userMessageGradientEnabled	boolean	否
enableFileUpload	boolean	否
enableDisplayCitations	boolean	否
toolDisplayMode	string (enum: full, compact, hidden)	否	full: Full ; compact: Compact ; hidden: Hidden;
enableDisplayThinking	boolean	否
enableUserThinkingControl	boolean	否
enableDisplayQueryMetadata	boolean	否
enableDisplayHookMarkers	boolean	否
hookMarkerTextInputModify	string	否
hookMarkerTextOutputModify	string	否
hookMarkerTextInputBlock	string	否
hookMarkerTextOutputBlock	string	否
enableShareConversation	boolean	否
enableLocation	boolean	否
enableShowPoweredBy	boolean	否
poweredByLogo	string (uri)	否
enableAnonymous	boolean	否
enableDisplayPreviousConversation	boolean	否
enableDisplayConversationHistory	boolean	否
enableConversationTimer	boolean	否
conversationTimerDuration	integer	否	計時器逾時時長，範圍 3-60 分鐘
enableAutoNewConversationOnTimeout	boolean	否
enableSatisfactionSurvey	boolean	否
satisfactionSurveyDelayMinutes	integer	否	最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘
satisfactionSurveyPrompt	string	否	自訂問卷標題文字，留空則使用前端多語系預設文字
enableThemeModeToggle	boolean	否
enableDisplayFontSizeSwitch	boolean	否
defaultThemeMode	object	否
enableDownloadCitations	boolean	否
customDomain	object (含 3 個屬性: id, domain, status)	否
customDomain.domain	string	是
enableDisplayChatbotAvatar	boolean	否
enableDisplayChatbotName	boolean	否
buttonIcon	string (uri)	否
conversationStartersDisplayCount	integer	否
preChatFormEnabled	boolean	否
preChatFormFields	object	否
preChatFormTitle	object	否
preChatFormSubtitle	object	否
loadingDisplayMode	object	否	Waiting-experience style. narrative shows per-stage copy; brand_animation plays the uploaded asset and hides every system narration line. Defaults to narrative, which with no copy configured beh...
loadingStageCopyByLocale	object	否	Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a...
loadingLongWaitCopyByLocale	object	否	Locale-keyed line shown once the wait exceeds loading_long_wait_threshold_seconds, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt...
loadingLongWaitThresholdSeconds	integer	否	How long a single reply must be pending before the long-wait copy appears.
loadingAnimationUseSharedAsset	boolean	否	True (default) means every stage plays loading_animation_shared_asset_url, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ...
loadingAnimationSharedAssetUrl	string (uri)	否
loadingAnimationAssetUrlsByStage	object	否	Shaped {stage: url} keyed by LoadingStage. Only consulted when loading_animation_use_shared_asset is False; a missing stage falls back to the shared asset.
loadingTypingShowCopy	boolean	否	Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line....
toolCardRunningIconUrl	string (uri)	否
toolCardCompletedIconUrl	string (uri)	否

請求結構範例

{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "conversationStartersDisplayCount"?: integer // 非必填
  "preChatFormEnabled"?: boolean // 非必填
  "preChatFormFields"?: object // 非必填
  "preChatFormTitle"?: object // 非必填
  "preChatFormSubtitle"?: object // 非必填
  "loadingDisplayMode"?:  // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed.

* `narrative` - Narrative copy
* `brand_animation` - Brand animation (非必填)
  {
  }
  "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (非必填)
  "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (非必填)
  "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (非必填)
  "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (非必填)
  "loadingAnimationSharedAssetUrl"?: string (uri) // 非必填
  "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (非必填)
  "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (非必填)
  "toolCardRunningIconUrl"?: string (uri) // 非必填
  "toolCardCompletedIconUrl"?: string (uri) // 非必填
}

請求範例值

{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableDisplayHookMarkers": true,
  "hookMarkerTextInputModify": "範例字串",
  "hookMarkerTextOutputModify": "範例字串",
  "hookMarkerTextInputBlock": "範例字串",
  "hookMarkerTextOutputBlock": "範例字串",
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableSatisfactionSurvey": true,
  "satisfactionSurveyDelayMinutes": 123,
  "satisfactionSurveyPrompt": "範例字串",
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "buttonIcon": "https://example.com/file.jpg",
  "conversationStartersDisplayCount": 123,
  "preChatFormEnabled": true,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 123,
  "loadingAnimationUseSharedAsset": true,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": true,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableDisplayHookMarkers": true,
    "hookMarkerTextInputModify": "範例字串",
    "hookMarkerTextOutputModify": "範例字串",
    "hookMarkerTextInputBlock": "範例字串",
    "hookMarkerTextOutputBlock": "範例字串",
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableSatisfactionSurvey": true,
    "satisfactionSurveyDelayMinutes": 123,
    "satisfactionSurveyPrompt": "範例字串",
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "buttonIcon": "https://example.com/file.jpg",
    "conversationStartersDisplayCount": 123,
    "preChatFormEnabled": true,
    "preChatFormFields": null,
    "preChatFormTitle": null,
    "preChatFormSubtitle": null,
    "loadingDisplayMode": {},
    "loadingStageCopyByLocale": null,
    "loadingLongWaitCopyByLocale": null,
    "loadingLongWaitThresholdSeconds": 123,
    "loadingAnimationUseSharedAsset": true,
    "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
    "loadingAnimationAssetUrlsByStage": null,
    "loadingTypingShowCopy": true,
    "toolCardRunningIconUrl": "https://example.com/file.jpg",
    "toolCardCompletedIconUrl": "https://example.com/file.jpg"
  };

axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableDisplayHookMarkers": true,
      "hookMarkerTextInputModify": "範例字串",
      "hookMarkerTextOutputModify": "範例字串",
      "hookMarkerTextInputBlock": "範例字串",
      "hookMarkerTextOutputBlock": "範例字串",
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableSatisfactionSurvey": true,
      "satisfactionSurveyDelayMinutes": 123,
      "satisfactionSurveyPrompt": "範例字串",
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "buttonIcon": "https://example.com/file.jpg",
      "conversationStartersDisplayCount": 123,
      "preChatFormEnabled": true,
      "preChatFormFields": null,
      "preChatFormTitle": null,
      "preChatFormSubtitle": null,
      "loadingDisplayMode": {},
      "loadingStageCopyByLocale": null,
      "loadingLongWaitCopyByLocale": null,
      "loadingLongWaitThresholdSeconds": 123,
      "loadingAnimationUseSharedAsset": true,
      "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
      "loadingAnimationAssetUrlsByStage": null,
      "loadingTypingShowCopy": true,
      "toolCardRunningIconUrl": "https://example.com/file.jpg",
      "toolCardCompletedIconUrl": "https://example.com/file.jpg"
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

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,
            "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",
            "enableDisplayThinking": true,
            "enableUserThinkingControl": true,
            "enableDisplayQueryMetadata": true,
            "enableDisplayHookMarkers": true,
            "hookMarkerTextInputModify": "範例字串",
            "hookMarkerTextOutputModify": "範例字串",
            "hookMarkerTextInputBlock": "範例字串",
            "hookMarkerTextOutputBlock": "範例字串",
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableSatisfactionSurvey": true,
            "satisfactionSurveyDelayMinutes": 123,
            "satisfactionSurveyPrompt": "範例字串",
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "buttonIcon": "https://example.com/file.jpg",
            "conversationStartersDisplayCount": 123,
            "preChatFormEnabled": true,
            "preChatFormFields": null,
            "preChatFormTitle": null,
            "preChatFormSubtitle": null,
            "loadingDisplayMode": {},
            "loadingStageCopyByLocale": null,
            "loadingLongWaitCopyByLocale": null,
            "loadingLongWaitThresholdSeconds": 123,
            "loadingAnimationUseSharedAsset": true,
            "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
            "loadingAnimationAssetUrlsByStage": null,
            "loadingTypingShowCopy": true,
            "toolCardRunningIconUrl": "https://example.com/file.jpg",
            "toolCardCompletedIconUrl": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableDisplayHookMarkers"?: boolean // 非必填
  "hookMarkerTextInputModify"?: string // 非必填
  "hookMarkerTextOutputModify"?: string // 非必填
  "hookMarkerTextInputBlock"?: string // 非必填
  "hookMarkerTextOutputBlock"?: string // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableSatisfactionSurvey"?: boolean // 非必填
  "satisfactionSurveyDelayMinutes"?: integer // 最後一則 AI 回覆後幾分鐘彈出問卷，範圍 1-60 分鐘 (非必填)
  "satisfactionSurveyPrompt"?: string // 自訂問卷標題文字，留空則使用前端多語系預設文字 (非必填)
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "buttonIcon"?: string (uri) // 非必填
  "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot.
  "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only)
  "conversationStartersDisplayCount"?: integer // 非必填
  "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option.
  "tools": [ // Expose chatbot tools to SDK for the tool_mask selector.

Name resolution prefers ``display_name`` (set on MCP tools, where
``name`` is null) and falls back to ``name`` for API tools where
``display_name`` is null. Tools missing both are skipped — SDK
should never show an unnamed tool to a contact.
    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
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableDisplayHookMarkers": false,
  "hookMarkerTextInputModify": "回應字串",
  "hookMarkerTextOutputModify": "回應字串",
  "hookMarkerTextInputBlock": "回應字串",
  "hookMarkerTextOutputBlock": "回應字串",
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "enableSatisfactionSurvey": false,
  "satisfactionSurveyDelayMinutes": 456,
  "satisfactionSurveyPrompt": "回應字串",
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "buttonIcon": "https://example.com/file.jpg",
  "enableCodeInterpreter": false,
  "voiceAgentEnabled": false,
  "conversationStartersDisplayCount": 456,
  "includeGreetingInContext": false,
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "preChatFormEnabled": false,
  "preChatFormFields": null,
  "preChatFormTitle": null,
  "preChatFormSubtitle": null,
  "loadingDisplayMode": {},
  "loadingStageCopyByLocale": null,
  "loadingLongWaitCopyByLocale": null,
  "loadingLongWaitThresholdSeconds": 456,
  "loadingAnimationUseSharedAsset": false,
  "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg",
  "loadingAnimationAssetUrlsByStage": null,
  "loadingTypingShowCopy": false,
  "toolCardRunningIconUrl": "https://example.com/file.jpg",
  "toolCardCompletedIconUrl": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}

---

上傳批次 QA 檔案

POST /api/v1/web-chats/{webchatPk}/batch-qas/

參數

參數名稱	必填	類型	說明
webchatPk	✅	string

請求內容

請求參數

欄位	類型	必填	說明
file	string (uri)	是

請求結構範例

{
  "file": string (uri)
}

請求範例值

{
  "file": "https://example.com/file.jpg"
}

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

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();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "file": string (uri)
  "createdAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "file": "https://example.com/file.jpg",
  "createdAt": "回應字串"
}

---

匯出批次 QA 為 Excel

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

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Chatbot 批次問答檔案.
webchatPk	✅	string

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

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();
}
?>

回應內容

狀態碼	說明
200	Excel 檔案下載

---

取得 LLM 使用統計

GET /api/v1/chatbots/{chatbotPk}/llm-usage-statistics/

參數

參數名稱	必填	類型	說明
chatbotPk	✅	string	A UUID string identifying this Chatbot ID
endDate	❌	string	結束日期，格式: YYYY-MM-DD
startDate	✅	string	開始日期，格式: YYYY-MM-DD
timeGranularity	✅	string	時間粒度 (day/month)

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

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();
}
?>

回應內容

狀態碼: 200

回應結構範例

[
  {
    "date": string (date)
  }
]

回應範例值

[
  [
    {
      "totalWordsCount": 511,
      "month": "2025-03-01",
      "llmDetails": [
        {
          "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b",
          "wordsCount": 511,
          "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383",
          "llmModelName": "GPT-4o-2024-08-06",
          "llmModelProvider": "openai"
        }
      ]
    }
  ]
]

狀態碼: 400

回應結構範例

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

回應範例值

[
  [
    {
      "totalWordsCount": 511,
      "month": "2025-03-01",
      "llmDetails": [
        {
          "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b",
          "wordsCount": 511,
          "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383",
          "llmModelName": "GPT-4o-2024-08-06",
          "llmModelProvider": "openai"
        }
      ]
    }
  ]
]

---

取得 AI 助理統計數據

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

參數

參數名稱	必填	類型	說明
chatbotPk	✅	string	A UUID string identifying this Chatbot ID
datetimeFrom	❌	string	開始時間
datetimeTo	❌	string	結束時間
timeGranularity	❌	string	時間粒度 (hour/day/month)

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

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/?datetimeFrom=example&datetimeTo=example&timeGranularity=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

[
  {
    "datetime": integer // 時間戳（毫秒）
    "messagesCount": integer // 訊息數量
    "conversationsCount": integer // 對話數量
    "likesCount": integer // 按讚數量
    "dislikesCount": integer // 不喜歡數量
  }
]

回應範例值

[
  {
    "datetime": 456,
    "messagesCount": 456,
    "conversationsCount": 456,
    "likesCount": 456,
    "dislikesCount": 456
  }
]

---