> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/api-reference/ai-zhu-li.md).

# AI 助理

### 建立新 AI 助理 <a href="#chatbots-create" id="chatbots-create"></a>

POST `/api/v1/chatbots/`

#### 請求內容

**請求參數**

| 欄位                                  | 類型                   | 必填 | 說明                                                                                                                                                                                                             |
| ----------------------------------- | -------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                | string               | 是  | Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.                                                                                                        |
| largeLanguageModel                  | string (uuid)        | 是  | 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略                                                                                                                                           |
| condenseQuestionLlm                 | string (uuid)        | 否  | 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定）                                                                                                                                  |
| embeddingModel                      | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                                                                                                                                             |
| rerankerModel                       | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                                                                                                                                                |
| instructions                        | string               | 否  | Role instructions describing the chatbot's role and behavior.                                                                                                                                                  |
| knowledgeBases                      | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                                                                                                                                   |
| databases                           | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                                                                                                                                           |
| organization                        | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                                                                                                                                           |
| replyMode                           | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: Normal ; `template`: Template ; `hybrid`: Hybrid ; `agent`: Agent;                                                                                                                    |
| template                            | string               | 否  | Template used by Template and Hybrid modes.                                                                                                                                                                    |
| unanswerableTemplate                | string               | 否  | Template used by Template and Hybrid modes when the question cannot be answered.                                                                                                                               |
| totalWordsCount                     | integer (int64)      | 否  | Accumulated total word count used.                                                                                                                                                                             |
| outputMode                          | object               | 否  | 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字） `text`: Text ; `json_schema`: JSON Schema;                                                                                                       |
| rawOutputFormat                     | object               | 否  | 自定義輸出格式的JSON結構定義                                                                                                                                                                                               |
| groups                              | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                                                                                                                                    |
| tools                               | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                                                                                                                                    |
| skills                              | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                                                                                                                                     |
| connectors                          | array\[IdName]       | 否  | Connectors associated with this chatbot, gating per-contact OAuth authorization                                                                                                                                |
| agentMode                           | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: Normal ; `canvas`: Canvas ; `team`: Team;                                                                                                                                         |
| numberOfRetrievedChunks             | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                                                        |
| defaultLabelRelations               | object               | 否  | 助理層級的預設知識庫標籤過濾條件，格式同 query\_metadata.label\_relations；null 表示不過濾。僅在呼叫端未帶 query\_metadata 時作為最低優先序兜底套用。                                                                                                         |
| useFullRetrievalRange               | boolean              | 否  | 啟用後忽略 LLM 的 top\_k 截斷，回傳完整 reranker 結果                                                                                                                                                                         |
| searchKnowledgeBaseFirst            | boolean              | 否  | Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can\_use\_search\_knowledge\_base\_first）                                                                                           |
| enableEvaluation                    | boolean              | 否  |                                                                                                                                                                                                                |
| enableInlineCitations               | boolean              | 否  | Enables inline citations, inserting citation markers such as \[1]\[2] into responses.                                                                                                                          |
| enableCodeInterpreter               | boolean              | 否  | When enabled, provides the Code Interpreter tool to run code in an isolated container.                                                                                                                         |
| enableBrowserTool                   | boolean              | 否  | Enable browser automation tool for web tasks                                                                                                                                                                   |
| browserToolMaxSteps                 | integer              | 否  | Most browser actions one reply of this assistant may take (1-100); null follows default\_browser\_tool\_max\_steps. Leaving it out of an update keeps the stored value.                                        |
| enableCloudDesktop                  | boolean              | 否  | Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization.                                       |
| cloudDesktopAllowedDomains          | array\[string]       | 否  | Domains the cloud desktop may reach, one per item; empty means no restriction (S19)                                                                                                                            |
| enableImageSearch                   | boolean              | 否  | Provide the image\_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely.                                                                        |
| enableClaudeStreamRetry             | boolean              | 否  | When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial outpu...    |
| enableStreamStallRetry              | boolean              | 否  | When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow ...    |
| customMaxLlmOutputTokens            | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                                                                                                                                   |
| voiceConfig                         | object               | 否  |                                                                                                                                                                                                                |
| voiceConfig.enabled                 | boolean              | 否  | Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle.                                 |
| voiceConfig.voiceAgentType          | string (uuid)        | 否  | Voice agent mode type.                                                                                                                                                                                         |
| voiceConfig.sttProvider             | string (uuid)        | 否  | Speech-to-Text service provider.                                                                                                                                                                               |
| voiceConfig.sttConfig               | object               | 否  | STT configuration parameters (JSON).                                                                                                                                                                           |
| voiceConfig.ttsProvider             | string (uuid)        | 否  | Text-to-Speech service provider.                                                                                                                                                                               |
| voiceConfig.ttsConfig               | object               | 否  | TTS configuration parameters (JSON).                                                                                                                                                                           |
| voiceConfig.realtimeProvider        | string (uuid)        | 否  | Realtime end-to-end voice model provider.                                                                                                                                                                      |
| voiceConfig.realtimeConfig          | object               | 否  | Realtime configuration parameters (JSON).                                                                                                                                                                      |
| voiceConfig.realtimeInstructions    | string               | 否  | Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty                                                                                                                  |
| voiceConfig.turnHandling            | object               | 否  | Turn-taking and interruption settings for the voice agent.                                                                                                                                                     |
| voiceConfig.enableVoiceReply        | boolean              | 否  | When disabled, the voice agent replies in text only and does not speak                                                                                                                                         |
| thinkingConfig                      | object               | 否  | 思考等級：null（模型預設）或 {"reasoning\_effort": "off                                                                                                                                                                    |
| enableToolSearching                 | boolean              | 否  | 舊欄位，請改用 tool\_loading\_mode。寫入 true 等同 tool\_loading\_mode=search、false 等同 all；兩者都帶時以 tool\_loading\_mode 為準。讀取時回傳「工具載入方式不是全部載入」。                                                                              |
| toolLoadingMode                     | object               | 否  | 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。 `auto`: Auto ; `all`: Load all ; `search`: Dynamic search;                                              |
| maxAgentIterations                  | integer              | 否  | Maximum number of iterations for AgentWorkflow (1-100, default: 20)                                                                                                                                            |
| agentTimeoutSeconds                 | integer              | 否  | Timeout in seconds for AgentWorkflow execution (30-1200, default: 600)                                                                                                                                         |
| agentTimeoutMessage                 | string               | 否  | Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default.                                                                                          |
| systemErrorMessage                  | string               | 否  | Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default.                             |
| requireTextWithFlexCards            | boolean              | 否  | When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a se...    |
| enableSizeBasedToolResultTruncation | boolean              | 否  | When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversati...    |
| toolResultMaxChars                  | integer              | 否  | Character threshold for size-based tool result truncation (500-50000). Only effective when enable\_size\_based\_tool\_result\_truncation is True.                                                              |
| enableMemberMemoryWrite             | boolean              | 否  | When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it ...    |
| enableMemberMemoryInjection         | boolean              | 否  | When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on.                   |
| enableVectorMemory                  | boolean              | 否  | When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat hist...    |
| longTermMemoryTopK                  | integer              | 否  | 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity\_top\_k），預設為 10，範圍 1–50                                                                                                                                                      |
| enableCrossConversationSearch       | boolean              | 否  | When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation.             |
| crossConversationLookbackDays       | integer              | 否  | How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable\_cross\_conversation\_search... |
| useGatewayFallback                  | boolean              | 否  | When enabled, use the fallback group instead of the single LLM                                                                                                                                                 |
| gatewayFallbackGroup                | string (uuid)        | 否  |                                                                                                                                                                                                                |
| enableSearchMessagesTool            | boolean              | 否  | Allow the AI to search past messages in the current conversation.                                                                                                                                              |
| enableGetMessageContextTool         | boolean              | 否  | Allow the AI to retrieve messages surrounding a specific message for context.                                                                                                                                  |
| enableReadAttachmentFullTextTool    | boolean              | 否  | Allow the AI to read the full text of plain-text attachments. AGENT mode only.                                                                                                                                 |
| enableParseAttachmentContentTool    | boolean              | 否  | Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only.                                                                                                                              |
| enableListAvailableParsersTool      | boolean              | 否  | Allow the AI to list available parsers and their capabilities. AGENT mode only.                                                                                                                                |
| enableGetDownloadLinkTool           | boolean              | 否  | Allow the AI to generate shareable download links for produced content. AGENT mode only.                                                                                                                       |
| webChatIsActive                     | boolean              | 否  | Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignor...    |
| apiIsActive                         | boolean              | 否  | Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on u...    |
| fileWorkspaceMode                   | object               | 否  | File workspace mode in Work internal conversations: none, bound or user\_mount. `none`: None ; `bound`: Bound workspace ; `user_mount`: User mount;                                                            |
| fileWorkspaceFolder                 | string (uuid)        | 否  | The bound workspace (folder id); required when the mode is bound, cleared otherwise.                                                                                                                           |

**請求結構範例**

```typescript
{
  "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": true,
  "searchKnowledgeBaseFirst": true,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "enableBrowserTool": true,
  "browserToolMaxSteps": 123,
  "enableCloudDesktop": true,
  "cloudDesktopAllowedDomains": [
    "範例字串"
  ],
  "enableImageSearch": true,
  "enableClaudeStreamRetry": true,
  "enableStreamStallRetry": true,
  "customMaxLlmOutputTokens": 123,
  "voiceConfig": {
    "enabled": true,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "範例字串",
    "turnHandling": null,
    "enableVoiceReply": true
  },
  "thinkingConfig": null,
  "enableToolSearching": true,
  "toolLoadingMode": {},
  "maxAgentIterations": 123,
  "agentTimeoutSeconds": 123,
  "agentTimeoutMessage": "範例字串",
  "systemErrorMessage": "範例字串",
  "requireTextWithFlexCards": true,
  "enableSizeBasedToolResultTruncation": true,
  "toolResultMaxChars": 123,
  "enableMemberMemoryWrite": true,
  "enableMemberMemoryInjection": true,
  "enableVectorMemory": true,
  "longTermMemoryTopK": 123,
  "enableCrossConversationSearch": true,
  "crossConversationLookbackDays": 123,
  "useGatewayFallback": true,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": true,
  "enableGetMessageContextTool": true,
  "enableReadAttachmentFullTextTool": true,
  "enableParseAttachmentContentTool": true,
  "enableListAvailableParsersTool": true,
  "enableGetDownloadLinkTool": true,
  "webChatIsActive": true,
  "apiIsActive": true,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chatbots/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "connectors": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": null,
    "useFullRetrievalRange": true,
    "searchKnowledgeBaseFirst": true,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "enableBrowserTool": true,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": true,
    "cloudDesktopAllowedDomains": [
      "範例字串"
    ],
    "enableImageSearch": true,
    "enableClaudeStreamRetry": true,
    "enableStreamStallRetry": true,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
      "enabled": true,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "realtimeInstructions": "範例字串",
      "turnHandling": null,
      "enableVoiceReply": true
    },
    "thinkingConfig": null,
    "enableToolSearching": true,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": true,
    "enableSizeBasedToolResultTruncation": true,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": true,
    "enableMemberMemoryInjection": true,
    "enableVectorMemory": true,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": true,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": true,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": true,
    "enableGetMessageContextTool": true,
    "enableReadAttachmentFullTextTool": true,
    "enableParseAttachmentContentTool": true,
    "enableListAvailableParsersTool": true,
    "enableGetDownloadLinkTool": true,
    "webChatIsActive": true,
    "apiIsActive": true,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "connectors": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": null,
    "useFullRetrievalRange": true,
    "searchKnowledgeBaseFirst": true,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "enableBrowserTool": true,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": true,
    "cloudDesktopAllowedDomains": [
      "範例字串"
    ],
    "enableImageSearch": true,
    "enableClaudeStreamRetry": true,
    "enableStreamStallRetry": true,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
      "enabled": true,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "realtimeInstructions": "範例字串",
      "turnHandling": null,
      "enableVoiceReply": true
    },
    "thinkingConfig": null,
    "enableToolSearching": true,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": true,
    "enableSizeBasedToolResultTruncation": true,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": true,
    "enableMemberMemoryInjection": true,
    "enableVectorMemory": true,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": true,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": true,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": true,
    "enableGetMessageContextTool": true,
    "enableReadAttachmentFullTextTool": true,
    "enableParseAttachmentContentTool": true,
    "enableListAvailableParsersTool": true,
    "enableGetDownloadLinkTool": true,
    "webChatIsActive": true,
    "apiIsActive": true,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.post("https://api.maiagent.ai/api/v1/chatbots/", 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/chatbots/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "databases": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": None,
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "tools": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "skills": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "connectors": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": None,
    "useFullRetrievalRange": True,
    "searchKnowledgeBaseFirst": True,
    "enableEvaluation": True,
    "enableInlineCitations": True,
    "enableCodeInterpreter": True,
    "enableBrowserTool": True,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": True,
    "cloudDesktopAllowedDomains": [
        "範例字串"
    ],
    "enableImageSearch": True,
    "enableClaudeStreamRetry": True,
    "enableStreamStallRetry": True,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
        "enabled": True,
        "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
        "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
        "sttConfig": None,
        "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
        "ttsConfig": None,
        "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
        "realtimeConfig": None,
        "realtimeInstructions": "範例字串",
        "turnHandling": None,
        "enableVoiceReply": True
    },
    "thinkingConfig": None,
    "enableToolSearching": True,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": True,
    "enableSizeBasedToolResultTruncation": True,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": True,
    "enableMemberMemoryInjection": True,
    "enableVectorMemory": True,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": True,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": True,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": True,
    "enableGetMessageContextTool": True,
    "enableReadAttachmentFullTextTool": True,
    "enableParseAttachmentContentTool": True,
    "enableListAvailableParsersTool": True,
    "enableGetDownloadLinkTool": True,
    "webChatIsActive": True,
    "apiIsActive": True,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
}

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/chatbots/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'largeLanguageModel' => '550e8400-e29b-41d4-a716-446655440000',
            'condenseQuestionLlm' => '550e8400-e29b-41d4-a716-446655440000',
            'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000',
            'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000',
            'instructions' => '範例字串',
            'knowledgeBases' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'databases' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'organization' => '550e8400-e29b-41d4-a716-446655440000',
            'replyMode' => new \stdClass(),
            'template' => '範例字串',
            'unanswerableTemplate' => '範例字串',
            'totalWordsCount' => 123,
            'outputMode' => new \stdClass(),
            'rawOutputFormat' => null,
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'tools' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'skills' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'connectors' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'agentMode' => new \stdClass(),
            'numberOfRetrievedChunks' => 123,
            'defaultLabelRelations' => null,
            'useFullRetrievalRange' => true,
            'searchKnowledgeBaseFirst' => true,
            'enableEvaluation' => true,
            'enableInlineCitations' => true,
            'enableCodeInterpreter' => true,
            'enableBrowserTool' => true,
            'browserToolMaxSteps' => 123,
            'enableCloudDesktop' => true,
            'cloudDesktopAllowedDomains' => [
                '範例字串'
            ],
            'enableImageSearch' => true,
            'enableClaudeStreamRetry' => true,
            'enableStreamStallRetry' => true,
            'customMaxLlmOutputTokens' => 123,
            'voiceConfig' => [
                'enabled' => true,
                'voiceAgentType' => '550e8400-e29b-41d4-a716-446655440000',
                'sttProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'sttConfig' => null,
                'ttsProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'ttsConfig' => null,
                'realtimeProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'realtimeConfig' => null,
                'realtimeInstructions' => '範例字串',
                'turnHandling' => null,
                'enableVoiceReply' => true
            ],
            'thinkingConfig' => null,
            'enableToolSearching' => true,
            'toolLoadingMode' => new \stdClass(),
            'maxAgentIterations' => 123,
            'agentTimeoutSeconds' => 123,
            'agentTimeoutMessage' => '範例字串',
            'systemErrorMessage' => '範例字串',
            'requireTextWithFlexCards' => true,
            'enableSizeBasedToolResultTruncation' => true,
            'toolResultMaxChars' => 123,
            'enableMemberMemoryWrite' => true,
            'enableMemberMemoryInjection' => true,
            'enableVectorMemory' => true,
            'longTermMemoryTopK' => 123,
            'enableCrossConversationSearch' => true,
            'crossConversationLookbackDays' => 123,
            'useGatewayFallback' => true,
            'gatewayFallbackGroup' => '550e8400-e29b-41d4-a716-446655440000',
            'enableSearchMessagesTool' => true,
            'enableGetMessageContextTool' => true,
            'enableReadAttachmentFullTextTool' => true,
            'enableParseAttachmentContentTool' => true,
            'enableListAvailableParsersTool' => true,
            'enableGetDownloadLinkTool' => true,
            'webChatIsActive' => true,
            'apiIsActive' => true,
            'fileWorkspaceMode' => new \stdClass(),
            'fileWorkspaceFolder' => '550e8400-e29b-41d4-a716-446655440000'
        ]
    ]);
    
    $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 // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
  "llm":  // 綁定模型的 id、name 與退役資訊，直接讀取 FK，即使該模型已被組織停用仍會回傳
  {
    "id": string (uuid)
    "name": string
    "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
    "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
    {
      "id": string (uuid)
      "name": string
    }
  }
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "defaultCondenseQuestionLlm":  // 跟隨系統設定時實際使用的問題改寫模型（id 與 name）；null 表示由助理主模型改寫（唯讀）
  {
    "id": string (uuid)
    "name": string
  }
  "organizationEnforcedSettings": [ // 組織 AI助理預設值對這個助理強制的項目代碼（與 AI助理預設值 API 的 key 相同）；這些欄位讀回的就是強制值，更新時帶不同的值會被拒絕（唯讀；官方內建 Agent 與 MaiGPT 為空）
    string
  ]
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "source": string
      "isGlobal": boolean
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "defaultBrowserToolMaxSteps": integer // Read-only. The site-wide browser step limit an assistant without its own limit uses.
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "cloudDesktopAvailable": boolean // Whether the site-wide setting lets this assistant offer the cloud desktop switch
  "cloudDesktopModelSupported": boolean // Whether the assistant's current model can run the cloud desktop
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified
  "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "team": 
  {
    "id": string (uuid)
    "name": string
  }
  "isBuiltinTeamEntry": boolean // Read-only. Whether this assistant is the entry of a team on the built-in entry node.
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
  "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null}
  "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace.
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "llm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "retiresAt": "回應字串",
    "replacement": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  },
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "defaultCondenseQuestionLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organizationEnforcedSettings": [
    "回應字串"
  ],
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "source": "回應字串",
      "isGlobal": false
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": false,
  "searchKnowledgeBaseFirst": false,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "enableBrowserTool": false,
  "browserToolMaxSteps": 456,
  "defaultBrowserToolMaxSteps": 456,
  "enableCloudDesktop": false,
  "cloudDesktopAllowedDomains": [
    "回應字串"
  ],
  "cloudDesktopAvailable": false,
  "cloudDesktopModelSupported": false,
  "enableImageSearch": false,
  "enableClaudeStreamRetry": false,
  "enableStreamStallRetry": false,
  "customMaxLlmOutputTokens": 456,
  "voiceConfig": {
    "enabled": false,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "回應字串",
    "turnHandling": null,
    "enableVoiceReply": false
  },
  "thinkingConfig": null,
  "enableToolSearching": false,
  "toolLoadingMode": {},
  "maxAgentIterations": 456,
  "agentTimeoutSeconds": 456,
  "agentTimeoutMessage": "回應字串",
  "systemErrorMessage": "回應字串",
  "requireTextWithFlexCards": false,
  "isMultimodalLlm": false,
  "enableSizeBasedToolResultTruncation": false,
  "toolResultMaxChars": 456,
  "enableMemberMemoryWrite": false,
  "enableMemberMemoryInjection": false,
  "enableVectorMemory": false,
  "longTermMemoryTopK": 456,
  "enableCrossConversationSearch": false,
  "crossConversationLookbackDays": 456,
  "useGatewayFallback": false,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": false,
  "enableGetMessageContextTool": false,
  "enableReadAttachmentFullTextTool": false,
  "enableParseAttachmentContentTool": false,
  "enableListAvailableParsersTool": false,
  "enableGetDownloadLinkTool": false,
  "isLocked": false,
  "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
  "canUpdate": false,
  "canDelete": false,
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isBuiltinTeamEntry": false,
  "webChatIsActive": false,
  "apiIsActive": false,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
  "fileWorkspaceStatus": {
    "name": "example.pdf",
    "content": "base64encoded_content",
    "contentType": "application/pdf"
  },
  "fileWorkspaceAvailable": false
}
```

***

### 列出 Embedding Model <a href="#embedding-models-list" id="embedding-models-list"></a>

GET `/api/v1/embedding-models/`

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/embedding-models/" \
  -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/embedding-models/", 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/embedding-models/"
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/embedding-models/", [
        '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
    "isDefault"?: boolean // 非必填
    "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (非必填)
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]
```

**回應範例值**

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

***

### 列出 Reranker Model <a href="#reranker-models-list" id="reranker-models-list"></a>

GET `/api/v1/reranker-models/`

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/reranker-models/" \
  -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/reranker-models/", 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/reranker-models/"
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/reranker-models/", [
        '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
    "isDefault"?: boolean // 非必填
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]
```

