# 對話 Widget

### 建立 Web Chat <a href="#web-chat" id="web-chat"></a>

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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/web-chats/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/web-chats/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "avatar": "https://example.com/file.jpg",
            "logo": "https://example.com/file.jpg",
            "description": "範例字串",
            "cover": "https://example.com/file.jpg",
            "backUrl": "範例字串",
            "isActive": true,
            "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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 建立 Web Chat <a href="#web-chat" id="web-chat"></a>

POST `/api/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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/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,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 列出 Web Chat <a href="#web-chat" id="web-chat"></a>

GET `/api/v1/web-chats/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

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

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/web-chats/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

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

**回應範例值**

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

***

### 列出 Web Chat <a href="#web-chat" id="web-chat"></a>

GET `/api/web-chats/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

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

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/web-chats/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/web-chats/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

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

**回應範例值**

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

***

### 取得特定 Web Chat <a href="#web-chat" id="web-chat"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "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 // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

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

***

### 取得特定 Web Chat <a href="#web-chat" id="web-chat"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

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

***

### 更新 Web Chat <a href="#web-chat" id="web-chat"></a>

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

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                                              | 類型                                   | 必填 | 說明                                                    |
| ----------------------------------------------- | ------------------------------------ | -- | ----------------------------------------------------- |
| avatar                                          | string (uri)                         | 否  |                                                       |
| logo                                            | string (uri)                         | 否  |                                                       |
| description                                     | string                               | 否  |                                                       |
| cover                                           | string (uri)                         | 否  |                                                       |
| backUrl                                         | string                               | 否  |                                                       |
| isActive                                        | boolean                              | 否  |                                                       |
| 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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "avatar": "https://example.com/file.jpg",
            "logo": "https://example.com/file.jpg",
            "description": "範例字串",
            "cover": "https://example.com/file.jpg",
            "backUrl": "範例字串",
            "isActive": true,
            "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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 更新 Web Chat <a href="#web-chat" id="web-chat"></a>

PUT `/api/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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/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,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/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,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 部分更新 Web Chat <a href="#web-chat" id="web-chat"></a>

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

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                                              | 類型                                   | 必填 | 說明                                                    |
| ----------------------------------------------- | ------------------------------------ | -- | ----------------------------------------------------- |
| avatar                                          | string (uri)                         | 否  |                                                       |
| logo                                            | string (uri)                         | 否  |                                                       |
| description                                     | string                               | 否  |                                                       |
| cover                                           | string (uri)                         | 否  |                                                       |
| backUrl                                         | string                               | 否  |                                                       |
| isActive                                        | boolean                              | 否  |                                                       |
| 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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme"?: { // 非必填
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme"?: { // 非必填
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "avatar": "https://example.com/file.jpg",
            "logo": "https://example.com/file.jpg",
            "description": "範例字串",
            "cover": "https://example.com/file.jpg",
            "backUrl": "範例字串",
            "isActive": true,
            "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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 部分更新 Web Chat <a href="#web-chat" id="web-chat"></a>

PATCH `/api/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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme"?: { // 非必填
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme"?: { // 非必填
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/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,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/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,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 設定聯絡人憑證 <a href="#undefined" id="undefined"></a>

POST `/api/v1/web-chats/{id}/setup-contact-credentials/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                     | 類型                                | 必填 | 說明                                |
| ---------------------- | --------------------------------- | -- | --------------------------------- |
| sourceId               | string                            | 是  | Unique identifier for the contact |
| name                   | string                            | 否  | Contact display name              |
| mcpCredentials         | object (含 2 個屬性: toolId, headers) | 否  | MCP credentials configuration     |
| mcpCredentials.toolId  | string (uuid)                     | 是  | MCP Tool ID                       |
| mcpCredentials.headers | object                            | 否  | Authentication headers            |

**請求結構範例**

```typescript
{
  "sourceId": string // Unique identifier for the contact
  "name"?: string // Contact display name (非必填)
  "mcpCredentials"?:  // MCP credentials configuration (非必填)
  {
    "toolId": string (uuid) // MCP Tool ID
    "headers"?: object // Authentication headers (非必填)
  }
}
```

