> 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/ja/api-reference/ai-zhu-li.md).
# AI アシスタント
### 新しい AI アシスタントを作成
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 モデルを含みます） |
| 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`: 通常 ; `template`: テンプレート ; `hybrid`: ハイブリッド ; `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 | いいえ | 出力モード：テキスト、表、またはカスタム形式です `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`: 通常 ; `canvas`: キャンバス ; `team`: チーム; |
| numberOfRetrievedChunks | integer | いいえ | 取得する参考情報のチャンク数です。デフォルトは 12、最小値は 1 です |
| defaultLabelRelations | object | いいえ | アシスタントレベルのデフォルトのナレッジベースラベルフィルターです。形式は query\_metadata.label\_relations と同じで、null はフィルターなしを意味します。呼び出し側が query\_metadata を指定しない場合にのみ、優先順位が最も低いフォールバックとして適用されます。 |
| useFullRetrievalRange | boolean | いいえ | 有効にすると、LLM の top\_k による切り詰めを無視し、reranker の結果をすべて返します |
| 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 |
| 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... |
| customMaxLlmOutputTokens | integer | いいえ | LLM の最大出力トークン数をカスタマイズします。最小値は 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\_searching\_tool を通じてツールを動的に検出し、読み込めるようにします |
| 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. |
| 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. |
| 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 モデルを含みます）
"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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モード：テキスト、表、またはカスタム形式です
* `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` - 通常
* `canvas` - キャンバス
* `team` - チーム (省略可能)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参考情報のチャンク数です。デフォルトは 12、最小値は 1 です (省略可能)
"defaultLabelRelations"?: object // アシスタントレベルのデフォルトのナレッジベースラベルフィルターです。形式は query_metadata.label_relations と同じで、null はフィルターなしを意味します。呼び出し側が query_metadata を指定しない場合にのみ、優先順位が最も低いフォールバックとして適用されます。 (省略可能)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り詰めを無視し、reranker の結果をすべて返します (省略可能)
"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 (省略可能)
"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. (省略可能)
"customMaxLlmOutputTokens"?: integer // LLM の最大出力トークン数をカスタマイズします。最小値は 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_searching_tool を通じてツールを動的に検出し、読み込めるようにします (省略可能)
"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. (省略可能)
"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. (省略可能)
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプルテキスト列",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": True,
"enableInlineCitations": True,
"enableCodeInterpreter": True,
"enableBrowserTool": True,
"enableImageSearch": True,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": True,
"enableSizeBasedToolResultTruncation": True,
"toolResultMaxChars": 123,
"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
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',
'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,
'enableEvaluation' => true,
'enableInlineCitations' => true,
'enableCodeInterpreter' => true,
'enableBrowserTool' => true,
'enableImageSearch' => true,
'enableClaudeStreamRetry' => 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,
'maxAgentIterations' => 123,
'agentTimeoutSeconds' => 123,
'agentTimeoutMessage' => 'サンプル文字列',
'requireTextWithFlexCards' => true,
'enableSizeBasedToolResultTruncation' => true,
'toolResultMaxChars' => 123,
'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 モデルを含みます）
"llm": // 紐づけられたモデルの id、name、および提供終了情報です。FK を直接読み取るため、組織によってそのモデルが無効化されていても返されます
{
"id": string (uuid)
"name": string
"retiresAt": string (date) // プロバイダーによる提供終了日です。期日を過ぎると、毎日のスケジュール処理がアシスタントを replacement に切り替え、このモデルを無効化します。null は提供終了が予定されていないことを示します
"replacement": // 提供終了後に引き継ぐモデル（id と name）です。null は未指定を示し、期日が過ぎても自動的には移行されません
{
"id": string (uuid)
"name": 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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モード：テキスト、表、またはカスタム形式です
* `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
}
]
"connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (省略可能)
{
"id": string (uuid)
"name": string
}
]
"agentMode"?: // エージェントモード：通常、SQL、またはワークフローモードです
* `normal` - 通常
* `canvas` - キャンバス
* `team` - チーム (省略可能)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参考情報のチャンク数です。デフォルトは 12、最小値は 1 です (省略可能)
"defaultLabelRelations"?: object // アシスタントレベルのデフォルトのナレッジベースラベルフィルターです。形式は query_metadata.label_relations と同じで、null はフィルターなしを意味します。呼び出し側が query_metadata を指定しない場合にのみ、優先順位が最も低いフォールバックとして適用されます。 (省略可能)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り詰めを無視し、reranker の結果をすべて返します (省略可能)
"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 (省略可能)
"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. (省略可能)
"customMaxLlmOutputTokens"?: integer // カスタムの LLM 最大出力トークン数です。最小値は 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_searching_tool を通じてツールを動的に検出し、読み込めるようにします (省略可能)
"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. (省略可能)
"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. (省略可能)
"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
}
"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": "サンプル文字列"
}
},
"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": "サンプル文字列"
}
],
"connectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "サンプル文字列"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"defaultLabelRelations": null,
"useFullRetrievalRange": false,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"enableBrowserTool": false,
"enableImageSearch": false,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 456,
"agentTimeoutSeconds": 456,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": false,
"isMultimodalLlm": false,
"enableSizeBasedToolResultTruncation": false,
"toolResultMaxChars": 456,
"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": "サンプル文字列"
},
"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 の一覧を取得
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
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 の一覧を取得
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
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"
}
}
]
```
***
### 大規模言語モデルの一覧
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
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.
}
]
```
**レスポンスの値の例**
```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": "レスポンス文字列"
}
]
```
***
### AI アシスタント一覧の取得
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
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
}
]
"agentMode"?: // Agent mode: Canvas or Normal. Canvas mode generates answers on a canvas; Normal mode generates regular answers.
* `normal` - 通常
* `canvas` - キャンバス
* `team` - チーム (任意)
{
}
"replyMode"?: // Reply mode: Normal, Template, Hybrid, or Agent.
* `normal` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `agent` - エージェント (任意)
{
}
"updatedAt": string (timestamp)
"enableEvaluation"?: boolean // 任意
"enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (任意)
"enableToolSearching"?: boolean // Enables dynamic tool search, letting the agent discover and load tools via tool_searching_tool. (任意)
"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. (任意)
"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": "サンプル文字列"
}
],
"agentMode": {},
"replyMode": {},
"updatedAt": "サンプル文字列",
"enableEvaluation": false,
"enableInlineCitations": false,
"enableToolSearching": false,
"enableCodeInterpreter": false,
"enableBrowserTool": false,
"enableImageSearch": false,
"numberOfRetrievedChunks": 456,
"useFullRetrievalRange": 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 アシスタントの取得
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
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 モデルを含む）
"llm": // バインドされたモデルの id、name、廃止情報。FK を直接読み取るため、組織によってそのモデルが無効化されていても返されます
{
"id": string (uuid)
"name": string
"retiresAt": string (date) // プロバイダーによる廃止日。期限を過ぎると、毎日のスケジュール処理がアシスタントを replacement に切り替え、このモデルを無効化します。null は廃止の予定がないことを示します
"replacement": // 廃止後に引き継ぐモデル（id と name）。null は未指定を示し、期限到来時に自動移行は行われません
{
"id": string (uuid)
"name": 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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モード：テキスト、表、またはカスタム形式
* `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
}
]
"connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (任意)
{
"id": string (uuid)
"name": string
}
]
"agentMode"?: // エージェントモード：通常、SQL、またはワークフローモードです
* `normal` - 通常
* `canvas` - Canvas
* `team` - チーム (省略可能)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参照データの件数です。デフォルトは 12、最小値は 1 です (省略可能)
"defaultLabelRelations"?: object // アシスタントレベルのデフォルトのナレッジベースラベルフィルタ条件です。形式は query_metadata.label_relations と同じで、null はフィルタなしを意味します。呼び出し側が query_metadata を指定しない場合にのみ、最も優先度の低いフォールバックとして適用されます。 (省略可能)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り捨てを無視し、reranker の結果をすべて返します (省略可能)
"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 (省略可能)
"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. (省略可能)
"customMaxLlmOutputTokens"?: integer // LLM の最大出力トークン数をカスタム設定します。最小値は 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_searching_tool を通じてツールを動的に検出して読み込めます (省略可能)
"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. (省略可能)
"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. (省略可能)
"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
}
"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": "レスポンス文字列"
}
},
"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": "レスポンス文字列"
}
],
"connectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"defaultLabelRelations": null,
"useFullRetrievalRange": false,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"enableBrowserTool": false,
"enableImageSearch": false,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 456,
"agentTimeoutSeconds": 456,
"agentTimeoutMessage": "レスポンス文字列",
"requireTextWithFlexCards": false,
"isMultimodalLlm": false,
"enableSizeBasedToolResultTruncation": false,
"toolResultMaxChars": 456,
"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": "レスポンス文字列"
},
"webChatIsActive": false,
"apiIsActive": false,
"fileWorkspaceMode": {},
"fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
"fileWorkspaceStatus": {
"name": "example.pdf",
"content": "base64encoded_content",
"contentType": "application/pdf"
},
"fileWorkspaceAvailable": false
}
```
***
### AI アシスタントの更新
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 モデルを含みます） |
| 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`: 通常 ; `template`: テンプレート ; `hybrid`: ハイブリッド ; `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 | いいえ | 出力モード：テキスト、表、またはカスタム形式です `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`: 通常 ; `canvas`: Canvas ; `team`: チーム; |
| numberOfRetrievedChunks | integer | いいえ | 取得する参照データの件数です。デフォルトは 12、最小値は 1 です |
| defaultLabelRelations | object | いいえ | アシスタントレベルのデフォルトのナレッジベースラベルフィルタ条件です。形式は query\_metadata.label\_relations と同じで、null はフィルタなしを意味します。呼び出し側が query\_metadata を指定しない場合にのみ、最も優先度の低いフォールバックとして適用されます。 |
| useFullRetrievalRange | boolean | いいえ | 有効にすると、LLM の top\_k による切り捨てを無視し、reranker の結果をすべて返します |
| 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 |
| 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... |
| customMaxLlmOutputTokens | integer | いいえ | LLM の最大出力トークン数をカスタム設定します。最小値は 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\_searching\_tool を通じてツールを動的に検出して読み込めます |
| 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. |
| 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. |
| 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 モデルを含みます）
"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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モード：テキスト、表、またはカスタム形式です
* `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` - 通常
* `canvas` - キャンバス
* `team` - チーム (省略可能)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参考情報のチャンク数です。デフォルトは 12、最小値は 1 です (省略可能)
"defaultLabelRelations"?: object // アシスタントレベルのデフォルトのナレッジベースラベルフィルターです。形式は query_metadata.label_relations と同じで、null はフィルターなしを意味します。呼び出し側が query_metadata を指定しない場合にのみ、優先順位が最も低いフォールバックとして適用されます。 (省略可能)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り詰めを無視し、reranker の結果をすべて返します (省略可能)
"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 (省略可能)
"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. (省略可能)
"customMaxLlmOutputTokens"?: integer // LLM 出力トークン数の上限をカスタマイズします。最小値は 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_searching_tool を通じてツールを動的に検出・読み込みできます (省略可能)
"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. (省略可能)
"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. (省略可能)
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": True,
"enableInlineCitations": True,
"enableCodeInterpreter": True,
"enableBrowserTool": True,
"enableImageSearch": True,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": True,
"enableSizeBasedToolResultTruncation": True,
"toolResultMaxChars": 123,
"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
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',
'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,
'enableEvaluation' => true,
'enableInlineCitations' => true,
'enableCodeInterpreter' => true,
'enableBrowserTool' => true,
'enableImageSearch' => true,
'enableClaudeStreamRetry' => 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,
'maxAgentIterations' => 123,
'agentTimeoutSeconds' => 123,
'agentTimeoutMessage' => 'サンプルテキスト列',
'requireTextWithFlexCards' => true,
'enableSizeBasedToolResultTruncation' => true,
'toolResultMaxChars' => 123,
'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 モデルを含む）
"llm": // 紐付けられたモデルの id、name、提供終了情報。FK から直接読み取るため、組織がそのモデルを無効化していても返されます
{
"id": string (uuid)
"name": string
"retiresAt": string (date) // プロバイダーによる提供終了日。期日を過ぎると、毎日のスケジュール処理によりアシスタントが replacement に切り替えられ、このモデルは無効化されます。null は終了予定なしを表します
"replacement": // 提供終了後に引き継ぐモデル（id と name）。null は未指定を表し、期日になっても自動移行されません
{
"id": string (uuid)
"name": 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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モード：テキスト、表、またはカスタム形式
* `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
}
]
"connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (省略可能)
{
"id": string (uuid)
"name": string
}
]
"agentMode"?: // エージェントモード：通常、SQL、またはワークフローモード
* `normal` - 通常
* `canvas` - Canvas
* `team` - チーム (省略可能)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参照データの件数。デフォルトは 12、最小値は 1 (省略可能)
"defaultLabelRelations"?: object // アシスタントレベルのデフォルトのナレッジベースラベルフィルター条件。形式は query_metadata.label_relations と同じで、null はフィルターなしを表します。呼び出し側が query_metadata を指定しない場合にのみ、最低優先度のフォールバックとして適用されます。 (省略可能)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り捨てを無視し、reranker の結果をすべて返します (省略可能)
"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 (省略可能)
"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. (省略可能)
"customMaxLlmOutputTokens"?: integer // LLM の最大出力トークン数のカスタム値。最小値は 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_searching_tool を通じてツールを動的に検出・読み込めるようにします (省略可能)
"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. (省略可能)
"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. (省略可能)
"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
}
"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": "レスポンス文字列"
}
},
"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": "レスポンス文字列"
}
],
"connectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"defaultLabelRelations": null,
"useFullRetrievalRange": false,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"enableBrowserTool": false,
"enableImageSearch": false,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 456,
"agentTimeoutSeconds": 456,
"agentTimeoutMessage": "レスポンス文字列",
"requireTextWithFlexCards": false,
"isMultimodalLlm": false,
"enableSizeBasedToolResultTruncation": false,
"toolResultMaxChars": 456,
"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": "レスポンス文字列"
},
"webChatIsActive": false,
"apiIsActive": false,
"fileWorkspaceMode": {},
"fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
"fileWorkspaceStatus": {
"name": "example.pdf",
"content": "base64encoded_content",
"contentType": "application/pdf"
},
"fileWorkspaceAvailable": false
}
```
***
### AI アシスタントの部分更新
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 モデルを含みます） |
| 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`: 通常 ; `template`: テンプレート ; `hybrid`: ハイブリッド ; `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 | いいえ | 出力モードです。テキスト、表、またはカスタム形式を指定します `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`: 通常 ; `canvas`: キャンバス ; `team`: チーム; |
| numberOfRetrievedChunks | integer | いいえ | 取得する参照チャンク数です。デフォルトは 12、最小値は 1 です |
| defaultLabelRelations | object | いいえ | アシスタント単位のデフォルトのナレッジベースラベルフィルター条件です。形式は query\_metadata.label\_relations と同じです。null はフィルターなしを示します。呼び出し元が query\_metadata を指定しない場合にのみ、優先順位が最も低いフォールバックとして適用されます。 |
| useFullRetrievalRange | boolean | いいえ | 有効にすると、LLM の top\_k による切り詰めを無視し、リランカーの結果をすべて返します |
| 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 |
| 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... |
| customMaxLlmOutputTokens | integer | いいえ | LLM の最大出力トークン数をカスタマイズします。最小値は 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\_searching\_tool を通じてツールを動的に検出して読み込めるようにします |
| 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. |
| 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. |
| 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 モデルを含みます） (任意)
"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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モードです。テキスト、表、またはカスタム形式を指定します
* `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` - 通常
* `canvas` - キャンバス
* `team` - チーム (任意)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参照チャンク数です。デフォルトは 12、最小値は 1 です (任意)
"defaultLabelRelations"?: object // アシスタント単位のデフォルトのナレッジベースラベルフィルター条件です。形式は query_metadata.label_relations と同じです。null はフィルターなしを示します。呼び出し元が query_metadata を指定しない場合にのみ、優先順位が最も低いフォールバックとして適用されます。 (任意)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り詰めを無視し、リランカーの結果をすべて返します (任意)
"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 (任意)
"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. (任意)
"customMaxLlmOutputTokens"?: integer // LLM の最大出力トークン数をカスタマイズします。最小値は 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_searching_tool を通じてツールを動的に検出して読み込めるようにします (任意)
"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. (任意)
"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. (任意)
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "サンプル文字列",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "文字列の例",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": true,
"enableInlineCitations": true,
"enableCodeInterpreter": true,
"enableBrowserTool": true,
"enableImageSearch": true,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "文字列の例",
"requireTextWithFlexCards": true,
"enableSizeBasedToolResultTruncation": true,
"toolResultMaxChars": 123,
"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",
"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,
"enableEvaluation": True,
"enableInlineCitations": True,
"enableCodeInterpreter": True,
"enableBrowserTool": True,
"enableImageSearch": True,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 123,
"agentTimeoutSeconds": 123,
"agentTimeoutMessage": "文字列の例",
"requireTextWithFlexCards": True,
"enableSizeBasedToolResultTruncation": True,
"toolResultMaxChars": 123,
"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
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',
'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,
'enableEvaluation' => true,
'enableInlineCitations' => true,
'enableCodeInterpreter' => true,
'enableBrowserTool' => true,
'enableImageSearch' => true,
'enableClaudeStreamRetry' => 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,
'maxAgentIterations' => 123,
'agentTimeoutSeconds' => 123,
'agentTimeoutMessage' => '文字列の例',
'requireTextWithFlexCards' => true,
'enableSizeBasedToolResultTruncation' => true,
'toolResultMaxChars' => 123,
'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 モデルを含みます）
"llm": // 関連付けられたモデルの id、name、提供終了に関する情報です。FK から直接読み取るため、組織がそのモデルを無効にしていても返されます
{
"id": string (uuid)
"name": string
"retiresAt": string (date) // プロバイダーによる提供終了日です。この日付を過ぎると、毎日のスケジュール処理でアシスタントを replacement に切り替え、このモデルを無効にします。null は提供終了が予定されていないことを示します
"replacement": // 提供終了後に使用する後継モデル（id と name）です。null は未指定を示し、提供終了日に自動移行は行われません
{
"id": string (uuid)
"name": 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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モード：テキスト、表、またはカスタム形式です
* `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
}
]
"connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (任意)
{
"id": string (uuid)
"name": string
}
]
"agentMode"?: // エージェントモード：通常、SQL、またはワークフローのモードです
* `normal` - 通常
* `canvas` - キャンバス
* `team` - チーム (任意)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参考資料チャンクの数です。デフォルトは 12、最小値は 1 です (任意)
"defaultLabelRelations"?: object // アシスタントレベルのデフォルトのナレッジベースラベルフィルター条件です。形式は query_metadata.label_relations と同じで、null はフィルターなしを示します。呼び出し元が query_metadata を指定しない場合にのみ、最も優先順位の低いフォールバックとして適用されます。 (任意)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り詰めを無視し、reranker の結果をすべて返します (任意)
"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 (任意)
"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. (任意)
"customMaxLlmOutputTokens"?: integer // LLM の最大出力トークン数をカスタマイズします。最小値は 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_searching_tool を通じてツールを動的に検出して読み込めるようにします (任意)
"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. (任意)
"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. (任意)
"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
}
"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": "レスポンス文字列"
}
},
"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": "レスポンス文字列"
}
],
"connectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"defaultLabelRelations": null,
"useFullRetrievalRange": false,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"enableBrowserTool": false,
"enableImageSearch": false,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 456,
"agentTimeoutSeconds": 456,
"agentTimeoutMessage": "レスポンス文字列",
"requireTextWithFlexCards": false,
"isMultimodalLlm": false,
"enableSizeBasedToolResultTruncation": false,
"toolResultMaxChars": 456,
"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": "レスポンス文字列"
},
"webChatIsActive": false,
"apiIsActive": false,
"fileWorkspaceMode": {},
"fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
"fileWorkspaceStatus": {
"name": "example.pdf",
"content": "base64encoded_content",
"contentType": "application/pdf"
},
"fileWorkspaceAvailable": false
}
```
***
### AI アシスタントの削除
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
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 アシスタントの複製
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
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 モデルを含みます）
"llm": // 紐付けられたモデルの id、name、提供終了情報です。FK を直接参照するため、組織がそのモデルを無効にしていても返されます
{
"id": string (uuid)
"name": string
"retiresAt": string (date) // プロバイダーの提供終了日です。この日を迎えると、毎日のスケジュール処理でアシスタントを replacement に切り替え、このモデルを無効にします。null は提供終了が予定されていないことを示します
"replacement": // 提供終了後に使用する代替モデル（id と name）です。null は未指定を示し、提供終了日に自動移行は行われません
{
"id": string (uuid)
"name": 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` - 通常
* `template` - テンプレート
* `hybrid` - ハイブリッド
* `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"?: // 出力モードです。テキスト、表、またはカスタム形式を指定します
* `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
}
]
"connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (任意)
{
"id": string (uuid)
"name": string
}
]
"agentMode"?: // エージェントモードです。通常、SQL、またはワークフローモードを指定します
* `normal` - 通常
* `canvas` - キャンバス
* `team` - チーム (任意)
{
}
"numberOfRetrievedChunks"?: integer // 取得する参考資料の数です。デフォルトは 12、最小値は 1 です (任意)
"defaultLabelRelations"?: object // アシスタントレベルのデフォルトのナレッジベースラベルフィルター条件です。形式は query_metadata.label_relations と同じで、null はフィルターなしを示します。呼び出し元が query_metadata を指定しない場合にのみ、優先順位が最も低いフォールバックとして適用されます。 (任意)
"useFullRetrievalRange"?: boolean // 有効にすると、LLM の top_k による切り詰めを無視し、reranker の結果をすべて返します (任意)
"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 (任意)
"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. (任意)
"customMaxLlmOutputTokens"?: integer // LLM の最大出力トークン数をカスタマイズします。最小値は 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 // 動的ツール検索を有効にし、agent が tool_searching_tool を通じてツールを動的に検出して読み込めるようにします (任意)
"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. (任意)
"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. (任意)
"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
}
"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": "レスポンス文字列"
}
},
"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": "レスポンス文字列"
}
],
"connectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"defaultLabelRelations": null,
"useFullRetrievalRange": false,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"enableBrowserTool": false,
"enableImageSearch": false,
"enableClaudeStreamRetry": 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,
"maxAgentIterations": 456,
"agentTimeoutSeconds": 456,
"agentTimeoutMessage": "レスポンス文字列",
"requireTextWithFlexCards": false,
"isMultimodalLlm": false,
"enableSizeBasedToolResultTruncation": false,
"toolResultMaxChars": 456,
"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": "レスポンス文字列"
},
"webChatIsActive": false,
"apiIsActive": false,
"fileWorkspaceMode": {},
"fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
"fileWorkspaceStatus": {
"name": "example.pdf",
"content": "base64encoded_content",
"contentType": "application/pdf"
},
"fileWorkspaceAvailable": false
}
```
***
### 評価機能の有効化または無効化
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
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 一覧を取得
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
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
"config": object
"blockMessage": string
"enabled": boolean
"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": "レスポンス文字列",
"config": null,
"blockMessage": "レスポンス文字列",
"enabled": 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 を作成
POST `/api/v1/hooks/`
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ------------ | ------------- | --- | -- |
| templateId | string (uuid) | はい | |
| name | string | はい | |
| description | string | いいえ | |
| config | object | いいえ | |
| blockMessage | string | いいえ | |
| enabled | boolean | いいえ | |
**リクエストスキーマの例**
```typescript
{
"templateId": string (uuid)
"name": string
"description"?: string // 任意
"config"?: object // 任意
"blockMessage"?: string // 任意
"enabled"?: boolean // 任意
}
```
**リクエストの値の例**
```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
}
```
#### コード例
{% 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
}'
# 実行前に 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
};
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
}
response = requests.post(url, json=data, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストでエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/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
]
]);
$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
"config": object
"blockMessage": string
"enabled": boolean
"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": "レスポンス文字列",
"config": null,
"blockMessage": "レスポンス文字列",
"enabled": 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 を取得
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
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
"config": object
"blockMessage": string
"enabled": boolean
"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": "レスポンス文字列",
"config": null,
"blockMessage": "レスポンス文字列",
"enabled": 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 を部分更新
PATCH `/api/v1/hooks/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | -- |
| `id` | ✅ | string | |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ------------ | ------- | --- | -- |
| name | string | いいえ | |
| description | string | いいえ | |
| config | object | いいえ | |
| blockMessage | string | いいえ | |
| enabled | boolean | いいえ | |
**リクエストスキーマの例**
```typescript
{
"name"?: string // 任意
"description"?: string // 任意
"config"?: object // 任意
"blockMessage"?: string // 任意
"enabled"?: boolean // 任意
}
```
**リクエストの値の例**
```json
{
"name": "名前の例",
"description": "文字列の例",
"config": null,
"blockMessage": "文字列の例",
"enabled": 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
}'
# 実行前に 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
};
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
}
response = requests.patch(url, json=data, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストでエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/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
]
]);
$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
"config": object
"blockMessage": string
"enabled": boolean
"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": "レスポンス文字列",
"config": null,
"blockMessage": "レスポンス文字列",
"enabled": 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 の削除
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
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 の一覧取得
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
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
}
]
}
```
**レスポンス値の例**
```json
{
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"scope": "レスポンス文字列",
"templateName": "レスポンス文字列",
"templateTypeLabel": "レスポンス文字列",
"triggerPoint": "レスポンス文字列",
"action": "レスポンス文字列",
"enabled": false,
"order": 456
}
]
}
```
***
### AI アシスタントに接続された Hook の一括置換
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
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
}
]
}
```
**レスポンス値の例**
```json
{
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"scope": "レスポンス文字列",
"templateName": "レスポンス文字列",
"templateTypeLabel": "レスポンス文字列",
"triggerPoint": "レスポンス文字列",
"action": "レスポンス文字列",
"enabled": false,
"order": 456
}
]
}
```
***
### スケジュールの一覧取得
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. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/schedules/?page=1&pageSize=1" \
-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", 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"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/schedules/?page=1&pageSize=1", [
'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)
]
"saveResultToContext"?: boolean // 任意
"enabled"?: boolean // 任意
"lastExecutedAt"?: string (timestamp) // 任意
"executionCount"?: integer // 任意
"maxExecutions"?: integer // 任意
"countsTowardLimit": boolean
"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"
],
"saveResultToContext": false,
"enabled": false,
"lastExecutedAt": "レスポンス文字列",
"executionCount": 456,
"maxExecutions": 456,
"countsTowardLimit": false,
"createdAt": "レスポンス文字列"
}
]
}
```
***
### スケジュールの作成
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] | いいえ | |
| 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 | いいえ | |
**リクエストスキーマの例**
```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)
]
"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 // 任意
}
```
**リクエスト値の例**
```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"
],
"scheduleType": "cron",
"cronExpression": "文字列の例",
"intervalSeconds": 123,
"oneShotAt": "文字列の例",
"timezone": "文字列の例",
"enabled": true,
"maxExecutions": 123
}
```
#### コード例
{% 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"
],
"scheduleType": "cron",
"cronExpression": "文字列の例",
"intervalSeconds": 123,
"oneShotAt": "文字列の例",
"timezone": "文字列の例",
"enabled": true,
"maxExecutions": 123
}'
# 実行前に 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"
],
"scheduleType": "cron",
"cronExpression": "文字列の例",
"intervalSeconds": 123,
"oneShotAt": "文字列の例",
"timezone": "文字列の例",
"enabled": true,
"maxExecutions": 123
};
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"
],
"scheduleType": "cron",
"cronExpression": "文字列の例",
"intervalSeconds": 123,
"oneShotAt": "文字列の例",
"timezone": "文字列の例",
"enabled": True,
"maxExecutions": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/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'
],
'scheduleType' => 'cron',
'cronExpression' => 'サンプル文字列',
'intervalSeconds' => 123,
'oneShotAt' => 'サンプル文字列',
'timezone' => 'サンプル文字列',
'enabled' => true,
'maxExecutions' => 123
]
]);
$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)
]
"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 // 任意
"countsTowardLimit": boolean
"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"
],
"scheduleType": "cron",
"cronExpression": "レスポンス文字列",
"intervalSeconds": 456,
"oneShotAt": "レスポンス文字列",
"timezone": "レスポンス文字列",
"periodicTask": 456,
"enabled": false,
"lastExecutedAt": "レスポンス文字列",
"executionCount": 456,
"maxExecutions": 456,
"countsTowardLimit": false,
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
***
### 特定のスケジュールを取得
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
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)
]
"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 // 任意
"countsTowardLimit": boolean
"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"
],
"scheduleType": "cron",
"cronExpression": "レスポンス文字列",
"intervalSeconds": 456,
"oneShotAt": "レスポンス文字列",
"timezone": "レスポンス文字列",
"periodicTask": 456,
"enabled": false,
"lastExecutedAt": "レスポンス文字列",
"executionCount": 456,
"maxExecutions": 456,
"countsTowardLimit": false,
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
***
### スケジュールを部分更新
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] | いいえ | |
| 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 | いいえ | |
**リクエストスキーマの例**
```typescript
{
"name"?: string // 任意
"prompt"?: string // 任意
"contextVariables"?: object // 任意
"saveResultToContext"?: boolean // 任意
"deliveryConversationIds"?: [ // 任意
string (uuid)
]
"deliveryWebhookUrls"?: [ // 任意
string (uri)
]
"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 // 任意
}
```
**リクエストの値の例**
```json
{
"name": "サンプル名",
"prompt": "サンプル文字列",
"contextVariables": null,
"saveResultToContext": true,
"deliveryConversationIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"deliveryWebhookUrls": [
"https://example.com/file.jpg"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": true,
"maxExecutions": 123
}
```
#### コード例
{% 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"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": true,
"maxExecutions": 123
}'
# 実行前に 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"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": true,
"maxExecutions": 123
};
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"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": True,
"maxExecutions": 123
}
response = requests.patch(url, json=data, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/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'
],
'scheduleType' => 'cron',
'cronExpression' => 'サンプル文字列',
'intervalSeconds' => 123,
'oneShotAt' => 'サンプル文字列',
'timezone' => 'サンプル文字列',
'enabled' => true,
'maxExecutions' => 123
]
]);
$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)
]
"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 // 任意
"countsTowardLimit": boolean
"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"
],
"scheduleType": "cron",
"cronExpression": "レスポンス文字列",
"intervalSeconds": 456,
"oneShotAt": "レスポンス文字列",
"timezone": "レスポンス文字列",
"periodicTask": 456,
"enabled": false,
"lastExecutedAt": "レスポンス文字列",
"executionCount": 456,
"maxExecutions": 456,
"countsTowardLimit": false,
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
***
### スケジュールを削除
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
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 |
***
### スケジュールを即時実行
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] | いいえ | |
| 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 | いいえ | |
**リクエストスキーマの例**
```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)
]
"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 // 任意
}
```
**リクエストの値の例**
```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"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": true,
"maxExecutions": 123
}
```
#### コード例
{% 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"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": true,
"maxExecutions": 123
}'
# 実行前に 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"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": true,
"maxExecutions": 123
};
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"
],
"scheduleType": "cron",
"cronExpression": "サンプル文字列",
"intervalSeconds": 123,
"oneShotAt": "サンプル文字列",
"timezone": "サンプル文字列",
"enabled": True,
"maxExecutions": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストでエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/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'
],
'scheduleType' => 'cron',
'cronExpression' => 'サンプル文字列',
'intervalSeconds' => 123,
'oneShotAt' => 'サンプル文字列',
'timezone' => 'サンプル文字列',
'enabled' => true,
'maxExecutions' => 123
]
]);
$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"
}
```
***
### スケジュールの有効化または無効化
POST `/api/v1/schedules/{id}/toggle/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Chatbot Schedule. |
#### コード例
{% 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"
# 実行前に 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.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"
}
response = requests.post(url, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストでエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/", [
'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)
]
"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 // 任意
"countsTowardLimit": boolean
"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"
],
"scheduleType": "cron",
"cronExpression": "レスポンス文字列",
"intervalSeconds": 456,
"oneShotAt": "レスポンス文字列",
"timezone": "レスポンス文字列",
"periodicTask": 456,
"enabled": false,
"lastExecutedAt": "レスポンス文字列",
"executionCount": 456,
"maxExecutions": 456,
"countsTowardLimit": 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/ja/api-reference/ai-zhu-li.md?ask=&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.