**回應範例值**

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

***

### 列出大型語言模型 <a href="#large-language-models-list" id="large-language-models-list"></a>

GET `/api/v1/large-language-models/`

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/large-language-models/" \
  -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/large-language-models/", 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/large-language-models/"
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/large-language-models/", [
        '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
    "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
    "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
    {
      "id": string (uuid)
      "name": string
    }
    "contextWindow"?: integer // Used only by OpenAILike or Ollama models; other models ignore this value. (非必填)
    "isDefault"?: boolean // 非必填
    "provider": string
    "servedBy": string // Who runs inference, which is where prompts are sent (for example OpenRouter, AWS Bedrock); models on a customer credential show Customer credential.
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
    "isMultiModalSupport"?: boolean // 非必填
    "isFunctionalCallingAvailable": boolean // Deprecated: same value as isToolCallingAvailable; use isToolCallingAvailable.
    "isToolCallingAvailable"?: boolean // 非必填
    "isTemplateAvailable": boolean
    "isOutputFormatAvailable": boolean
    "isThinkingAvailable"?: boolean // When checked, this model shows the thinking depth setting and requests carry thinking parameters (thinking_budget for Gemini, reasoning_effort for OpenAI-compatible hosts). Unchecking stops sending them; saved thinking settings are kept but have no effect. Check only for models known to support thinking parameters, otherwise the provider returns 4xx. (非必填)
    "defaultThinkingLevel"?: // 可能有不同的類型 (非必填)
    string (enum: off, minimal, low, medium, high, xhigh, max) // The thinking level sent when neither the conversation nor the assistant sets one. Empty sends no thinking parameter, so the provider default applies. A level the model does not accept is lowered to the nearest one it does. Takes effect only when Supports Thinking is checked.

* `off` - off
* `minimal` - minimal
* `low` - low
* `medium` - medium
* `high` - high
* `xhigh` - xhigh
* `max` - max (非必填)
    "thinkingConfigSchema": { // 此模型的思考設定表單；null 表示此模型沒有思考設定
    {
      "type"?: string // 表單類型，固定為 reasoning_effort (非必填)
      "fields"?: object // reasoning_effort 欄位：options 列出此模型接受的思考等級（由弱到強），default 固定為 null (非必填)
      "canDisable"?: boolean // 此模型能否關閉思考；true 時 options 含 off (非必填)
      "unsetBehavior"?: string (enum: off, model_default) // 對話與助理都沒設思考等級時的實際行為：off＝不思考（最快）；model_default＝模型自行思考，或平台預設等級會開啟思考 (非必填)
      "unsetLevel"?: string // 沒設等級時平台實際送出的等級；null 表示不送思考參數，交給模型自身預設 (非必填)
    }
    }
    "replyMode": [
      string
    ]
    "outputMode": [
      string
    ]
    "agentMode": [
      string
    ]
    "maxTokens"?: integer // 非必填
    "minTokens": integer
    "isCustomModel": boolean // Whether the row is organization-owned (materialized from an AI Gateway custom model).
    "originCountry": string // ISO 3166-1 alpha-2 code of the country the model developer is based in (e.g. US, CN, FR); null when unknown. Follows the model, not who runs inference.
    "originRegion": // 可能有不同的類型
    string (enum: cn, us, other) // Origin group for labels and filters: cn / us / other; null when unknown (no label).

* `cn` - China
* `us` - United States
* `other` - Other countries
    "originRegionDisplay": string // Translated origin group name (e.g. 中國／美國／其他國家); null when unknown.
    "isCondenseQuestionAvailable": boolean // Whether an assistant can pick this model as its question-rewrite (condense question) model; false for image-generation models, which the chatbot condense_question_llm field rejects.
    "isCloudDesktopSupported": boolean // Whether an assistant on this model can offer the cloud desktop (S5 (d)); the settings page hint.
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "retiresAt": "回應字串",
    "replacement": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    },
    "contextWindow": 456,
    "isDefault": false,
    "provider": "回應字串",
    "servedBy": "回應字串",
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    },
    "isMultiModalSupport": false,
    "isFunctionalCallingAvailable": false,
    "isToolCallingAvailable": false,
    "isTemplateAvailable": false,
    "isOutputFormatAvailable": false,
    "isThinkingAvailable": false,
    "defaultThinkingLevel": "off",
    "thinkingConfigSchema": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    },
    "replyMode": [
      "回應字串"
    ],
    "outputMode": [
      "回應字串"
    ],
    "agentMode": [
      "回應字串"
    ],
    "maxTokens": 456,
    "minTokens": 456,
    "isCustomModel": false,
    "originCountry": "回應字串",
    "originRegion": "cn",
    "originRegionDisplay": "回應字串",
    "isCondenseQuestionAvailable": false,
    "isCloudDesktopSupported": false
  }
]
```

***

### 取得 AI 助理列表 <a href="#chatbots-list" id="chatbots-list"></a>

GET `/api/v1/chatbots/`

#### 參數

| 參數名稱                 | 必填 | 類型      | 說明                                                                      |
| -------------------- | -- | ------- | ----------------------------------------------------------------------- |
| `createdByMember`    | ❌  | string  | 建立者篩選：本組織成員 id（成員名冊回傳的 id，含已停用成員），只回該成員建立的 AI 助理                        |
| `largeLanguageModel` | ❌  | string  |                                                                         |
| `page`               | ❌  | integer | A page number within the paginated result set.                          |
| `pageSize`           | ❌  | integer | Number of results to return per page.                                   |
| `pagination`         | ❌  | string  | 是否分頁 (true/false)                                                       |
| `query`              | ❌  | string  |                                                                         |
| `replyMode`          | ❌  | string  |                                                                         |
| `source`             | ❌  | string  | \`self\_built\`: self\_built ; \`built\_in\`: built\_in ; \`all\`: all; |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all" \
  -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/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all", 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/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all"
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/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all", [
        '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
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
      "groups": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "largeLanguageModel": { // LLM 的基礎序列化器：識別欄位加上退役資訊，供前端在模型即將退役時提示。
      {
        "id": string (uuid)
        "name": string
        "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
        "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
        {
          "id": string (uuid)
          "name": string
        }
      }
      }
      "embeddingModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (非必填)
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "rerankerModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "knowledgeBases": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "tools": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "displayName": string
          "toolType": string
        }
      ]
      "skills": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "source": string
          "isGlobal": boolean
        }
      ]
      "agentMode"?:  // Agent mode: Canvas or Normal. Canvas mode generates answers on a canvas; Normal mode generates regular answers.

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
      {
      }
      "replyMode"?:  // Reply mode: Normal, Template, Hybrid, or Agent.

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
      {
      }
      "updatedAt": string (timestamp)
      "enableEvaluation"?: boolean // 非必填
      "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
      "enableToolSearching": boolean
      "toolLoadingMode": string
      "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
      "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
      "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
      "numberOfRetrievedChunks"?: integer // 非必填
      "useFullRetrievalRange"?: boolean // When enabled, the retrieval tool ignores the top_k set by the LLM and returns the full reranker result up to the maximum number of retrieved chunks. Useful for knowledge bases with long tables that need a wider retrieval range. (非必填)
      "searchKnowledgeBaseFirst"?: boolean // Agent reply mode only. When enabled, every reply first searches the knowledge base with the user's message as typed, and the model starts from those results instead of first deciding what to search; it can still search again or use other tools. Replies to knowledge base questions start sooner; a message that needs no knowledge base still pays for one search. Has no effect unless the platform offers this option to the organization (Config: "Offer Search Knowledge Base First"). (非必填)
      "isMultimodalLlm": boolean // Return whether the chatbot's LLM supports multimodal.
      "voiceConfig": 
      {
        "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
      }
      "createdBy": 
      {
        "id": string (uuid)
        "name": string
      }
      "isLocked"?: boolean // Locked instance: config follows the official version; only the dedicated KB can be modified (非必填)
      "sourceBuildInAgent"?: string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental (非必填)
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
      "team": 
      {
        "id": string (uuid)
        "name": string
      }
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "largeLanguageModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "retiresAt": "回應字串",
        "replacement": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      },
      "embeddingModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "isMultimodal": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "rerankerModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串",
          "displayName": "回應字串",
          "toolType": "回應字串"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串",
          "source": "回應字串",
          "isGlobal": false
        }
      ],
      "agentMode": {},
      "replyMode": {},
      "updatedAt": "回應字串",
      "enableEvaluation": false,
      "enableInlineCitations": false,
      "enableToolSearching": false,
      "toolLoadingMode": "回應字串",
      "enableCodeInterpreter": false,
      "enableBrowserTool": false,
      "enableImageSearch": false,
      "numberOfRetrievedChunks": 456,
      "useFullRetrievalRange": false,
      "searchKnowledgeBaseFirst": false,
      "isMultimodalLlm": false,
      "voiceConfig": {
        "enabled": false
      },
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "isLocked": false,
      "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
      "canUpdate": false,
      "canDelete": false,
      "team": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      }
    }
  ]
}
```

***

### 取得特定 AI 助理 <a href="#chatbots-retrieve" id="chatbots-retrieve"></a>

GET `/api/v1/chatbots/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/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/chatbots/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/chatbots/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/chatbots/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 // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
  "llm":  // 綁定模型的 id、name 與退役資訊，直接讀取 FK，即使該模型已被組織停用仍會回傳
  {
    "id": string (uuid)
    "name": string
    "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
    "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
    {
      "id": string (uuid)
      "name": string
    }
  }
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "defaultCondenseQuestionLlm":  // 跟隨系統設定時實際使用的問題改寫模型（id 與 name）；null 表示由助理主模型改寫（唯讀）
  {
    "id": string (uuid)
    "name": string
  }
  "organizationEnforcedSettings": [ // 組織 AI助理預設值對這個助理強制的項目代碼（與 AI助理預設值 API 的 key 相同）；這些欄位讀回的就是強制值，更新時帶不同的值會被拒絕（唯讀；官方內建 Agent 與 MaiGPT 為空）
    string
  ]
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "source": string
      "isGlobal": boolean
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "defaultBrowserToolMaxSteps": integer // Read-only. The site-wide browser step limit an assistant without its own limit uses.
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "cloudDesktopAvailable": boolean // Whether the site-wide setting lets this assistant offer the cloud desktop switch
  "cloudDesktopModelSupported": boolean // Whether the assistant's current model can run the cloud desktop
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified
  "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "team": 
  {
    "id": string (uuid)
    "name": string
  }
  "isBuiltinTeamEntry": boolean // Read-only. Whether this assistant is the entry of a team on the built-in entry node.
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
  "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null}
  "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace.
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "llm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "retiresAt": "回應字串",
    "replacement": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  },
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "defaultCondenseQuestionLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organizationEnforcedSettings": [
    "回應字串"
  ],
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "source": "回應字串",
      "isGlobal": false
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": false,
  "searchKnowledgeBaseFirst": false,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "enableBrowserTool": false,
  "browserToolMaxSteps": 456,
  "defaultBrowserToolMaxSteps": 456,
  "enableCloudDesktop": false,
  "cloudDesktopAllowedDomains": [
    "回應字串"
  ],
  "cloudDesktopAvailable": false,
  "cloudDesktopModelSupported": false,
  "enableImageSearch": false,
  "enableClaudeStreamRetry": false,
  "enableStreamStallRetry": false,
  "customMaxLlmOutputTokens": 456,
  "voiceConfig": {
    "enabled": false,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "回應字串",
    "turnHandling": null,
    "enableVoiceReply": false
  },
  "thinkingConfig": null,
  "enableToolSearching": false,
  "toolLoadingMode": {},
  "maxAgentIterations": 456,
  "agentTimeoutSeconds": 456,
  "agentTimeoutMessage": "回應字串",
  "systemErrorMessage": "回應字串",
  "requireTextWithFlexCards": false,
  "isMultimodalLlm": false,
  "enableSizeBasedToolResultTruncation": false,
  "toolResultMaxChars": 456,
  "enableMemberMemoryWrite": false,
  "enableMemberMemoryInjection": false,
  "enableVectorMemory": false,
  "longTermMemoryTopK": 456,
  "enableCrossConversationSearch": false,
  "crossConversationLookbackDays": 456,
  "useGatewayFallback": false,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": false,
  "enableGetMessageContextTool": false,
  "enableReadAttachmentFullTextTool": false,
  "enableParseAttachmentContentTool": false,
  "enableListAvailableParsersTool": false,
  "enableGetDownloadLinkTool": false,
  "isLocked": false,
  "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
  "canUpdate": false,
  "canDelete": false,
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isBuiltinTeamEntry": false,
  "webChatIsActive": false,
  "apiIsActive": false,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
  "fileWorkspaceStatus": {
    "name": "example.pdf",
    "content": "base64encoded_content",
    "contentType": "application/pdf"
  },
  "fileWorkspaceAvailable": false
}
```