**請求範例值**

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "範例字串",
    "name": "範例名稱",
    "mcpCredentials": {
      "toolId": "550e8400-e29b-41d4-a716-446655440000",
      "headers": {}
    }
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "sourceId": "範例字串",
    "name": "範例名稱",
    "mcpCredentials": {
      "toolId": "550e8400-e29b-41d4-a716-446655440000",
      "headers": {}
    }
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# 請求內容 (payload)
data = {
      "sourceId": "範例字串",
      "name": "範例名稱",
      "mcpCredentials": {
        "toolId": "550e8400-e29b-41d4-a716-446655440000",
        "headers": {}
      }
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "sourceId": "範例字串",
            "name": "範例名稱",
            "mcpCredentials": {
                "toolId": "550e8400-e29b-41d4-a716-446655440000",
                "headers": {}
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "contactId": string (uuid) // The created or existing contact ID
}
```

**回應範例值**

```json
{
  "contactId": "550e8400-e29b-41d4-a716-446655440000"
}
```

**狀態碼: 400 - No response body**

***

### 設定聯絡人憑證 <a href="#undefined" id="undefined"></a>

POST `/api/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            |

**請求結構範例**

```typescript
{
  "sourceId": string // Unique identifier for the contact
  "name"?: string // Contact display name (非必填)
  "mcpCredentials"?:  // MCP credentials configuration (非必填)
  {
    "toolId": string (uuid) // MCP Tool ID
    "headers"?: object // Authentication headers (非必填)
  }
}
```

**請求範例值**

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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": {}
    }
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "sourceId": "範例字串",
    "name": "範例名稱",
    "mcpCredentials": {
      "toolId": "550e8400-e29b-41d4-a716-446655440000",
      "headers": {}
    }
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/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": {}
      }
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/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": {}
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "contactId": string (uuid) // The created or existing contact ID
}
```

**回應範例值**

```json
{
  "contactId": "550e8400-e29b-41d4-a716-446655440000"
}
```

**狀態碼: 400 - No response body**

***

### 取得語音助理 Token <a href="#token" id="token"></a>

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

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                                              | 類型                                   | 必填 | 說明                                                    |
| ----------------------------------------------- | ------------------------------------ | -- | ----------------------------------------------------- |
| avatar                                          | string (uri)                         | 否  |                                                       |
| logo                                            | string (uri)                         | 否  |                                                       |
| description                                     | string                               | 否  |                                                       |
| cover                                           | string (uri)                         | 否  |                                                       |
| backUrl                                         | string                               | 否  |                                                       |
| isActive                                        | boolean                              | 否  |                                                       |
| 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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# 請求內容 (payload)
data = {
      "avatar": "https://example.com/file.jpg",
      "logo": "https://example.com/file.jpg",
      "description": "範例字串",
      "cover": "https://example.com/file.jpg",
      "backUrl": "範例字串",
      "isActive": true,
      "theme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "darkTheme": {
        "primaryColor": "範例字串",
        "navbarTextColor": "範例字串",
        "conversationBackgroundColor": "範例字串",
        "chatbotMessageTextColor": "範例字串",
        "userMessageTextColor": "範例字串",
        "chatbotMessageBackgroundColor": "範例字串",
        "userMessageBackgroundColor": "範例字串",
        "chatbotMessageBackgroundShadowEnabled": true,
        "userMessageBackgroundShadowEnabled": true,
        "chatbotMessageGradientEnabled": true,
        "userMessageGradientEnabled": true
      },
      "enableFileUpload": true,
      "enableDisplayCitations": true,
      "toolDisplayMode": "full",
      "enableDisplayThinking": true,
      "enableUserThinkingControl": true,
      "enableDisplayQueryMetadata": true,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "avatar": "https://example.com/file.jpg",
            "logo": "https://example.com/file.jpg",
            "description": "範例字串",
            "cover": "https://example.com/file.jpg",
            "backUrl": "範例字串",
            "isActive": true,
            "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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 取得語音助理 Token <a href="#token" id="token"></a>

POST `/api/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                              | 否  |                                                       |
| enableShareConversation                         | boolean                              | 否  |                                                       |
| enableLocation                                  | boolean                              | 否  |                                                       |
| enableShowPoweredBy                             | boolean                              | 否  |                                                       |
| poweredByLogo                                   | string (uri)                         | 否  |                                                       |
| enableAnonymous                                 | boolean                              | 否  |                                                       |
| enableDisplayPreviousConversation               | boolean                              | 否  |                                                       |
| enableDisplayConversationHistory                | boolean                              | 否  |                                                       |
| enableConversationTimer                         | boolean                              | 否  |                                                       |
| conversationTimerDuration                       | integer                              | 否  | 計時器逾時時長，範圍 3-60 分鐘                                    |
| enableAutoNewConversationOnTimeout              | boolean                              | 否  |                                                       |
| enableThemeModeToggle                           | boolean                              | 否  |                                                       |
| enableDisplayFontSizeSwitch                     | boolean                              | 否  |                                                       |
| defaultThemeMode                                | object                               | 否  |                                                       |
| enableDownloadCitations                         | boolean                              | 否  |                                                       |
| customDomain                                    | object (含 3 個屬性: id, domain, status) | 否  |                                                       |
| customDomain.domain                             | string                               | 是  |                                                       |
| enableDisplayChatbotAvatar                      | boolean                              | 否  |                                                       |
| enableDisplayChatbotName                        | boolean                              | 否  |                                                       |
| enableVoiceAgent                                | boolean                              | 否  | 是否允許 WebChat 使用語音代理功能                                 |
| buttonIcon                                      | string (uri)                         | 否  |                                                       |