***

### 更新 AI 助理 <a href="#chatbots-update" id="chatbots-update"></a>

PUT `/api/v1/chatbots/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                                  | 類型                   | 必填 | 說明                                                                                                                                                                                                             |
| ----------------------------------- | -------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                | string               | 是  | Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.                                                                                                        |
| largeLanguageModel                  | string (uuid)        | 是  | 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略                                                                                                                                           |
| condenseQuestionLlm                 | string (uuid)        | 否  | 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定）                                                                                                                                  |
| embeddingModel                      | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                                                                                                                                             |
| rerankerModel                       | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                                                                                                                                                |
| instructions                        | string               | 否  | Role instructions describing the chatbot's role and behavior.                                                                                                                                                  |
| knowledgeBases                      | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                                                                                                                                   |
| databases                           | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                                                                                                                                           |
| organization                        | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                                                                                                                                           |
| replyMode                           | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: Normal ; `template`: Template ; `hybrid`: Hybrid ; `agent`: Agent;                                                                                                                    |
| template                            | string               | 否  | Template used by Template and Hybrid modes.                                                                                                                                                                    |
| unanswerableTemplate                | string               | 否  | Template used by Template and Hybrid modes when the question cannot be answered.                                                                                                                               |
| totalWordsCount                     | integer (int64)      | 否  | Accumulated total word count used.                                                                                                                                                                             |
| outputMode                          | object               | 否  | 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字） `text`: Text ; `json_schema`: JSON Schema;                                                                                                       |
| rawOutputFormat                     | object               | 否  | 自定義輸出格式的JSON結構定義                                                                                                                                                                                               |
| groups                              | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                                                                                                                                    |
| tools                               | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                                                                                                                                    |
| skills                              | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                                                                                                                                     |
| connectors                          | array\[IdName]       | 否  | Connectors associated with this chatbot, gating per-contact OAuth authorization                                                                                                                                |
| agentMode                           | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: Normal ; `canvas`: Canvas ; `team`: Team;                                                                                                                                         |
| numberOfRetrievedChunks             | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                                                        |
| defaultLabelRelations               | object               | 否  | 助理層級的預設知識庫標籤過濾條件，格式同 query\_metadata.label\_relations；null 表示不過濾。僅在呼叫端未帶 query\_metadata 時作為最低優先序兜底套用。                                                                                                         |
| useFullRetrievalRange               | boolean              | 否  | 啟用後忽略 LLM 的 top\_k 截斷，回傳完整 reranker 結果                                                                                                                                                                         |
| searchKnowledgeBaseFirst            | boolean              | 否  | Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can\_use\_search\_knowledge\_base\_first）                                                                                           |
| enableEvaluation                    | boolean              | 否  |                                                                                                                                                                                                                |
| enableInlineCitations               | boolean              | 否  | Enables inline citations, inserting citation markers such as \[1]\[2] into responses.                                                                                                                          |
| enableCodeInterpreter               | boolean              | 否  | When enabled, provides the Code Interpreter tool to run code in an isolated container.                                                                                                                         |
| enableBrowserTool                   | boolean              | 否  | Enable browser automation tool for web tasks                                                                                                                                                                   |
| browserToolMaxSteps                 | integer              | 否  | Most browser actions one reply of this assistant may take (1-100); null follows default\_browser\_tool\_max\_steps. Leaving it out of an update keeps the stored value.                                        |
| enableCloudDesktop                  | boolean              | 否  | Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization.                                       |
| cloudDesktopAllowedDomains          | array\[string]       | 否  | Domains the cloud desktop may reach, one per item; empty means no restriction (S19)                                                                                                                            |
| enableImageSearch                   | boolean              | 否  | Provide the image\_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely.                                                                        |
| enableClaudeStreamRetry             | boolean              | 否  | When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial outpu...    |
| enableStreamStallRetry              | boolean              | 否  | When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow ...    |
| customMaxLlmOutputTokens            | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                                                                                                                                   |
| voiceConfig                         | object               | 否  |                                                                                                                                                                                                                |
| voiceConfig.enabled                 | boolean              | 否  | Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle.                                 |
| voiceConfig.voiceAgentType          | string (uuid)        | 否  | Voice agent mode type.                                                                                                                                                                                         |
| voiceConfig.sttProvider             | string (uuid)        | 否  | Speech-to-Text service provider.                                                                                                                                                                               |
| voiceConfig.sttConfig               | object               | 否  | STT configuration parameters (JSON).                                                                                                                                                                           |
| voiceConfig.ttsProvider             | string (uuid)        | 否  | Text-to-Speech service provider.                                                                                                                                                                               |
| voiceConfig.ttsConfig               | object               | 否  | TTS configuration parameters (JSON).                                                                                                                                                                           |
| voiceConfig.realtimeProvider        | string (uuid)        | 否  | Realtime end-to-end voice model provider.                                                                                                                                                                      |
| voiceConfig.realtimeConfig          | object               | 否  | Realtime configuration parameters (JSON).                                                                                                                                                                      |
| voiceConfig.realtimeInstructions    | string               | 否  | Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty                                                                                                                  |
| voiceConfig.turnHandling            | object               | 否  | Turn-taking and interruption settings for the voice agent.                                                                                                                                                     |
| voiceConfig.enableVoiceReply        | boolean              | 否  | When disabled, the voice agent replies in text only and does not speak                                                                                                                                         |
| thinkingConfig                      | object               | 否  | 思考等級：null（模型預設）或 {"reasoning\_effort": "off                                                                                                                                                                    |
| enableToolSearching                 | boolean              | 否  | 舊欄位，請改用 tool\_loading\_mode。寫入 true 等同 tool\_loading\_mode=search、false 等同 all；兩者都帶時以 tool\_loading\_mode 為準。讀取時回傳「工具載入方式不是全部載入」。                                                                              |
| toolLoadingMode                     | object               | 否  | 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。 `auto`: Auto ; `all`: Load all ; `search`: Dynamic search;                                              |
| maxAgentIterations                  | integer              | 否  | Maximum number of iterations for AgentWorkflow (1-100, default: 20)                                                                                                                                            |
| agentTimeoutSeconds                 | integer              | 否  | Timeout in seconds for AgentWorkflow execution (30-1200, default: 600)                                                                                                                                         |
| agentTimeoutMessage                 | string               | 否  | Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default.                                                                                          |
| systemErrorMessage                  | string               | 否  | Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default.                             |
| requireTextWithFlexCards            | boolean              | 否  | When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a se...    |
| enableSizeBasedToolResultTruncation | boolean              | 否  | When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversati...    |
| toolResultMaxChars                  | integer              | 否  | Character threshold for size-based tool result truncation (500-50000). Only effective when enable\_size\_based\_tool\_result\_truncation is True.                                                              |
| enableMemberMemoryWrite             | boolean              | 否  | When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it ...    |
| enableMemberMemoryInjection         | boolean              | 否  | When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on.                   |
| enableVectorMemory                  | boolean              | 否  | When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat hist...    |
| longTermMemoryTopK                  | integer              | 否  | 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity\_top\_k），預設為 10，範圍 1–50                                                                                                                                                      |
| enableCrossConversationSearch       | boolean              | 否  | When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation.             |
| crossConversationLookbackDays       | integer              | 否  | How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable\_cross\_conversation\_search... |
| useGatewayFallback                  | boolean              | 否  | When enabled, use the fallback group instead of the single LLM                                                                                                                                                 |
| gatewayFallbackGroup                | string (uuid)        | 否  |                                                                                                                                                                                                                |
| enableSearchMessagesTool            | boolean              | 否  | Allow the AI to search past messages in the current conversation.                                                                                                                                              |
| enableGetMessageContextTool         | boolean              | 否  | Allow the AI to retrieve messages surrounding a specific message for context.                                                                                                                                  |
| enableReadAttachmentFullTextTool    | boolean              | 否  | Allow the AI to read the full text of plain-text attachments. AGENT mode only.                                                                                                                                 |
| enableParseAttachmentContentTool    | boolean              | 否  | Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only.                                                                                                                              |
| enableListAvailableParsersTool      | boolean              | 否  | Allow the AI to list available parsers and their capabilities. AGENT mode only.                                                                                                                                |
| enableGetDownloadLinkTool           | boolean              | 否  | Allow the AI to generate shareable download links for produced content. AGENT mode only.                                                                                                                       |
| webChatIsActive                     | boolean              | 否  | Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignor...    |
| apiIsActive                         | boolean              | 否  | Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on u...    |
| fileWorkspaceMode                   | object               | 否  | File workspace mode in Work internal conversations: none, bound or user\_mount. `none`: None ; `bound`: Bound workspace ; `user_mount`: User mount;                                                            |
| fileWorkspaceFolder                 | string (uuid)        | 否  | The bound workspace (folder id); required when the mode is bound, cleared otherwise.                                                                                                                           |

**請求結構範例**

```typescript
{
  "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": true,
  "searchKnowledgeBaseFirst": true,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "enableBrowserTool": true,
  "browserToolMaxSteps": 123,
  "enableCloudDesktop": true,
  "cloudDesktopAllowedDomains": [
    "範例字串"
  ],
  "enableImageSearch": true,
  "enableClaudeStreamRetry": true,
  "enableStreamStallRetry": true,
  "customMaxLlmOutputTokens": 123,
  "voiceConfig": {
    "enabled": true,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "範例字串",
    "turnHandling": null,
    "enableVoiceReply": true
  },
  "thinkingConfig": null,
  "enableToolSearching": true,
  "toolLoadingMode": {},
  "maxAgentIterations": 123,
  "agentTimeoutSeconds": 123,
  "agentTimeoutMessage": "範例字串",
  "systemErrorMessage": "範例字串",
  "requireTextWithFlexCards": true,
  "enableSizeBasedToolResultTruncation": true,
  "toolResultMaxChars": 123,
  "enableMemberMemoryWrite": true,
  "enableMemberMemoryInjection": true,
  "enableVectorMemory": true,
  "longTermMemoryTopK": 123,
  "enableCrossConversationSearch": true,
  "crossConversationLookbackDays": 123,
  "useGatewayFallback": true,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": true,
  "enableGetMessageContextTool": true,
  "enableReadAttachmentFullTextTool": true,
  "enableParseAttachmentContentTool": true,
  "enableListAvailableParsersTool": true,
  "enableGetDownloadLinkTool": true,
  "webChatIsActive": true,
  "apiIsActive": true,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "connectors": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": null,
    "useFullRetrievalRange": true,
    "searchKnowledgeBaseFirst": true,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "enableBrowserTool": true,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": true,
    "cloudDesktopAllowedDomains": [
      "範例字串"
    ],
    "enableImageSearch": true,
    "enableClaudeStreamRetry": true,
    "enableStreamStallRetry": true,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
      "enabled": true,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "realtimeInstructions": "範例字串",
      "turnHandling": null,
      "enableVoiceReply": true
    },
    "thinkingConfig": null,
    "enableToolSearching": true,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": true,
    "enableSizeBasedToolResultTruncation": true,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": true,
    "enableMemberMemoryInjection": true,
    "enableVectorMemory": true,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": true,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": true,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": true,
    "enableGetMessageContextTool": true,
    "enableReadAttachmentFullTextTool": true,
    "enableParseAttachmentContentTool": true,
    "enableListAvailableParsersTool": true,
    "enableGetDownloadLinkTool": true,
    "webChatIsActive": true,
    "apiIsActive": true,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "connectors": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": null,
    "useFullRetrievalRange": true,
    "searchKnowledgeBaseFirst": true,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "enableBrowserTool": true,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": true,
    "cloudDesktopAllowedDomains": [
      "範例字串"
    ],
    "enableImageSearch": true,
    "enableClaudeStreamRetry": true,
    "enableStreamStallRetry": true,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
      "enabled": true,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "realtimeInstructions": "範例字串",
      "turnHandling": null,
      "enableVoiceReply": true
    },
    "thinkingConfig": null,
    "enableToolSearching": true,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": true,
    "enableSizeBasedToolResultTruncation": true,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": true,
    "enableMemberMemoryInjection": true,
    "enableVectorMemory": true,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": true,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": true,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": true,
    "enableGetMessageContextTool": true,
    "enableReadAttachmentFullTextTool": true,
    "enableParseAttachmentContentTool": true,
    "enableListAvailableParsersTool": true,
    "enableGetDownloadLinkTool": true,
    "webChatIsActive": true,
    "apiIsActive": true,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.put("https://api.maiagent.ai/api/v1/chatbots/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/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "databases": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": None,
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "tools": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "skills": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "connectors": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": None,
    "useFullRetrievalRange": True,
    "searchKnowledgeBaseFirst": True,
    "enableEvaluation": True,
    "enableInlineCitations": True,
    "enableCodeInterpreter": True,
    "enableBrowserTool": True,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": True,
    "cloudDesktopAllowedDomains": [
        "範例字串"
    ],
    "enableImageSearch": True,
    "enableClaudeStreamRetry": True,
    "enableStreamStallRetry": True,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
        "enabled": True,
        "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
        "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
        "sttConfig": None,
        "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
        "ttsConfig": None,
        "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
        "realtimeConfig": None,
        "realtimeInstructions": "範例字串",
        "turnHandling": None,
        "enableVoiceReply": True
    },
    "thinkingConfig": None,
    "enableToolSearching": True,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": True,
    "enableSizeBasedToolResultTruncation": True,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": True,
    "enableMemberMemoryInjection": True,
    "enableVectorMemory": True,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": True,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": True,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": True,
    "enableGetMessageContextTool": True,
    "enableReadAttachmentFullTextTool": True,
    "enableParseAttachmentContentTool": True,
    "enableListAvailableParsersTool": True,
    "enableGetDownloadLinkTool": True,
    "webChatIsActive": True,
    "apiIsActive": True,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
}

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/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'largeLanguageModel' => '550e8400-e29b-41d4-a716-446655440000',
            'condenseQuestionLlm' => '550e8400-e29b-41d4-a716-446655440000',
            'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000',
            'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000',
            'instructions' => '範例字串',
            'knowledgeBases' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'databases' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'organization' => '550e8400-e29b-41d4-a716-446655440000',
            'replyMode' => new \stdClass(),
            'template' => '範例字串',
            'unanswerableTemplate' => '範例字串',
            'totalWordsCount' => 123,
            'outputMode' => new \stdClass(),
            'rawOutputFormat' => null,
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'tools' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'skills' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'connectors' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'agentMode' => new \stdClass(),
            'numberOfRetrievedChunks' => 123,
            'defaultLabelRelations' => null,
            'useFullRetrievalRange' => true,
            'searchKnowledgeBaseFirst' => true,
            'enableEvaluation' => true,
            'enableInlineCitations' => true,
            'enableCodeInterpreter' => true,
            'enableBrowserTool' => true,
            'browserToolMaxSteps' => 123,
            'enableCloudDesktop' => true,
            'cloudDesktopAllowedDomains' => [
                '範例字串'
            ],
            'enableImageSearch' => true,
            'enableClaudeStreamRetry' => true,
            'enableStreamStallRetry' => true,
            'customMaxLlmOutputTokens' => 123,
            'voiceConfig' => [
                'enabled' => true,
                'voiceAgentType' => '550e8400-e29b-41d4-a716-446655440000',
                'sttProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'sttConfig' => null,
                'ttsProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'ttsConfig' => null,
                'realtimeProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'realtimeConfig' => null,
                'realtimeInstructions' => '範例字串',
                'turnHandling' => null,
                'enableVoiceReply' => true
            ],
            'thinkingConfig' => null,
            'enableToolSearching' => true,
            'toolLoadingMode' => new \stdClass(),
            'maxAgentIterations' => 123,
            'agentTimeoutSeconds' => 123,
            'agentTimeoutMessage' => '範例字串',
            'systemErrorMessage' => '範例字串',
            'requireTextWithFlexCards' => true,
            'enableSizeBasedToolResultTruncation' => true,
            'toolResultMaxChars' => 123,
            'enableMemberMemoryWrite' => true,
            'enableMemberMemoryInjection' => true,
            'enableVectorMemory' => true,
            'longTermMemoryTopK' => 123,
            'enableCrossConversationSearch' => true,
            'crossConversationLookbackDays' => 123,
            'useGatewayFallback' => true,
            'gatewayFallbackGroup' => '550e8400-e29b-41d4-a716-446655440000',
            'enableSearchMessagesTool' => true,
            'enableGetMessageContextTool' => true,
            'enableReadAttachmentFullTextTool' => true,
            'enableParseAttachmentContentTool' => true,
            'enableListAvailableParsersTool' => true,
            'enableGetDownloadLinkTool' => true,
            'webChatIsActive' => true,
            'apiIsActive' => true,
            'fileWorkspaceMode' => new \stdClass(),
            'fileWorkspaceFolder' => '550e8400-e29b-41d4-a716-446655440000'
        ]
    ]);
    
    $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 // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
  "llm":  // 綁定模型的 id、name 與退役資訊，直接讀取 FK，即使該模型已被組織停用仍會回傳
  {
    "id": string (uuid)
    "name": string
    "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
    "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
    {
      "id": string (uuid)
      "name": string
    }
  }
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "defaultCondenseQuestionLlm":  // 跟隨系統設定時實際使用的問題改寫模型（id 與 name）；null 表示由助理主模型改寫（唯讀）
  {
    "id": string (uuid)
    "name": string
  }
  "organizationEnforcedSettings": [ // 組織 AI助理預設值對這個助理強制的項目代碼（與 AI助理預設值 API 的 key 相同）；這些欄位讀回的就是強制值，更新時帶不同的值會被拒絕（唯讀；官方內建 Agent 與 MaiGPT 為空）
    string
  ]
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "source": string
      "isGlobal": boolean
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "defaultBrowserToolMaxSteps": integer // Read-only. The site-wide browser step limit an assistant without its own limit uses.
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "cloudDesktopAvailable": boolean // Whether the site-wide setting lets this assistant offer the cloud desktop switch
  "cloudDesktopModelSupported": boolean // Whether the assistant's current model can run the cloud desktop
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified
  "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "team": 
  {
    "id": string (uuid)
    "name": string
  }
  "isBuiltinTeamEntry": boolean // Read-only. Whether this assistant is the entry of a team on the built-in entry node.
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
  "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null}
  "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace.
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "llm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "retiresAt": "回應字串",
    "replacement": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  },
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "defaultCondenseQuestionLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organizationEnforcedSettings": [
    "回應字串"
  ],
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "source": "回應字串",
      "isGlobal": false
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": false,
  "searchKnowledgeBaseFirst": false,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "enableBrowserTool": false,
  "browserToolMaxSteps": 456,
  "defaultBrowserToolMaxSteps": 456,
  "enableCloudDesktop": false,
  "cloudDesktopAllowedDomains": [
    "回應字串"
  ],
  "cloudDesktopAvailable": false,
  "cloudDesktopModelSupported": false,
  "enableImageSearch": false,
  "enableClaudeStreamRetry": false,
  "enableStreamStallRetry": false,
  "customMaxLlmOutputTokens": 456,
  "voiceConfig": {
    "enabled": false,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "回應字串",
    "turnHandling": null,
    "enableVoiceReply": false
  },
  "thinkingConfig": null,
  "enableToolSearching": false,
  "toolLoadingMode": {},
  "maxAgentIterations": 456,
  "agentTimeoutSeconds": 456,
  "agentTimeoutMessage": "回應字串",
  "systemErrorMessage": "回應字串",
  "requireTextWithFlexCards": false,
  "isMultimodalLlm": false,
  "enableSizeBasedToolResultTruncation": false,
  "toolResultMaxChars": 456,
  "enableMemberMemoryWrite": false,
  "enableMemberMemoryInjection": false,
  "enableVectorMemory": false,
  "longTermMemoryTopK": 456,
  "enableCrossConversationSearch": false,
  "crossConversationLookbackDays": 456,
  "useGatewayFallback": false,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": false,
  "enableGetMessageContextTool": false,
  "enableReadAttachmentFullTextTool": false,
  "enableParseAttachmentContentTool": false,
  "enableListAvailableParsersTool": false,
  "enableGetDownloadLinkTool": false,
  "isLocked": false,
  "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
  "canUpdate": false,
  "canDelete": false,
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isBuiltinTeamEntry": false,
  "webChatIsActive": false,
  "apiIsActive": false,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
  "fileWorkspaceStatus": {
    "name": "example.pdf",
    "content": "base64encoded_content",
    "contentType": "application/pdf"
  },
  "fileWorkspaceAvailable": false
}
```

***

### 部分更新 AI 助理 <a href="#chatbots-partial-update" id="chatbots-partial-update"></a>

PATCH `/api/v1/chatbots/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                                  | 類型                   | 必填 | 說明                                                                                                                                                                                                             |
| ----------------------------------- | -------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                | string               | 否  | Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.                                                                                                        |
| largeLanguageModel                  | string (uuid)        | 否  | 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略                                                                                                                                           |
| condenseQuestionLlm                 | string (uuid)        | 否  | 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定）                                                                                                                                  |
| embeddingModel                      | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                                                                                                                                             |
| rerankerModel                       | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                                                                                                                                                |
| instructions                        | string               | 否  | Role instructions describing the chatbot's role and behavior.                                                                                                                                                  |
| knowledgeBases                      | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                                                                                                                                   |
| databases                           | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                                                                                                                                           |
| organization                        | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                                                                                                                                           |
| replyMode                           | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: Normal ; `template`: Template ; `hybrid`: Hybrid ; `agent`: Agent;                                                                                                                    |
| template                            | string               | 否  | Template used by Template and Hybrid modes.                                                                                                                                                                    |
| unanswerableTemplate                | string               | 否  | Template used by Template and Hybrid modes when the question cannot be answered.                                                                                                                               |
| totalWordsCount                     | integer (int64)      | 否  | Accumulated total word count used.                                                                                                                                                                             |
| outputMode                          | object               | 否  | 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字） `text`: Text ; `json_schema`: JSON Schema;                                                                                                       |
| rawOutputFormat                     | object               | 否  | 自定義輸出格式的JSON結構定義                                                                                                                                                                                               |
| groups                              | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                                                                                                                                    |
| tools                               | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                                                                                                                                    |
| skills                              | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                                                                                                                                     |
| connectors                          | array\[IdName]       | 否  | Connectors associated with this chatbot, gating per-contact OAuth authorization                                                                                                                                |
| agentMode                           | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: Normal ; `canvas`: Canvas ; `team`: Team;                                                                                                                                         |
| numberOfRetrievedChunks             | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                                                        |
| defaultLabelRelations               | object               | 否  | 助理層級的預設知識庫標籤過濾條件，格式同 query\_metadata.label\_relations；null 表示不過濾。僅在呼叫端未帶 query\_metadata 時作為最低優先序兜底套用。                                                                                                         |
| useFullRetrievalRange               | boolean              | 否  | 啟用後忽略 LLM 的 top\_k 截斷，回傳完整 reranker 結果                                                                                                                                                                         |
| searchKnowledgeBaseFirst            | boolean              | 否  | Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can\_use\_search\_knowledge\_base\_first）                                                                                           |
| enableEvaluation                    | boolean              | 否  |                                                                                                                                                                                                                |
| enableInlineCitations               | boolean              | 否  | Enables inline citations, inserting citation markers such as \[1]\[2] into responses.                                                                                                                          |
| enableCodeInterpreter               | boolean              | 否  | When enabled, provides the Code Interpreter tool to run code in an isolated container.                                                                                                                         |
| enableBrowserTool                   | boolean              | 否  | Enable browser automation tool for web tasks                                                                                                                                                                   |
| browserToolMaxSteps                 | integer              | 否  | Most browser actions one reply of this assistant may take (1-100); null follows default\_browser\_tool\_max\_steps. Leaving it out of an update keeps the stored value.                                        |
| enableCloudDesktop                  | boolean              | 否  | Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization.                                       |
| cloudDesktopAllowedDomains          | array\[string]       | 否  | Domains the cloud desktop may reach, one per item; empty means no restriction (S19)                                                                                                                            |
| enableImageSearch                   | boolean              | 否  | Provide the image\_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely.                                                                        |
| enableClaudeStreamRetry             | boolean              | 否  | When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial outpu...    |
| enableStreamStallRetry              | boolean              | 否  | When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow ...    |
| customMaxLlmOutputTokens            | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                                                                                                                                   |
| voiceConfig                         | object               | 否  |                                                                                                                                                                                                                |
| voiceConfig.enabled                 | boolean              | 否  | Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle.                                 |
| voiceConfig.voiceAgentType          | string (uuid)        | 否  | Voice agent mode type.                                                                                                                                                                                         |
| voiceConfig.sttProvider             | string (uuid)        | 否  | Speech-to-Text service provider.                                                                                                                                                                               |
| voiceConfig.sttConfig               | object               | 否  | STT configuration parameters (JSON).                                                                                                                                                                           |
| voiceConfig.ttsProvider             | string (uuid)        | 否  | Text-to-Speech service provider.                                                                                                                                                                               |
| voiceConfig.ttsConfig               | object               | 否  | TTS configuration parameters (JSON).                                                                                                                                                                           |
| voiceConfig.realtimeProvider        | string (uuid)        | 否  | Realtime end-to-end voice model provider.                                                                                                                                                                      |
| voiceConfig.realtimeConfig          | object               | 否  | Realtime configuration parameters (JSON).                                                                                                                                                                      |
| voiceConfig.realtimeInstructions    | string               | 否  | Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty                                                                                                                  |
| voiceConfig.turnHandling            | object               | 否  | Turn-taking and interruption settings for the voice agent.                                                                                                                                                     |
| voiceConfig.enableVoiceReply        | boolean              | 否  | When disabled, the voice agent replies in text only and does not speak                                                                                                                                         |
| thinkingConfig                      | object               | 否  | 思考等級：null（模型預設）或 {"reasoning\_effort": "off                                                                                                                                                                    |
| enableToolSearching                 | boolean              | 否  | 舊欄位，請改用 tool\_loading\_mode。寫入 true 等同 tool\_loading\_mode=search、false 等同 all；兩者都帶時以 tool\_loading\_mode 為準。讀取時回傳「工具載入方式不是全部載入」。                                                                              |
| toolLoadingMode                     | object               | 否  | 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。 `auto`: Auto ; `all`: Load all ; `search`: Dynamic search;                                              |
| maxAgentIterations                  | integer              | 否  | Maximum number of iterations for AgentWorkflow (1-100, default: 20)                                                                                                                                            |
| agentTimeoutSeconds                 | integer              | 否  | Timeout in seconds for AgentWorkflow execution (30-1200, default: 600)                                                                                                                                         |
| agentTimeoutMessage                 | string               | 否  | Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default.                                                                                          |
| systemErrorMessage                  | string               | 否  | Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default.                             |
| requireTextWithFlexCards            | boolean              | 否  | When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a se...    |
| enableSizeBasedToolResultTruncation | boolean              | 否  | When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversati...    |
| toolResultMaxChars                  | integer              | 否  | Character threshold for size-based tool result truncation (500-50000). Only effective when enable\_size\_based\_tool\_result\_truncation is True.                                                              |
| enableMemberMemoryWrite             | boolean              | 否  | When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it ...    |
| enableMemberMemoryInjection         | boolean              | 否  | When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on.                   |
| enableVectorMemory                  | boolean              | 否  | When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat hist...    |
| longTermMemoryTopK                  | integer              | 否  | 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity\_top\_k），預設為 10，範圍 1–50                                                                                                                                                      |
| enableCrossConversationSearch       | boolean              | 否  | When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation.             |
| crossConversationLookbackDays       | integer              | 否  | How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable\_cross\_conversation\_search... |
| useGatewayFallback                  | boolean              | 否  | When enabled, use the fallback group instead of the single LLM                                                                                                                                                 |
| gatewayFallbackGroup                | string (uuid)        | 否  |                                                                                                                                                                                                                |
| enableSearchMessagesTool            | boolean              | 否  | Allow the AI to search past messages in the current conversation.                                                                                                                                              |
| enableGetMessageContextTool         | boolean              | 否  | Allow the AI to retrieve messages surrounding a specific message for context.                                                                                                                                  |
| enableReadAttachmentFullTextTool    | boolean              | 否  | Allow the AI to read the full text of plain-text attachments. AGENT mode only.                                                                                                                                 |
| enableParseAttachmentContentTool    | boolean              | 否  | Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only.                                                                                                                              |
| enableListAvailableParsersTool      | boolean              | 否  | Allow the AI to list available parsers and their capabilities. AGENT mode only.                                                                                                                                |
| enableGetDownloadLinkTool           | boolean              | 否  | Allow the AI to generate shareable download links for produced content. AGENT mode only.                                                                                                                       |
| webChatIsActive                     | boolean              | 否  | Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignor...    |
| apiIsActive                         | boolean              | 否  | Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on u...    |
| fileWorkspaceMode                   | object               | 否  | File workspace mode in Work internal conversations: none, bound or user\_mount. `none`: None ; `bound`: Bound workspace ; `user_mount`: User mount;                                                            |
| fileWorkspaceFolder                 | string (uuid)        | 否  | The bound workspace (folder id); required when the mode is bound, cleared otherwise.                                                                                                                           |

**請求結構範例**

```typescript
{
  "name"?: string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. (非必填)
  "largeLanguageModel"?: string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略 (非必填)
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": true,
  "searchKnowledgeBaseFirst": true,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "enableBrowserTool": true,
  "browserToolMaxSteps": 123,
  "enableCloudDesktop": true,
  "cloudDesktopAllowedDomains": [
    "範例字串"
  ],
  "enableImageSearch": true,
  "enableClaudeStreamRetry": true,
  "enableStreamStallRetry": true,
  "customMaxLlmOutputTokens": 123,
  "voiceConfig": {
    "enabled": true,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "範例字串",
    "turnHandling": null,
    "enableVoiceReply": true
  },
  "thinkingConfig": null,
  "enableToolSearching": true,
  "toolLoadingMode": {},
  "maxAgentIterations": 123,
  "agentTimeoutSeconds": 123,
  "agentTimeoutMessage": "範例字串",
  "systemErrorMessage": "範例字串",
  "requireTextWithFlexCards": true,
  "enableSizeBasedToolResultTruncation": true,
  "toolResultMaxChars": 123,
  "enableMemberMemoryWrite": true,
  "enableMemberMemoryInjection": true,
  "enableVectorMemory": true,
  "longTermMemoryTopK": 123,
  "enableCrossConversationSearch": true,
  "crossConversationLookbackDays": 123,
  "useGatewayFallback": true,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": true,
  "enableGetMessageContextTool": true,
  "enableReadAttachmentFullTextTool": true,
  "enableParseAttachmentContentTool": true,
  "enableListAvailableParsersTool": true,
  "enableGetDownloadLinkTool": true,
  "webChatIsActive": true,
  "apiIsActive": true,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "connectors": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": null,
    "useFullRetrievalRange": true,
    "searchKnowledgeBaseFirst": true,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "enableBrowserTool": true,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": true,
    "cloudDesktopAllowedDomains": [
      "範例字串"
    ],
    "enableImageSearch": true,
    "enableClaudeStreamRetry": true,
    "enableStreamStallRetry": true,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
      "enabled": true,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "realtimeInstructions": "範例字串",
      "turnHandling": null,
      "enableVoiceReply": true
    },
    "thinkingConfig": null,
    "enableToolSearching": true,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": true,
    "enableSizeBasedToolResultTruncation": true,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": true,
    "enableMemberMemoryInjection": true,
    "enableVectorMemory": true,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": true,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": true,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": true,
    "enableGetMessageContextTool": true,
    "enableReadAttachmentFullTextTool": true,
    "enableParseAttachmentContentTool": true,
    "enableListAvailableParsersTool": true,
    "enableGetDownloadLinkTool": true,
    "webChatIsActive": true,
    "apiIsActive": true,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "connectors": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": null,
    "useFullRetrievalRange": true,
    "searchKnowledgeBaseFirst": true,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "enableBrowserTool": true,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": true,
    "cloudDesktopAllowedDomains": [
      "範例字串"
    ],
    "enableImageSearch": true,
    "enableClaudeStreamRetry": true,
    "enableStreamStallRetry": true,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
      "enabled": true,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "realtimeInstructions": "範例字串",
      "turnHandling": null,
      "enableVoiceReply": true
    },
    "thinkingConfig": null,
    "enableToolSearching": true,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": true,
    "enableSizeBasedToolResultTruncation": true,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": true,
    "enableMemberMemoryInjection": true,
    "enableVectorMemory": true,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": true,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": true,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": true,
    "enableGetMessageContextTool": true,
    "enableReadAttachmentFullTextTool": true,
    "enableParseAttachmentContentTool": true,
    "enableListAvailableParsersTool": true,
    "enableGetDownloadLinkTool": true,
    "webChatIsActive": true,
    "apiIsActive": true,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.patch("https://api.maiagent.ai/api/v1/chatbots/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/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "databases": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": None,
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "tools": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "skills": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "connectors": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "defaultLabelRelations": None,
    "useFullRetrievalRange": True,
    "searchKnowledgeBaseFirst": True,
    "enableEvaluation": True,
    "enableInlineCitations": True,
    "enableCodeInterpreter": True,
    "enableBrowserTool": True,
    "browserToolMaxSteps": 123,
    "enableCloudDesktop": True,
    "cloudDesktopAllowedDomains": [
        "範例字串"
    ],
    "enableImageSearch": True,
    "enableClaudeStreamRetry": True,
    "enableStreamStallRetry": True,
    "customMaxLlmOutputTokens": 123,
    "voiceConfig": {
        "enabled": True,
        "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
        "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
        "sttConfig": None,
        "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
        "ttsConfig": None,
        "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
        "realtimeConfig": None,
        "realtimeInstructions": "範例字串",
        "turnHandling": None,
        "enableVoiceReply": True
    },
    "thinkingConfig": None,
    "enableToolSearching": True,
    "toolLoadingMode": {},
    "maxAgentIterations": 123,
    "agentTimeoutSeconds": 123,
    "agentTimeoutMessage": "範例字串",
    "systemErrorMessage": "範例字串",
    "requireTextWithFlexCards": True,
    "enableSizeBasedToolResultTruncation": True,
    "toolResultMaxChars": 123,
    "enableMemberMemoryWrite": True,
    "enableMemberMemoryInjection": True,
    "enableVectorMemory": True,
    "longTermMemoryTopK": 123,
    "enableCrossConversationSearch": True,
    "crossConversationLookbackDays": 123,
    "useGatewayFallback": True,
    "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
    "enableSearchMessagesTool": True,
    "enableGetMessageContextTool": True,
    "enableReadAttachmentFullTextTool": True,
    "enableParseAttachmentContentTool": True,
    "enableListAvailableParsersTool": True,
    "enableGetDownloadLinkTool": True,
    "webChatIsActive": True,
    "apiIsActive": True,
    "fileWorkspaceMode": {},
    "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000"
}

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/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'largeLanguageModel' => '550e8400-e29b-41d4-a716-446655440000',
            'condenseQuestionLlm' => '550e8400-e29b-41d4-a716-446655440000',
            'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000',
            'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000',
            'instructions' => '範例字串',
            'knowledgeBases' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'databases' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'organization' => '550e8400-e29b-41d4-a716-446655440000',
            'replyMode' => new \stdClass(),
            'template' => '範例字串',
            'unanswerableTemplate' => '範例字串',
            'totalWordsCount' => 123,
            'outputMode' => new \stdClass(),
            'rawOutputFormat' => null,
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'tools' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'skills' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'connectors' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'agentMode' => new \stdClass(),
            'numberOfRetrievedChunks' => 123,
            'defaultLabelRelations' => null,
            'useFullRetrievalRange' => true,
            'searchKnowledgeBaseFirst' => true,
            'enableEvaluation' => true,
            'enableInlineCitations' => true,
            'enableCodeInterpreter' => true,
            'enableBrowserTool' => true,
            'browserToolMaxSteps' => 123,
            'enableCloudDesktop' => true,
            'cloudDesktopAllowedDomains' => [
                '範例字串'
            ],
            'enableImageSearch' => true,
            'enableClaudeStreamRetry' => true,
            'enableStreamStallRetry' => true,
            'customMaxLlmOutputTokens' => 123,
            'voiceConfig' => [
                'enabled' => true,
                'voiceAgentType' => '550e8400-e29b-41d4-a716-446655440000',
                'sttProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'sttConfig' => null,
                'ttsProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'ttsConfig' => null,
                'realtimeProvider' => '550e8400-e29b-41d4-a716-446655440000',
                'realtimeConfig' => null,
                'realtimeInstructions' => '範例字串',
                'turnHandling' => null,
                'enableVoiceReply' => true
            ],
            'thinkingConfig' => null,
            'enableToolSearching' => true,
            'toolLoadingMode' => new \stdClass(),
            'maxAgentIterations' => 123,
            'agentTimeoutSeconds' => 123,
            'agentTimeoutMessage' => '範例字串',
            'systemErrorMessage' => '範例字串',
            'requireTextWithFlexCards' => true,
            'enableSizeBasedToolResultTruncation' => true,
            'toolResultMaxChars' => 123,
            'enableMemberMemoryWrite' => true,
            'enableMemberMemoryInjection' => true,
            'enableVectorMemory' => true,
            'longTermMemoryTopK' => 123,
            'enableCrossConversationSearch' => true,
            'crossConversationLookbackDays' => 123,
            'useGatewayFallback' => true,
            'gatewayFallbackGroup' => '550e8400-e29b-41d4-a716-446655440000',
            'enableSearchMessagesTool' => true,
            'enableGetMessageContextTool' => true,
            'enableReadAttachmentFullTextTool' => true,
            'enableParseAttachmentContentTool' => true,
            'enableListAvailableParsersTool' => true,
            'enableGetDownloadLinkTool' => true,
            'webChatIsActive' => true,
            'apiIsActive' => true,
            'fileWorkspaceMode' => new \stdClass(),
            'fileWorkspaceFolder' => '550e8400-e29b-41d4-a716-446655440000'
        ]
    ]);
    
    $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 // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
  "llm":  // 綁定模型的 id、name 與退役資訊，直接讀取 FK，即使該模型已被組織停用仍會回傳
  {
    "id": string (uuid)
    "name": string
    "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
    "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
    {
      "id": string (uuid)
      "name": string
    }
  }
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "defaultCondenseQuestionLlm":  // 跟隨系統設定時實際使用的問題改寫模型（id 與 name）；null 表示由助理主模型改寫（唯讀）
  {
    "id": string (uuid)
    "name": string
  }
  "organizationEnforcedSettings": [ // 組織 AI助理預設值對這個助理強制的項目代碼（與 AI助理預設值 API 的 key 相同）；這些欄位讀回的就是強制值，更新時帶不同的值會被拒絕（唯讀；官方內建 Agent 與 MaiGPT 為空）
    string
  ]
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "source": string
      "isGlobal": boolean
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "defaultBrowserToolMaxSteps": integer // Read-only. The site-wide browser step limit an assistant without its own limit uses.
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "cloudDesktopAvailable": boolean // Whether the site-wide setting lets this assistant offer the cloud desktop switch
  "cloudDesktopModelSupported": boolean // Whether the assistant's current model can run the cloud desktop
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified
  "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "team": 
  {
    "id": string (uuid)
    "name": string
  }
  "isBuiltinTeamEntry": boolean // Read-only. Whether this assistant is the entry of a team on the built-in entry node.
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
  "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null}
  "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace.
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "llm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "retiresAt": "回應字串",
    "replacement": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  },
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "defaultCondenseQuestionLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organizationEnforcedSettings": [
    "回應字串"
  ],
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "source": "回應字串",
      "isGlobal": false
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": false,
  "searchKnowledgeBaseFirst": false,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "enableBrowserTool": false,
  "browserToolMaxSteps": 456,
  "defaultBrowserToolMaxSteps": 456,
  "enableCloudDesktop": false,
  "cloudDesktopAllowedDomains": [
    "回應字串"
  ],
  "cloudDesktopAvailable": false,
  "cloudDesktopModelSupported": false,
  "enableImageSearch": false,
  "enableClaudeStreamRetry": false,
  "enableStreamStallRetry": false,
  "customMaxLlmOutputTokens": 456,
  "voiceConfig": {
    "enabled": false,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "回應字串",
    "turnHandling": null,
    "enableVoiceReply": false
  },
  "thinkingConfig": null,
  "enableToolSearching": false,
  "toolLoadingMode": {},
  "maxAgentIterations": 456,
  "agentTimeoutSeconds": 456,
  "agentTimeoutMessage": "回應字串",
  "systemErrorMessage": "回應字串",
  "requireTextWithFlexCards": false,
  "isMultimodalLlm": false,
  "enableSizeBasedToolResultTruncation": false,
  "toolResultMaxChars": 456,
  "enableMemberMemoryWrite": false,
  "enableMemberMemoryInjection": false,
  "enableVectorMemory": false,
  "longTermMemoryTopK": 456,
  "enableCrossConversationSearch": false,
  "crossConversationLookbackDays": 456,
  "useGatewayFallback": false,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": false,
  "enableGetMessageContextTool": false,
  "enableReadAttachmentFullTextTool": false,
  "enableParseAttachmentContentTool": false,
  "enableListAvailableParsersTool": false,
  "enableGetDownloadLinkTool": false,
  "isLocked": false,
  "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
  "canUpdate": false,
  "canDelete": false,
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isBuiltinTeamEntry": false,
  "webChatIsActive": false,
  "apiIsActive": false,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
  "fileWorkspaceStatus": {
    "name": "example.pdf",
    "content": "base64encoded_content",
    "contentType": "application/pdf"
  },
  "fileWorkspaceAvailable": false
}
```

***

### 刪除 AI 助理 <a href="#chatbots-destroy" id="chatbots-destroy"></a>

DELETE `/api/v1/chatbots/{id}/`

#### 參數

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

#### 程式碼範例

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/chatbots/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/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(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->delete("https://api.maiagent.ai/api/v1/chatbots/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 %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 複製 AI 助理 <a href="#chatbots-duplicate-create" id="chatbots-duplicate-create"></a>

POST `/api/v1/chatbots/{id}/duplicate/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 是  |    |

**請求結構範例**

```typescript
{
  "name": string
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱"
  };

axios.post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", 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/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱"
}

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/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱'
        ]
    ]);
    
    $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 // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
  "llm":  // 綁定模型的 id、name 與退役資訊，直接讀取 FK，即使該模型已被組織停用仍會回傳
  {
    "id": string (uuid)
    "name": string
    "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
    "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
    {
      "id": string (uuid)
      "name": string
    }
  }
  "condenseQuestionLlm"?: string (uuid) // 問題改寫模型：RAG 回覆模式檢索前把追問改寫成獨立問題；null 表示跟隨系統設定（已選的模型之後被組織封鎖或停用時，也讀回 null 並跟隨系統設定） (非必填)
  "defaultCondenseQuestionLlm":  // 跟隨系統設定時實際使用的問題改寫模型（id 與 name）；null 表示由助理主模型改寫（唯讀）
  {
    "id": string (uuid)
    "name": string
  }
  "organizationEnforcedSettings": [ // 組織 AI助理預設值對這個助理強制的項目代碼（與 AI助理預設值 API 的 key 相同）；這些欄位讀回的就是強制值，更新時帶不同的值會被拒絕（唯讀；官方內建 Agent 與 MaiGPT 為空）
    string
  ]
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
  {
  }
  "template"?: string // Template used by Template and Hybrid modes. (非必填)
  "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
  "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
  "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - Text
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "source": string
      "isGlobal": boolean
    }
  ]
  "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
  "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
  "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
  "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
  "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
  "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
  "defaultBrowserToolMaxSteps": integer // Read-only. The site-wide browser step limit an assistant without its own limit uses.
  "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
  "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
    string
  ]
  "cloudDesktopAvailable": boolean // Whether the site-wide setting lets this assistant offer the cloud desktop switch
  "cloudDesktopModelSupported": boolean // Whether the assistant's current model can run the cloud desktop
  "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
  "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
  "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceConfig"?: { // 非必填
  {
    "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
    "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
    "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
    "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
    "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
    "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
    "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
    "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
    "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
    "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
    "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
  }
  }
  "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
  "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
  "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
  {
  }
  "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
  "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
  "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
  "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
  "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
  "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
  "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
  "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
  "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
  "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
  "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
  "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
  "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
  "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
  "gatewayFallbackGroup"?: string (uuid) // 非必填
  "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
  "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
  "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
  "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
  "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
  "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
  "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified
  "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "team": 
  {
    "id": string (uuid)
    "name": string
  }
  "isBuiltinTeamEntry": boolean // Read-only. Whether this assistant is the entry of a team on the built-in entry node.
  "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
  "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
  "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
  {
  }
  "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
  "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null}
  "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace.
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "llm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "retiresAt": "回應字串",
    "replacement": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  },
  "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000",
  "defaultCondenseQuestionLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organizationEnforcedSettings": [
    "回應字串"
  ],
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "source": "回應字串",
      "isGlobal": false
    }
  ],
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "defaultLabelRelations": null,
  "useFullRetrievalRange": false,
  "searchKnowledgeBaseFirst": false,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "enableBrowserTool": false,
  "browserToolMaxSteps": 456,
  "defaultBrowserToolMaxSteps": 456,
  "enableCloudDesktop": false,
  "cloudDesktopAllowedDomains": [
    "回應字串"
  ],
  "cloudDesktopAvailable": false,
  "cloudDesktopModelSupported": false,
  "enableImageSearch": false,
  "enableClaudeStreamRetry": false,
  "enableStreamStallRetry": false,
  "customMaxLlmOutputTokens": 456,
  "voiceConfig": {
    "enabled": false,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "realtimeInstructions": "回應字串",
    "turnHandling": null,
    "enableVoiceReply": false
  },
  "thinkingConfig": null,
  "enableToolSearching": false,
  "toolLoadingMode": {},
  "maxAgentIterations": 456,
  "agentTimeoutSeconds": 456,
  "agentTimeoutMessage": "回應字串",
  "systemErrorMessage": "回應字串",
  "requireTextWithFlexCards": false,
  "isMultimodalLlm": false,
  "enableSizeBasedToolResultTruncation": false,
  "toolResultMaxChars": 456,
  "enableMemberMemoryWrite": false,
  "enableMemberMemoryInjection": false,
  "enableVectorMemory": false,
  "longTermMemoryTopK": 456,
  "enableCrossConversationSearch": false,
  "crossConversationLookbackDays": 456,
  "useGatewayFallback": false,
  "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
  "enableSearchMessagesTool": false,
  "enableGetMessageContextTool": false,
  "enableReadAttachmentFullTextTool": false,
  "enableParseAttachmentContentTool": false,
  "enableListAvailableParsersTool": false,
  "enableGetDownloadLinkTool": false,
  "isLocked": false,
  "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
  "canUpdate": false,
  "canDelete": false,
  "team": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isBuiltinTeamEntry": false,
  "webChatIsActive": false,
  "apiIsActive": false,
  "fileWorkspaceMode": {},
  "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
  "fileWorkspaceStatus": {
    "name": "example.pdf",
    "content": "base64encoded_content",
    "contentType": "application/pdf"
  },
  "fileWorkspaceAvailable": false
}
```

***

### 啟用或停用評估功能 <a href="#chatbots-enable-evaluation-partial-update" id="chatbots-enable-evaluation-partial-update"></a>

PATCH `/api/v1/chatbots/{id}/enable-evaluation/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位               | 類型      | 必填 | 說明 |
| ---------------- | ------- | -- | -- |
| enableEvaluation | boolean | 否  |    |