**請求結構範例**

```typescript
{
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "domain": string
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
}
```

**請求範例值**

```json
{
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "範例字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "範例字串",
  "isActive": true,
  "theme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "darkTheme": {
    "primaryColor": "範例字串",
    "navbarTextColor": "範例字串",
    "conversationBackgroundColor": "範例字串",
    "chatbotMessageTextColor": "範例字串",
    "userMessageTextColor": "範例字串",
    "chatbotMessageBackgroundColor": "範例字串",
    "userMessageBackgroundColor": "範例字串",
    "chatbotMessageBackgroundShadowEnabled": true,
    "userMessageBackgroundShadowEnabled": true,
    "chatbotMessageGradientEnabled": true,
    "userMessageGradientEnabled": true
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "toolDisplayMode": "full",
  "enableDisplayThinking": true,
  "enableUserThinkingControl": true,
  "enableDisplayQueryMetadata": true,
  "enableShareConversation": true,
  "enableLocation": true,
  "enableShowPoweredBy": true,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": true,
  "enableDisplayPreviousConversation": true,
  "enableDisplayConversationHistory": true,
  "enableConversationTimer": true,
  "conversationTimerDuration": 123,
  "enableAutoNewConversationOnTimeout": true,
  "enableThemeModeToggle": true,
  "enableDisplayFontSizeSwitch": true,
  "defaultThemeMode": {},
  "enableDownloadCitations": true,
  "customDomain": {
    "domain": "範例字串"
  },
  "enableDisplayChatbotAvatar": true,
  "enableDisplayChatbotName": true,
  "enableVoiceAgent": true,
  "buttonIcon": "https://example.com/file.jpg"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "avatar": "https://example.com/file.jpg",
    "logo": "https://example.com/file.jpg",
    "description": "範例字串",
    "cover": "https://example.com/file.jpg",
    "backUrl": "範例字串",
    "isActive": true,
    "theme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "darkTheme": {
      "primaryColor": "範例字串",
      "navbarTextColor": "範例字串",
      "conversationBackgroundColor": "範例字串",
      "chatbotMessageTextColor": "範例字串",
      "userMessageTextColor": "範例字串",
      "chatbotMessageBackgroundColor": "範例字串",
      "userMessageBackgroundColor": "範例字串",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true,
      "chatbotMessageGradientEnabled": true,
      "userMessageGradientEnabled": true
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "toolDisplayMode": "full",
    "enableDisplayThinking": true,
    "enableUserThinkingControl": true,
    "enableDisplayQueryMetadata": true,
    "enableShareConversation": true,
    "enableLocation": true,
    "enableShowPoweredBy": true,
    "poweredByLogo": "https://example.com/file.jpg",
    "enableAnonymous": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": true,
    "conversationTimerDuration": 123,
    "enableAutoNewConversationOnTimeout": true,
    "enableThemeModeToggle": true,
    "enableDisplayFontSizeSwitch": true,
    "defaultThemeMode": {},
    "enableDownloadCitations": true,
    "customDomain": {
      "domain": "範例字串"
    },
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableVoiceAgent": true,
    "buttonIcon": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/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,
      "enableShareConversation": true,
      "enableLocation": true,
      "enableShowPoweredBy": true,
      "poweredByLogo": "https://example.com/file.jpg",
      "enableAnonymous": true,
      "enableDisplayPreviousConversation": true,
      "enableDisplayConversationHistory": true,
      "enableConversationTimer": true,
      "conversationTimerDuration": 123,
      "enableAutoNewConversationOnTimeout": true,
      "enableThemeModeToggle": true,
      "enableDisplayFontSizeSwitch": true,
      "defaultThemeMode": {},
      "enableDownloadCitations": true,
      "customDomain": {
        "domain": "範例字串"
      },
      "enableDisplayChatbotAvatar": true,
      "enableDisplayChatbotName": true,
      "enableVoiceAgent": true,
      "buttonIcon": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/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,
            "enableShareConversation": true,
            "enableLocation": true,
            "enableShowPoweredBy": true,
            "poweredByLogo": "https://example.com/file.jpg",
            "enableAnonymous": true,
            "enableDisplayPreviousConversation": true,
            "enableDisplayConversationHistory": true,
            "enableConversationTimer": true,
            "conversationTimerDuration": 123,
            "enableAutoNewConversationOnTimeout": true,
            "enableThemeModeToggle": true,
            "enableDisplayFontSizeSwitch": true,
            "defaultThemeMode": {},
            "enableDownloadCitations": true,
            "customDomain": {
                "domain": "範例字串"
            },
            "enableDisplayChatbotAvatar": true,
            "enableDisplayChatbotName": true,
            "enableVoiceAgent": true,
            "buttonIcon": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // 非必填
  "logo"?: string (uri) // 非必填
  "description"?: string // 非必填
  "cover"?: string (uri) // 非必填
  "backUrl"?: string // 非必填
  "isActive"?: boolean // 非必填
  "enableSpeech": boolean
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // 非必填
    "navbarTextColor"?: string // 非必填
    "conversationBackgroundColor"?: string // 非必填
    "chatbotMessageTextColor"?: string // 非必填
    "userMessageTextColor"?: string // 非必填
    "chatbotMessageBackgroundColor"?: string // 非必填
    "userMessageBackgroundColor"?: string // 非必填
    "chatbotMessageBackgroundShadowEnabled"?: boolean // 非必填
    "userMessageBackgroundShadowEnabled"?: boolean // 非必填
    "chatbotMessageGradientEnabled"?: boolean // 非必填
    "userMessageGradientEnabled"?: boolean // 非必填
  }
  }
  "enableFileUpload"?: boolean // 非必填
  "enableDisplayCitations"?: boolean // 非必填
  "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (非必填)
  "enableDisplayThinking"?: boolean // 非必填
  "enableUserThinkingControl"?: boolean // 非必填
  "enableDisplayQueryMetadata"?: boolean // 非必填
  "enableShareConversation"?: boolean // 非必填
  "enableLocation"?: boolean // 非必填
  "enableShowPoweredBy"?: boolean // 非必填
  "poweredByLogo"?: string (uri) // 非必填
  "enableAnonymous"?: boolean // 非必填
  "enableDisplayPreviousConversation"?: boolean // 非必填
  "enableDisplayConversationHistory"?: boolean // 非必填
  "enableConversationTimer"?: boolean // 非必填
  "conversationTimerDuration"?: integer // 計時器逾時時長，範圍 3-60 分鐘 (非必填)
  "enableAutoNewConversationOnTimeout"?: boolean // 非必填
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // 非必填
  "enableDisplayFontSizeSwitch"?: boolean // 非必填
  "defaultThemeMode"?:  // 非必填
  {
  }
  "enableDownloadCitations"?: boolean // 非必填
  "customDomain"?:  // 非必填
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // 非必填
  "enableDisplayChatbotName"?: boolean // 非必填
  "enableVoiceAgent"?: boolean // 是否允許 WebChat 使用語音代理功能 (非必填)
  "buttonIcon"?: string (uri) // 非必填
  "inbox": object
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "logo": "https://example.com/file.jpg",
  "description": "回應字串",
  "cover": "https://example.com/file.jpg",
  "backUrl": "回應字串",
  "isActive": false,
  "enableSpeech": false,
  "displayConversationStarters": [
    "回應字串"
  ],
  "theme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "darkTheme": {
    "primaryColor": "回應字串",
    "navbarTextColor": "回應字串",
    "conversationBackgroundColor": "回應字串",
    "chatbotMessageTextColor": "回應字串",
    "userMessageTextColor": "回應字串",
    "chatbotMessageBackgroundColor": "回應字串",
    "userMessageBackgroundColor": "回應字串",
    "chatbotMessageBackgroundShadowEnabled": false,
    "userMessageBackgroundShadowEnabled": false,
    "chatbotMessageGradientEnabled": false,
    "userMessageGradientEnabled": false
  },
  "enableFileUpload": false,
  "enableDisplayCitations": false,
  "toolDisplayMode": "full",
  "enableDisplayThinking": false,
  "enableUserThinkingControl": false,
  "enableDisplayQueryMetadata": false,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": false,
  "poweredByLogo": "https://example.com/file.jpg",
  "enableAnonymous": false,
  "enableDisplayPreviousConversation": false,
  "enableDisplayConversationHistory": false,
  "enableConversationTimer": false,
  "conversationTimerDuration": 456,
  "enableAutoNewConversationOnTimeout": false,
  "accessType": {},
  "enableThemeModeToggle": false,
  "enableDisplayFontSizeSwitch": false,
  "defaultThemeMode": {},
  "enableDownloadCitations": false,
  "customDomain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "回應字串",
    "status": {}
  },
  "enableDisplayChatbotAvatar": false,
  "enableDisplayChatbotName": false,
  "enableVoiceAgent": false,
  "buttonIcon": "https://example.com/file.jpg",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 上傳批次 QA 檔案 <a href="#qa" id="qa"></a>

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

#### 參數

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

#### 請求內容

**請求參數**

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

**請求結構範例**

```typescript
{
  "file": string (uri)
}
```

**請求範例值**

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "file": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# 請求內容 (payload)
data = {
      "file": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "file": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

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

**回應範例值**

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

***

### 上傳批次 QA 檔案 <a href="#qa" id="qa"></a>

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

#### 參數

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

#### 請求內容

**請求參數**

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

**請求結構範例**

```typescript
{
  "file": string (uri)
}
```

**請求範例值**

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "https://example.com/file.jpg"
  }'

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

// 請求內容 (payload)
const data = {
    "file": "https://example.com/file.jpg"
  };

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# 請求內容 (payload)
data = {
      "file": "https://example.com/file.jpg"
    }

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "file": "https://example.com/file.jpg"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

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

**回應範例值**

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

***

### 匯出批次 QA 為 Excel <a href="#qa-excel" id="qa-excel"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明         |
| --- | ---------- |
| 200 | Excel 檔案下載 |

***

### 匯出批次 QA 為 Excel <a href="#qa-excel" id="qa-excel"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明         |
| --- | ---------- |
| 200 | Excel 檔案下載 |

***

### 取得 LLM 使用統計 <a href="#llm" id="llm"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

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

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

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

**回應範例值**

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

**狀態碼: 400**

**回應結構範例**

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

**回應範例值**

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

***

### 取得 LLM 使用統計 <a href="#llm" id="llm"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

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

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

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

**回應範例值**

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

**狀態碼: 400**

**回應結構範例**

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

**回應範例值**

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

***

### 取得 AI 助理統計數據 <a href="#ai" id="ai"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

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

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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


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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

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

**回應範例值**

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

***

### 取得 AI 助理統計數據 <a href="#ai" id="ai"></a>

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

#### 參數

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

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

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

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

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

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

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


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

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

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

**回應範例值**

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

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.