**請求結構範例**

```typescript
{
  "enableEvaluation"?: boolean // 非必填
}
```

**請求範例值**

```json
{
  "enableEvaluation": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enableEvaluation": true
  }'

# 請確認在執行前替換 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 = {
    "enableEvaluation": true
  };

axios.patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", 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/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "enableEvaluation": True
}

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/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'enableEvaluation' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "enableEvaluation"?: boolean // 非必填
}
```

**回應範例值**

```json
{
  "enableEvaluation": false
}
```

***

### 列出組織的 Hook <a href="#hooks-list" id="hooks-list"></a>

GET `/api/v1/hooks/`

{% hint style="info" %}
Hook 由 Hook 樣板建立，觸發點與處理方式由樣板決定，建立時不能自行指定；掛載到 AI 助理後會在訊息進出時執行。功能說明見使用者手冊 [Hook 訊息攔截](https://docs.maiagent.ai/build/hook)。
{% endhint %}

#### 參數

| 參數名稱       | 必填 | 類型      | 說明                                             |
| ---------- | -- | ------- | ---------------------------------------------- |
| `page`     | ❌  | integer | A page number within the paginated result set. |
| `pageSize` | ❌  | integer | Number of results to return per page.          |
| `search`   | ❌  | string  | A search term.                                 |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/hooks/?page=1&pageSize=1&search=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/hooks/?page=1&pageSize=1&search=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/hooks/?page=1&pageSize=1&search=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/hooks/?page=1&pageSize=1&search=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
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "organization": string (uuid)
      "templateId": string (uuid)
      "templateName": string
      "templateTypeLabel": string
      "scope": string
      "name": string
      "description": string
      "triggerPoint": string
      "action": string
      "handlerType": string
      "mintsAliases": boolean
      "config": object
      "blockMessage": string
      "enabled": boolean
      "blockWhenEngineUnavailable": boolean // Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the original text is not stored either; the AI assistant cannot reply until the engine is back. Off (default): the message goes on without this hook. Once the engine is set up, a hook that cannot start or fails while running always blocks the message, whatever this setting says. Has no effect on hooks that run after the reply.
      "silentBlock": boolean // Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (default): the block message is sent as the reply. Takes effect only while the silent block switch is on in system config.
      "createdBy": object
      "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched
``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1.
        object
      ]
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "templateId": "550e8400-e29b-41d4-a716-446655440000",
      "templateName": "回應字串",
      "templateTypeLabel": "回應字串",
      "scope": "回應字串",
      "name": "回應字串",
      "description": "回應字串",
      "triggerPoint": "回應字串",
      "action": "回應字串",
      "handlerType": "回應字串",
      "mintsAliases": false,
      "config": null,
      "blockMessage": "回應字串",
      "enabled": false,
      "blockWhenEngineUnavailable": false,
      "silentBlock": false,
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        }
      ],
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}
```

***

### 依樣板建立 Hook <a href="#hooks-create" id="hooks-create"></a>

POST `/api/v1/hooks/`

#### 請求內容

**請求參數**

| 欄位                         | 類型            | 必填 | 說明                                                                                                                                                                                                          |
| -------------------------- | ------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| templateId                 | string (uuid) | 是  |                                                                                                                                                                                                             |
| name                       | string        | 是  |                                                                                                                                                                                                             |
| description                | string        | 否  |                                                                                                                                                                                                             |
| config                     | object        | 否  |                                                                                                                                                                                                             |
| blockMessage               | string        | 否  |                                                                                                                                                                                                             |
| enabled                    | boolean       | 否  |                                                                                                                                                                                                             |
| blockWhenEngineUnavailable | boolean       | 否  | Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the... |
| silentBlock                | boolean       | 否  | Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (d... |

**請求結構範例**

```typescript
{
  "templateId": string (uuid)
  "name": string
  "description"?: string // 非必填
  "config"?: object // 非必填
  "blockMessage"?: string // 非必填
  "enabled"?: boolean // 非必填
  "blockWhenEngineUnavailable"?: boolean // Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the original text is not stored either; the AI assistant cannot reply until the engine is back. Off (default): the message goes on without this hook. Once the engine is set up, a hook that cannot start or fails while running always blocks the message, whatever this setting says. Has no effect on hooks that run after the reply. (非必填)
  "silentBlock"?: boolean // Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (default): the block message is sent as the reply. Takes effect only while the silent block switch is on in system config. (非必填)
}
```

**請求範例值**

```json
{
  "template_id": "00000000-0000-0000-0000-000000000001",
  "name": "Customer PII Redaction",
  "description": "Mask phone numbers and emails in inbound messages.",
  "config": {
    "data": {
      "patterns": [
        "phone",
        "email"
      ],
      "mode": "mask"
    }
  },
  "block_message": "",
  "enabled": true,
  "block_when_engine_unavailable": false,
  "silent_block": false
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/hooks/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "00000000-0000-0000-0000-000000000001",
    "name": "Customer PII Redaction",
    "description": "Mask phone numbers and emails in inbound messages.",
    "config": {
      "data": {
        "patterns": [
          "phone",
          "email"
        ],
        "mode": "mask"
      }
    },
    "block_message": "",
    "enabled": true,
    "block_when_engine_unavailable": false,
    "silent_block": false
  }'

# 請確認在執行前替換 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 = {
    "template_id": "00000000-0000-0000-0000-000000000001",
    "name": "Customer PII Redaction",
    "description": "Mask phone numbers and emails in inbound messages.",
    "config": {
      "data": {
        "patterns": [
          "phone",
          "email"
        ],
        "mode": "mask"
      }
    },
    "block_message": "",
    "enabled": true,
    "block_when_engine_unavailable": false,
    "silent_block": false
  };

axios.post("https://api.maiagent.ai/api/v1/hooks/", 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/hooks/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "template_id": "00000000-0000-0000-0000-000000000001",
    "name": "Customer PII Redaction",
    "description": "Mask phone numbers and emails in inbound messages.",
    "config": {
        "data": {
            "patterns": [
                "phone",
                "email"
            ],
            "mode": "mask"
        }
    },
    "block_message": "",
    "enabled": True,
    "block_when_engine_unavailable": False,
    "silent_block": False
}

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/hooks/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'template_id' => '00000000-0000-0000-0000-000000000001',
            'name' => 'Customer PII Redaction',
            'description' => 'Mask phone numbers and emails in inbound messages.',
            'config' => [
                'data' => [
                    'patterns' => [
                        'phone',
                        'email'
                    ],
                    'mode' => 'mask'
                ]
            ],
            'block_message' => '',
            'enabled' => true,
            'block_when_engine_unavailable' => false,
            'silent_block' => false
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "organization": string (uuid)
  "templateId": string (uuid)
  "templateName": string
  "templateTypeLabel": string
  "scope": string
  "name": string
  "description": string
  "triggerPoint": string
  "action": string
  "handlerType": string
  "mintsAliases": boolean
  "config": object
  "blockMessage": string
  "enabled": boolean
  "blockWhenEngineUnavailable": boolean // Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the original text is not stored either; the AI assistant cannot reply until the engine is back. Off (default): the message goes on without this hook. Once the engine is set up, a hook that cannot start or fails while running always blocks the message, whatever this setting says. Has no effect on hooks that run after the reply.
  "silentBlock": boolean // Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (default): the block message is sent as the reply. Takes effect only while the silent block switch is on in system config.
  "createdBy": object
  "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched
``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1.
    object
  ]
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "templateName": "回應字串",
  "templateTypeLabel": "回應字串",
  "scope": "回應字串",
  "name": "回應字串",
  "description": "回應字串",
  "triggerPoint": "回應字串",
  "action": "回應字串",
  "handlerType": "回應字串",
  "mintsAliases": false,
  "config": null,
  "blockMessage": "回應字串",
  "enabled": false,
  "blockWhenEngineUnavailable": false,
  "silentBlock": false,
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 取得特定 Hook <a href="#hooks-retrieve" id="hooks-retrieve"></a>

GET `/api/v1/hooks/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/hooks/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/hooks/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/hooks/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/hooks/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)
  "organization": string (uuid)
  "templateId": string (uuid)
  "templateName": string
  "templateTypeLabel": string
  "scope": string
  "name": string
  "description": string
  "triggerPoint": string
  "action": string
  "handlerType": string
  "mintsAliases": boolean
  "config": object
  "blockMessage": string
  "enabled": boolean
  "blockWhenEngineUnavailable": boolean // Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the original text is not stored either; the AI assistant cannot reply until the engine is back. Off (default): the message goes on without this hook. Once the engine is set up, a hook that cannot start or fails while running always blocks the message, whatever this setting says. Has no effect on hooks that run after the reply.
  "silentBlock": boolean // Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (default): the block message is sent as the reply. Takes effect only while the silent block switch is on in system config.
  "createdBy": object
  "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched
``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1.
    object
  ]
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "templateName": "回應字串",
  "templateTypeLabel": "回應字串",
  "scope": "回應字串",
  "name": "回應字串",
  "description": "回應字串",
  "triggerPoint": "回應字串",
  "action": "回應字串",
  "handlerType": "回應字串",
  "mintsAliases": false,
  "config": null,
  "blockMessage": "回應字串",
  "enabled": false,
  "blockWhenEngineUnavailable": false,
  "silentBlock": false,
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 部分更新 Hook <a href="#hooks-partial-update" id="hooks-partial-update"></a>

PATCH `/api/v1/hooks/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                         | 類型      | 必填 | 說明                                                                                                                                                                                                          |
| -------------------------- | ------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                       | string  | 否  |                                                                                                                                                                                                             |
| description                | string  | 否  |                                                                                                                                                                                                             |
| config                     | object  | 否  |                                                                                                                                                                                                             |
| blockMessage               | string  | 否  |                                                                                                                                                                                                             |
| enabled                    | boolean | 否  |                                                                                                                                                                                                             |
| blockWhenEngineUnavailable | boolean | 否  | Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the... |
| silentBlock                | boolean | 否  | Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (d... |

**請求結構範例**

```typescript
{
  "name"?: string // 非必填
  "description"?: string // 非必填
  "config"?: object // 非必填
  "blockMessage"?: string // 非必填
  "enabled"?: boolean // 非必填
  "blockWhenEngineUnavailable"?: boolean // Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the original text is not stored either; the AI assistant cannot reply until the engine is back. Off (default): the message goes on without this hook. Once the engine is set up, a hook that cannot start or fails while running always blocks the message, whatever this setting says. Has no effect on hooks that run after the reply. (非必填)
  "silentBlock"?: boolean // Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (default): the block message is sent as the reply. Takes effect only while the silent block switch is on in system config. (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "description": "範例字串",
  "config": null,
  "blockMessage": "範例字串",
  "enabled": true,
  "blockWhenEngineUnavailable": true,
  "silentBlock": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串",
    "config": null,
    "blockMessage": "範例字串",
    "enabled": true,
    "blockWhenEngineUnavailable": true,
    "silentBlock": true
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱",
    "description": "範例字串",
    "config": null,
    "blockMessage": "範例字串",
    "enabled": true,
    "blockWhenEngineUnavailable": true,
    "silentBlock": true
  };

axios.patch("https://api.maiagent.ai/api/v1/hooks/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/hooks/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串",
    "config": None,
    "blockMessage": "範例字串",
    "enabled": True,
    "blockWhenEngineUnavailable": True,
    "silentBlock": True
}

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/hooks/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串',
            'config' => null,
            'blockMessage' => '範例字串',
            'enabled' => true,
            'blockWhenEngineUnavailable' => true,
            'silentBlock' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "organization": string (uuid)
  "templateId": string (uuid)
  "templateName": string
  "templateTypeLabel": string
  "scope": string
  "name": string
  "description": string
  "triggerPoint": string
  "action": string
  "handlerType": string
  "mintsAliases": boolean
  "config": object
  "blockMessage": string
  "enabled": boolean
  "blockWhenEngineUnavailable": boolean // Applies when the hook engine cannot be set up for a message (for example, its sandbox backend cannot be reached). On: the message is blocked with a safety notice, and for a hook that rewrites text the original text is not stored either; the AI assistant cannot reply until the engine is back. Off (default): the message goes on without this hook. Once the engine is set up, a hook that cannot start or fails while running always blocks the message, whatever this setting says. Has no effect on hooks that run after the reply.
  "silentBlock": boolean // Applies only to hooks that check user input and block it. On: a blocked user message gets no reply on any channel, and internal chat and the hook execution log still show which hook blocked it. Off (default): the block message is sent as the reply. Takes effect only while the silent block switch is on in system config.
  "createdBy": object
  "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched
``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1.
    object
  ]
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "templateName": "回應字串",
  "templateTypeLabel": "回應字串",
  "scope": "回應字串",
  "name": "回應字串",
  "description": "回應字串",
  "triggerPoint": "回應字串",
  "action": "回應字串",
  "handlerType": "回應字串",
  "mintsAliases": false,
  "config": null,
  "blockMessage": "回應字串",
  "enabled": false,
  "blockWhenEngineUnavailable": false,
  "silentBlock": false,
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 刪除 Hook <a href="#hooks-destroy" id="hooks-destroy"></a>

DELETE `/api/v1/hooks/{id}/`

#### 參數

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

#### 程式碼範例

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/hooks/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/hooks/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(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->delete("https://api.maiagent.ai/api/v1/hooks/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 %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 列出 AI 助理掛載的 Hook <a href="#chatbots-hooks-retrieve" id="chatbots-hooks-retrieve"></a>

GET `/api/v1/chatbots/{chatbotId}/hooks/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/" \
  -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/hooks/", 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/hooks/"
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/hooks/", [
        '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
{
  "results": [
    {
      "id": string (uuid)
      "name": string
      "scope": string
      "templateName": string
      "templateTypeLabel": string
      "triggerPoint": string
      "action": string
      "enabled": boolean
      "order": integer
      "inputScope": 
      {
      }
    }
  ]
}
```

**回應範例值**

```json
{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "scope": "回應字串",
      "templateName": "回應字串",
      "templateTypeLabel": "回應字串",
      "triggerPoint": "回應字串",
      "action": "回應字串",
      "enabled": false,
      "order": 456,
      "inputScope": {}
    }
  ]
}
```

***

### 整批替換 AI 助理掛載的 Hook <a href="#chatbots-hooks-update" id="chatbots-hooks-update"></a>

PUT `/api/v1/chatbots/{chatbotId}/hooks/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位      | 類型             | 必填 | 說明 |
| ------- | -------------- | -- | -- |
| hookIds | array\[string] | 是  |    |

**請求結構範例**

```typescript
{
  "hookIds": [
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "hookIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hookIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 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 = {
    "hookIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

axios.put("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/", 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/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "hookIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

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/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'hookIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "results": [
    {
      "id": string (uuid)
      "name": string
      "scope": string
      "templateName": string
      "templateTypeLabel": string
      "triggerPoint": string
      "action": string
      "enabled": boolean
      "order": integer
      "inputScope": 
      {
      }
    }
  ]
}
```

**回應範例值**

```json
{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "scope": "回應字串",
      "templateName": "回應字串",
      "templateTypeLabel": "回應字串",
      "triggerPoint": "回應字串",
      "action": "回應字串",
      "enabled": false,
      "order": 456,
      "inputScope": {}
    }
  ]
}
```

***

### 列出排程 <a href="#schedules-list" id="schedules-list"></a>

GET `/api/v1/schedules/`

{% hint style="info" %}
排程會在指定時間以 AI 助理執行一段指令；建立時系統自動配置專用的聯絡人與對話。
{% endhint %}

#### 參數

| 參數名稱       | 必填 | 類型      | 說明                                             |
| ---------- | -- | ------- | ---------------------------------------------- |
| `page`     | ❌  | integer | A page number within the paginated result set. |
| `pageSize` | ❌  | integer | Number of results to return per page.          |
| `search`   | ❌  | string  | A search term.                                 |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/schedules/?page=1&pageSize=1&search=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/schedules/?page=1&pageSize=1&search=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/schedules/?page=1&pageSize=1&search=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/schedules/?page=1&pageSize=1&search=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
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string
      "prompt": string
      "chatbot": string (uuid)
      "chatbotName": string
      "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context
* `isolated` - Isolated
      "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot
      "cronExpression"?: string // 非必填
      "intervalSeconds"?: integer // 非必填
      "oneShotAt"?: string (timestamp) // 非必填
      "deliveryConversationIds"?: [ // 非必填
        string (uuid)
      ]
      "deliveryWebhookUrls"?: [ // 非必填
        string (uri)
      ]
      "deliveryCondition": string // When set, each run delivers only if the agent judges this condition met; blank delivers every run.
      "saveResultToContext"?: boolean // 非必填
      "enabled"?: boolean // 非必填
      "lastExecutedAt"?: string (timestamp) // 非必填
      "executionCount"?: integer // 非必填
      "maxExecutions"?: integer // 非必填
      "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
      "countsTowardLimit": boolean
      "runAs": 
      {
        "id": string (uuid)
        "name": string
        "status": 
        {
        }
      }
      "createdAt": string (timestamp)
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "prompt": "回應字串",
      "chatbot": "550e8400-e29b-41d4-a716-446655440000",
      "chatbotName": "回應字串",
      "executionMode": "in_context",
      "scheduleType": "cron",
      "cronExpression": "回應字串",
      "intervalSeconds": 456,
      "oneShotAt": "回應字串",
      "deliveryConversationIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ],
      "deliveryWebhookUrls": [
        "https://example.com/file.jpg"
      ],
      "deliveryCondition": "回應字串",
      "saveResultToContext": false,
      "enabled": false,
      "lastExecutedAt": "回應字串",
      "executionCount": 456,
      "maxExecutions": 456,
      "endDate": "回應字串",
      "countsTowardLimit": false,
      "runAs": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "status": {}
      },
      "createdAt": "回應字串"
    }
  ]
}
```

**狀態碼: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 建立排程 <a href="#schedules-create" id="schedules-create"></a>

POST `/api/v1/schedules/`

#### 請求內容

**請求參數**

| 欄位                      | 類型                                       | 必填 | 說明                                                                                                                                                                                                          |
| ----------------------- | ---------------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| chatbot                 | string (uuid)                            | 是  |                                                                                                                                                                                                             |
| name                    | string                                   | 是  |                                                                                                                                                                                                             |
| executionMode           | string (enum: in\_context, isolated)     | 是  | `in_context`: In Context ; `isolated`: Isolated;                                                                                                                                                            |
| prompt                  | string                                   | 是  |                                                                                                                                                                                                             |
| contextVariables        | object                                   | 否  |                                                                                                                                                                                                             |
| inbox                   | string (uuid)                            | 是  |                                                                                                                                                                                                             |
| saveResultToContext     | boolean                                  | 否  |                                                                                                                                                                                                             |
| deliveryConversationIds | array\[string]                           | 否  |                                                                                                                                                                                                             |
| deliveryWebhookUrls     | array\[string]                           | 否  |                                                                                                                                                                                                             |
| deliveryCondition       | string                                   | 否  | When set, each run delivers only if the agent judges this condition met; blank delivers every run.                                                                                                          |
| scheduleType            | string (enum: cron, interval, one\_shot) | 是  | `cron`: Cron ; `interval`: Interval ; `one_shot`: One Shot;                                                                                                                                                 |
| cronExpression          | string                                   | 否  |                                                                                                                                                                                                             |
| intervalSeconds         | integer                                  | 否  |                                                                                                                                                                                                             |
| oneShotAt               | string (timestamp)                       | 否  |                                                                                                                                                                                                             |
| timezone                | string                                   | 否  |                                                                                                                                                                                                             |
| enabled                 | boolean                                  | 否  |                                                                                                                                                                                                             |
| maxExecutions           | integer                                  | 否  |                                                                                                                                                                                                             |
| endDate                 | string (date)                            | 否  | Last day the schedule runs, in its own timezone; the first run due after that day turns it off.                                                                                                             |
| confirmRunAsChange      | boolean                                  | 否  | Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by to... |

**請求結構範例**

```typescript
{
  "chatbot": string (uuid)
  "name": string
  "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context
* `isolated` - Isolated
  "prompt": string
  "contextVariables"?: object // 非必填
  "inbox": string (uuid)
  "saveResultToContext"?: boolean // 非必填
  "deliveryConversationIds"?: [ // 非必填
    string (uuid)
  ]
  "deliveryWebhookUrls"?: [ // 非必填
    string (uri)
  ]
  "deliveryCondition"?: string // When set, each run delivers only if the agent judges this condition met; blank delivers every run. (非必填)
  "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot
  "cronExpression"?: string // 非必填
  "intervalSeconds"?: integer // 非必填
  "oneShotAt"?: string (timestamp) // 非必填
  "timezone"?: string // 非必填
  "enabled"?: boolean // 非必填
  "maxExecutions"?: integer // 非必填
  "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
  "confirmRunAsChange"?: boolean // Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by toggle when it turns on a schedule whose run-as member no longer has access. (非必填)
}
```

**請求範例值**

```json
{
  "chatbot": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "executionMode": "in_context",
  "prompt": "範例字串",
  "contextVariables": null,
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "saveResultToContext": true,
  "deliveryConversationIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "deliveryWebhookUrls": [
    "https://example.com/file.jpg"
  ],
  "deliveryCondition": "範例字串",
  "scheduleType": "cron",
  "cronExpression": "範例字串",
  "intervalSeconds": 123,
  "oneShotAt": "範例字串",
  "timezone": "範例字串",
  "enabled": true,
  "maxExecutions": 123,
  "endDate": "範例字串",
  "confirmRunAsChange": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/schedules/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "executionMode": "in_context",
    "prompt": "範例字串",
    "contextVariables": null,
    "inbox": "550e8400-e29b-41d4-a716-446655440000",
    "saveResultToContext": true,
    "deliveryConversationIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
      "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": true,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "confirmRunAsChange": true
  }'

# 請確認在執行前替換 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 = {
    "chatbot": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "executionMode": "in_context",
    "prompt": "範例字串",
    "contextVariables": null,
    "inbox": "550e8400-e29b-41d4-a716-446655440000",
    "saveResultToContext": true,
    "deliveryConversationIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
      "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": true,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "confirmRunAsChange": true
  };

axios.post("https://api.maiagent.ai/api/v1/schedules/", 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/schedules/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "chatbot": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "executionMode": "in_context",
    "prompt": "範例字串",
    "contextVariables": None,
    "inbox": "550e8400-e29b-41d4-a716-446655440000",
    "saveResultToContext": True,
    "deliveryConversationIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
        "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": True,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "confirmRunAsChange": True
}

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/schedules/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'chatbot' => '550e8400-e29b-41d4-a716-446655440000',
            'name' => '範例名稱',
            'executionMode' => 'in_context',
            'prompt' => '範例字串',
            'contextVariables' => null,
            'inbox' => '550e8400-e29b-41d4-a716-446655440000',
            'saveResultToContext' => true,
            'deliveryConversationIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'deliveryWebhookUrls' => [
                'https://example.com/file.jpg'
            ],
            'deliveryCondition' => '範例字串',
            'scheduleType' => 'cron',
            'cronExpression' => '範例字串',
            'intervalSeconds' => 123,
            'oneShotAt' => '範例字串',
            'timezone' => '範例字串',
            'enabled' => true,
            'maxExecutions' => 123,
            'endDate' => '範例字串',
            'confirmRunAsChange' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "chatbot": string (uuid)
  "organization": string (uuid)
  "name": string
  "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context
* `isolated` - Isolated
  "prompt": string
  "contextVariables"?: object // 非必填
  "inbox": string (uuid)
  "saveResultToContext"?: boolean // 非必填
  "dedicatedContact": string (uuid)
  "dedicatedConversation": string (uuid)
  "deliveryConversationIds"?: [ // 非必填
    string (uuid)
  ]
  "deliveryWebhookUrls"?: [ // 非必填
    string (uri)
  ]
  "deliveryCondition"?: string // When set, each run delivers only if the agent judges this condition met; blank delivers every run. (非必填)
  "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot
  "cronExpression"?: string // 非必填
  "intervalSeconds"?: integer // 非必填
  "oneShotAt"?: string (timestamp) // 非必填
  "timezone"?: string // 非必填
  "periodicTask": integer
  "enabled"?: boolean // 非必填
  "lastExecutedAt": string (timestamp)
  "executionCount": integer
  "maxExecutions"?: integer // 非必填
  "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
  "countsTowardLimit": boolean
  "webhookAvailable": boolean
  "webhookEnabled": boolean // When on, and Unattended Mode is on site-wide, an external system runs this schedule once per POST to its webhook URL. Turning it off stops the URL at once; turning it on again gives a new URL.
  "webhookAcceptsExternalText": boolean // When on, a webhook call may add up to 4,000 characters after the prompt. That text reaches the model, and the assistant's API, MCP and other tools may write data because of it; turn it on only when the sender is trusted. When off, a call that adds text is refused.
  "webhookUrl": string
  "runAs": 
  {
    "id": string (uuid)
    "name": string
    "status": 
    {
    }
  }
  "runsAsMember": boolean
  "confirmRunAsChange"?: boolean // Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by toggle when it turns on a schedule whose run-as member no longer has access. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbot": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "executionMode": "in_context",
  "prompt": "回應字串",
  "contextVariables": null,
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "saveResultToContext": false,
  "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000",
  "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000",
  "deliveryConversationIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "deliveryWebhookUrls": [
    "https://example.com/file.jpg"
  ],
  "deliveryCondition": "回應字串",
  "scheduleType": "cron",
  "cronExpression": "回應字串",
  "intervalSeconds": 456,
  "oneShotAt": "回應字串",
  "timezone": "回應字串",
  "periodicTask": 456,
  "enabled": false,
  "lastExecutedAt": "回應字串",
  "executionCount": 456,
  "maxExecutions": 456,
  "endDate": "回應字串",
  "countsTowardLimit": false,
  "webhookAvailable": false,
  "webhookEnabled": false,
  "webhookAcceptsExternalText": false,
  "webhookUrl": "回應字串",
  "runAs": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "status": {}
  },
  "runsAsMember": false,
  "confirmRunAsChange": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

**狀態碼: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 取得特定排程 <a href="#schedules-retrieve" id="schedules-retrieve"></a>

GET `/api/v1/schedules/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/schedules/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/schedules/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/schedules/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/schedules/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)
  "chatbot": string (uuid)
  "organization": string (uuid)
  "name": string
  "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context
* `isolated` - Isolated
  "prompt": string
  "contextVariables"?: object // 非必填
  "inbox": string (uuid)
  "saveResultToContext"?: boolean // 非必填
  "dedicatedContact": string (uuid)
  "dedicatedConversation": string (uuid)
  "deliveryConversationIds"?: [ // 非必填
    string (uuid)
  ]
  "deliveryWebhookUrls"?: [ // 非必填
    string (uri)
  ]
  "deliveryCondition"?: string // When set, each run delivers only if the agent judges this condition met; blank delivers every run. (非必填)
  "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot
  "cronExpression"?: string // 非必填
  "intervalSeconds"?: integer // 非必填
  "oneShotAt"?: string (timestamp) // 非必填
  "timezone"?: string // 非必填
  "periodicTask": integer
  "enabled"?: boolean // 非必填
  "lastExecutedAt": string (timestamp)
  "executionCount": integer
  "maxExecutions"?: integer // 非必填
  "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
  "countsTowardLimit": boolean
  "webhookAvailable": boolean
  "webhookEnabled": boolean // When on, and Unattended Mode is on site-wide, an external system runs this schedule once per POST to its webhook URL. Turning it off stops the URL at once; turning it on again gives a new URL.
  "webhookAcceptsExternalText": boolean // When on, a webhook call may add up to 4,000 characters after the prompt. That text reaches the model, and the assistant's API, MCP and other tools may write data because of it; turn it on only when the sender is trusted. When off, a call that adds text is refused.
  "webhookUrl": string
  "runAs": 
  {
    "id": string (uuid)
    "name": string
    "status": 
    {
    }
  }
  "runsAsMember": boolean
  "confirmRunAsChange"?: boolean // Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by toggle when it turns on a schedule whose run-as member no longer has access. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbot": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "executionMode": "in_context",
  "prompt": "回應字串",
  "contextVariables": null,
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "saveResultToContext": false,
  "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000",
  "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000",
  "deliveryConversationIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "deliveryWebhookUrls": [
    "https://example.com/file.jpg"
  ],
  "deliveryCondition": "回應字串",
  "scheduleType": "cron",
  "cronExpression": "回應字串",
  "intervalSeconds": 456,
  "oneShotAt": "回應字串",
  "timezone": "回應字串",
  "periodicTask": 456,
  "enabled": false,
  "lastExecutedAt": "回應字串",
  "executionCount": 456,
  "maxExecutions": 456,
  "endDate": "回應字串",
  "countsTowardLimit": false,
  "webhookAvailable": false,
  "webhookEnabled": false,
  "webhookAcceptsExternalText": false,
  "webhookUrl": "回應字串",
  "runAs": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "status": {}
  },
  "runsAsMember": false,
  "confirmRunAsChange": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

**狀態碼: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 部分更新排程 <a href="#schedules-partial-update" id="schedules-partial-update"></a>

PATCH `/api/v1/schedules/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                         | 類型                                       | 必填 | 說明                                                                                                                                                                                                          |
| -------------------------- | ---------------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                       | string                                   | 否  |                                                                                                                                                                                                             |
| prompt                     | string                                   | 否  |                                                                                                                                                                                                             |
| contextVariables           | object                                   | 否  |                                                                                                                                                                                                             |
| saveResultToContext        | boolean                                  | 否  |                                                                                                                                                                                                             |
| deliveryConversationIds    | array\[string]                           | 否  |                                                                                                                                                                                                             |
| deliveryWebhookUrls        | array\[string]                           | 否  |                                                                                                                                                                                                             |
| deliveryCondition          | string                                   | 否  | When set, each run delivers only if the agent judges this condition met; blank delivers every run.                                                                                                          |
| scheduleType               | string (enum: cron, interval, one\_shot) | 否  | `cron`: Cron ; `interval`: Interval ; `one_shot`: One Shot;                                                                                                                                                 |
| cronExpression             | string                                   | 否  |                                                                                                                                                                                                             |
| intervalSeconds            | integer                                  | 否  |                                                                                                                                                                                                             |
| oneShotAt                  | string (timestamp)                       | 否  |                                                                                                                                                                                                             |
| timezone                   | string                                   | 否  |                                                                                                                                                                                                             |
| enabled                    | boolean                                  | 否  |                                                                                                                                                                                                             |
| maxExecutions              | integer                                  | 否  |                                                                                                                                                                                                             |
| endDate                    | string (date)                            | 否  | Last day the schedule runs, in its own timezone; the first run due after that day turns it off.                                                                                                             |
| webhookEnabled             | boolean                                  | 否  | When on, and Unattended Mode is on site-wide, an external system runs this schedule once per POST to its webhook URL. Turning it off stops the URL at once; turning it on again gives a new URL.            |
| webhookAcceptsExternalText | boolean                                  | 否  | When on, a webhook call may add up to 4,000 characters after the prompt. That text reaches the model, and the assistant's API, MCP and other tools may write data because of it; turn it on only when th... |
| confirmRunAsChange         | boolean                                  | 否  | Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by to... |

**請求結構範例**

```typescript
{
  "name"?: string // 非必填
  "prompt"?: string // 非必填
  "contextVariables"?: object // 非必填
  "saveResultToContext"?: boolean // 非必填
  "deliveryConversationIds"?: [ // 非必填
    string (uuid)
  ]
  "deliveryWebhookUrls"?: [ // 非必填
    string (uri)
  ]
  "deliveryCondition"?: string // When set, each run delivers only if the agent judges this condition met; blank delivers every run. (非必填)
  "scheduleType"?: string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot (非必填)
  "cronExpression"?: string // 非必填
  "intervalSeconds"?: integer // 非必填
  "oneShotAt"?: string (timestamp) // 非必填
  "timezone"?: string // 非必填
  "enabled"?: boolean // 非必填
  "maxExecutions"?: integer // 非必填
  "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
  "webhookEnabled"?: boolean // When on, and Unattended Mode is on site-wide, an external system runs this schedule once per POST to its webhook URL. Turning it off stops the URL at once; turning it on again gives a new URL. (非必填)
  "webhookAcceptsExternalText"?: boolean // When on, a webhook call may add up to 4,000 characters after the prompt. That text reaches the model, and the assistant's API, MCP and other tools may write data because of it; turn it on only when the sender is trusted. When off, a call that adds text is refused. (非必填)
  "confirmRunAsChange"?: boolean // Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by toggle when it turns on a schedule whose run-as member no longer has access. (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "prompt": "範例字串",
  "contextVariables": null,
  "saveResultToContext": true,
  "deliveryConversationIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "deliveryWebhookUrls": [
    "https://example.com/file.jpg"
  ],
  "deliveryCondition": "範例字串",
  "scheduleType": "cron",
  "cronExpression": "範例字串",
  "intervalSeconds": 123,
  "oneShotAt": "範例字串",
  "timezone": "範例字串",
  "enabled": true,
  "maxExecutions": 123,
  "endDate": "範例字串",
  "webhookEnabled": true,
  "webhookAcceptsExternalText": true,
  "confirmRunAsChange": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "prompt": "範例字串",
    "contextVariables": null,
    "saveResultToContext": true,
    "deliveryConversationIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
      "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": true,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "webhookEnabled": true,
    "webhookAcceptsExternalText": true,
    "confirmRunAsChange": true
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱",
    "prompt": "範例字串",
    "contextVariables": null,
    "saveResultToContext": true,
    "deliveryConversationIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
      "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": true,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "webhookEnabled": true,
    "webhookAcceptsExternalText": true,
    "confirmRunAsChange": true
  };

axios.patch("https://api.maiagent.ai/api/v1/schedules/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/schedules/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "prompt": "範例字串",
    "contextVariables": None,
    "saveResultToContext": True,
    "deliveryConversationIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
        "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": True,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "webhookEnabled": True,
    "webhookAcceptsExternalText": True,
    "confirmRunAsChange": True
}

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/schedules/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'prompt' => '範例字串',
            'contextVariables' => null,
            'saveResultToContext' => true,
            'deliveryConversationIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'deliveryWebhookUrls' => [
                'https://example.com/file.jpg'
            ],
            'deliveryCondition' => '範例字串',
            'scheduleType' => 'cron',
            'cronExpression' => '範例字串',
            'intervalSeconds' => 123,
            'oneShotAt' => '範例字串',
            'timezone' => '範例字串',
            'enabled' => true,
            'maxExecutions' => 123,
            'endDate' => '範例字串',
            'webhookEnabled' => true,
            'webhookAcceptsExternalText' => true,
            'confirmRunAsChange' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "chatbot": string (uuid)
  "organization": string (uuid)
  "name": string
  "executionMode": 
  {
  }
  "prompt": string
  "contextVariables"?: object // 非必填
  "inbox": string (uuid)
  "saveResultToContext"?: boolean // 非必填
  "dedicatedContact": string (uuid)
  "dedicatedConversation": string (uuid)
  "deliveryConversationIds"?: [ // 非必填
    string (uuid)
  ]
  "deliveryWebhookUrls"?: [ // 非必填
    string (uri)
  ]
  "deliveryCondition"?: string // When set, each run delivers only if the agent judges this condition met; blank delivers every run. (非必填)
  "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot
  "cronExpression"?: string // 非必填
  "intervalSeconds"?: integer // 非必填
  "oneShotAt"?: string (timestamp) // 非必填
  "timezone"?: string // 非必填
  "periodicTask": integer
  "enabled"?: boolean // 非必填
  "lastExecutedAt": string (timestamp)
  "executionCount": integer
  "maxExecutions"?: integer // 非必填
  "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
  "countsTowardLimit": boolean
  "webhookAvailable": boolean
  "webhookEnabled"?: boolean // When on, and Unattended Mode is on site-wide, an external system runs this schedule once per POST to its webhook URL. Turning it off stops the URL at once; turning it on again gives a new URL. (非必填)
  "webhookAcceptsExternalText"?: boolean // When on, a webhook call may add up to 4,000 characters after the prompt. That text reaches the model, and the assistant's API, MCP and other tools may write data because of it; turn it on only when the sender is trusted. When off, a call that adds text is refused. (非必填)
  "webhookUrl": string
  "runAs": 
  {
    "id": string (uuid)
    "name": string
    "status": 
    {
    }
  }
  "runsAsMember": boolean
  "confirmRunAsChange"?: boolean // Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by toggle when it turns on a schedule whose run-as member no longer has access. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbot": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "executionMode": {},
  "prompt": "回應字串",
  "contextVariables": null,
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "saveResultToContext": false,
  "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000",
  "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000",
  "deliveryConversationIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "deliveryWebhookUrls": [
    "https://example.com/file.jpg"
  ],
  "deliveryCondition": "回應字串",
  "scheduleType": "cron",
  "cronExpression": "回應字串",
  "intervalSeconds": 456,
  "oneShotAt": "回應字串",
  "timezone": "回應字串",
  "periodicTask": 456,
  "enabled": false,
  "lastExecutedAt": "回應字串",
  "executionCount": 456,
  "maxExecutions": 456,
  "endDate": "回應字串",
  "countsTowardLimit": false,
  "webhookAvailable": false,
  "webhookEnabled": false,
  "webhookAcceptsExternalText": false,
  "webhookUrl": "回應字串",
  "runAs": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "status": {}
  },
  "runsAsMember": false,
  "confirmRunAsChange": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

**狀態碼: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 刪除排程 <a href="#schedules-destroy" id="schedules-destroy"></a>

DELETE `/api/v1/schedules/{id}/`

#### 參數

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

#### 程式碼範例

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/schedules/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/schedules/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(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->delete("https://api.maiagent.ai/api/v1/schedules/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 %}

#### 回應內容

| 狀態碼 | 說明                                                                 |
| --- | ------------------------------------------------------------------ |
| 204 | No response body                                                   |
| 4XX | Error response; X-Error-Code carries its code (see "Error codes"). |

***

### 立即執行排程 <a href="#schedules-run-now-create" id="schedules-run-now-create"></a>

POST `/api/v1/schedules/{id}/run-now/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                      | 類型                                       | 必填 | 說明                                                                                                                                                                                                          |
| ----------------------- | ---------------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| chatbot                 | string (uuid)                            | 是  |                                                                                                                                                                                                             |
| name                    | string                                   | 是  |                                                                                                                                                                                                             |
| executionMode           | string (enum: in\_context, isolated)     | 是  | `in_context`: In Context ; `isolated`: Isolated;                                                                                                                                                            |
| prompt                  | string                                   | 是  |                                                                                                                                                                                                             |
| contextVariables        | object                                   | 否  |                                                                                                                                                                                                             |
| inbox                   | string (uuid)                            | 是  |                                                                                                                                                                                                             |
| saveResultToContext     | boolean                                  | 否  |                                                                                                                                                                                                             |
| deliveryConversationIds | array\[string]                           | 否  |                                                                                                                                                                                                             |
| deliveryWebhookUrls     | array\[string]                           | 否  |                                                                                                                                                                                                             |
| deliveryCondition       | string                                   | 否  | When set, each run delivers only if the agent judges this condition met; blank delivers every run.                                                                                                          |
| scheduleType            | string (enum: cron, interval, one\_shot) | 是  | `cron`: Cron ; `interval`: Interval ; `one_shot`: One Shot;                                                                                                                                                 |
| cronExpression          | string                                   | 否  |                                                                                                                                                                                                             |
| intervalSeconds         | integer                                  | 否  |                                                                                                                                                                                                             |
| oneShotAt               | string (timestamp)                       | 否  |                                                                                                                                                                                                             |
| timezone                | string                                   | 否  |                                                                                                                                                                                                             |
| enabled                 | boolean                                  | 否  |                                                                                                                                                                                                             |
| maxExecutions           | integer                                  | 否  |                                                                                                                                                                                                             |
| endDate                 | string (date)                            | 否  | Last day the schedule runs, in its own timezone; the first run due after that day turns it off.                                                                                                             |
| confirmRunAsChange      | boolean                                  | 否  | Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by to... |

**請求結構範例**

```typescript
{
  "chatbot": string (uuid)
  "name": string
  "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context
* `isolated` - Isolated
  "prompt": string
  "contextVariables"?: object // 非必填
  "inbox": string (uuid)
  "saveResultToContext"?: boolean // 非必填
  "deliveryConversationIds"?: [ // 非必填
    string (uuid)
  ]
  "deliveryWebhookUrls"?: [ // 非必填
    string (uri)
  ]
  "deliveryCondition"?: string // When set, each run delivers only if the agent judges this condition met; blank delivers every run. (非必填)
  "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot
  "cronExpression"?: string // 非必填
  "intervalSeconds"?: integer // 非必填
  "oneShotAt"?: string (timestamp) // 非必填
  "timezone"?: string // 非必填
  "enabled"?: boolean // 非必填
  "maxExecutions"?: integer // 非必填
  "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
  "confirmRunAsChange"?: boolean // Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by toggle when it turns on a schedule whose run-as member no longer has access. (非必填)
}
```

**請求範例值**

```json
{
  "chatbot": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "executionMode": "in_context",
  "prompt": "範例字串",
  "contextVariables": null,
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "saveResultToContext": true,
  "deliveryConversationIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "deliveryWebhookUrls": [
    "https://example.com/file.jpg"
  ],
  "deliveryCondition": "範例字串",
  "scheduleType": "cron",
  "cronExpression": "範例字串",
  "intervalSeconds": 123,
  "oneShotAt": "範例字串",
  "timezone": "範例字串",
  "enabled": true,
  "maxExecutions": 123,
  "endDate": "範例字串",
  "confirmRunAsChange": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "executionMode": "in_context",
    "prompt": "範例字串",
    "contextVariables": null,
    "inbox": "550e8400-e29b-41d4-a716-446655440000",
    "saveResultToContext": true,
    "deliveryConversationIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
      "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": true,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "confirmRunAsChange": true
  }'

# 請確認在執行前替換 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 = {
    "chatbot": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "executionMode": "in_context",
    "prompt": "範例字串",
    "contextVariables": null,
    "inbox": "550e8400-e29b-41d4-a716-446655440000",
    "saveResultToContext": true,
    "deliveryConversationIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
      "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": true,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "confirmRunAsChange": true
  };

axios.post("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/", 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/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "chatbot": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "executionMode": "in_context",
    "prompt": "範例字串",
    "contextVariables": None,
    "inbox": "550e8400-e29b-41d4-a716-446655440000",
    "saveResultToContext": True,
    "deliveryConversationIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deliveryWebhookUrls": [
        "https://example.com/file.jpg"
    ],
    "deliveryCondition": "範例字串",
    "scheduleType": "cron",
    "cronExpression": "範例字串",
    "intervalSeconds": 123,
    "oneShotAt": "範例字串",
    "timezone": "範例字串",
    "enabled": True,
    "maxExecutions": 123,
    "endDate": "範例字串",
    "confirmRunAsChange": True
}

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/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'chatbot' => '550e8400-e29b-41d4-a716-446655440000',
            'name' => '範例名稱',
            'executionMode' => 'in_context',
            'prompt' => '範例字串',
            'contextVariables' => null,
            'inbox' => '550e8400-e29b-41d4-a716-446655440000',
            'saveResultToContext' => true,
            'deliveryConversationIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'deliveryWebhookUrls' => [
                'https://example.com/file.jpg'
            ],
            'deliveryCondition' => '範例字串',
            'scheduleType' => 'cron',
            'cronExpression' => '範例字串',
            'intervalSeconds' => 123,
            'oneShotAt' => '範例字串',
            'timezone' => '範例字串',
            'enabled' => true,
            'maxExecutions' => 123,
            'endDate' => '範例字串',
            'confirmRunAsChange' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 202**

**回應結構範例**

```typescript
{
  "status"?: string // 非必填
}
```

**回應範例值**

```json
{
  "status": "scheduled"
}
```

**狀態碼: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 啟用或停用排程 <a href="#schedules-toggle-create" id="schedules-toggle-create"></a>

POST `/api/v1/schedules/{id}/toggle/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                 | 類型      | 必填 | 說明 |
| ------------------ | ------- | -- | -- |
| confirmRunAsChange | boolean | 否  |    |

**請求結構範例**

```typescript
{
  "confirmRunAsChange"?: boolean // 非必填
}
```

**請求範例值**

```json
{
  "confirmRunAsChange": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmRunAsChange": true
  }'

# 請確認在執行前替換 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 = {
    "confirmRunAsChange": true
  };

axios.post("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/", 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/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "confirmRunAsChange": True
}

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/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'confirmRunAsChange' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "chatbot": string (uuid)
  "organization": string (uuid)
  "name": string
  "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context
* `isolated` - Isolated
  "prompt": string
  "contextVariables"?: object // 非必填
  "inbox": string (uuid)
  "saveResultToContext"?: boolean // 非必填
  "dedicatedContact": string (uuid)
  "dedicatedConversation": string (uuid)
  "deliveryConversationIds"?: [ // 非必填
    string (uuid)
  ]
  "deliveryWebhookUrls"?: [ // 非必填
    string (uri)
  ]
  "deliveryCondition"?: string // When set, each run delivers only if the agent judges this condition met; blank delivers every run. (非必填)
  "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron
* `interval` - Interval
* `one_shot` - One Shot
  "cronExpression"?: string // 非必填
  "intervalSeconds"?: integer // 非必填
  "oneShotAt"?: string (timestamp) // 非必填
  "timezone"?: string // 非必填
  "periodicTask": integer
  "enabled"?: boolean // 非必填
  "lastExecutedAt": string (timestamp)
  "executionCount": integer
  "maxExecutions"?: integer // 非必填
  "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (非必填)
  "countsTowardLimit": boolean
  "webhookAvailable": boolean
  "webhookEnabled": boolean // When on, and Unattended Mode is on site-wide, an external system runs this schedule once per POST to its webhook URL. Turning it off stops the URL at once; turning it on again gives a new URL.
  "webhookAcceptsExternalText": boolean // When on, a webhook call may add up to 4,000 characters after the prompt. That text reaches the model, and the assistant's API, MCP and other tools may write data because of it; turn it on only when the sender is trusted. When off, a call that adds text is refused.
  "webhookUrl": string
  "runAs": 
  {
    "id": string (uuid)
    "name": string
    "status": 
    {
    }
  }
  "runsAsMember": boolean
  "confirmRunAsChange"?: boolean // Send true once the member confirmed that saving makes the schedule run as them. Required when the organization runs schedules as their member and the schedule runs as someone else; also accepted by toggle when it turns on a schedule whose run-as member no longer has access. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbot": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "executionMode": "in_context",
  "prompt": "回應字串",
  "contextVariables": null,
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "saveResultToContext": false,
  "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000",
  "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000",
  "deliveryConversationIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "deliveryWebhookUrls": [
    "https://example.com/file.jpg"
  ],
  "deliveryCondition": "回應字串",
  "scheduleType": "cron",
  "cronExpression": "回應字串",
  "intervalSeconds": 456,
  "oneShotAt": "回應字串",
  "timezone": "回應字串",
  "periodicTask": 456,
  "enabled": false,
  "lastExecutedAt": "回應字串",
  "executionCount": 456,
  "maxExecutions": 456,
  "endDate": "回應字串",
  "countsTowardLimit": false,
  "webhookAvailable": false,
  "webhookEnabled": false,
  "webhookAcceptsExternalText": false,
  "webhookUrl": "回應字串",
  "runAs": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "status": {}
  },
  "runsAsMember": false,
  "confirmRunAsChange": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

**狀態碼: 400**

**回應結構範例**

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

**回應範例值**

```json
{
  "detail": "回應字串"
}
```

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

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

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

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

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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