> 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/dui-hua-widget.md). # チャットウィジェット ### Web Chat を作成します POST `/api/v1/web-chats/` #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ----------------------------------------------- | ------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | avatar | string (uri) | いいえ | | | logo | string (uri) | いいえ | | | description | string | いいえ | | | cover | string (uri) | いいえ | | | backUrl | string | いいえ | | | isActive | boolean | いいえ | | | theme | object | はい | | | theme.primaryColor | string | いいえ | | | theme.navbarTextColor | string | いいえ | | | theme.conversationBackgroundColor | string | いいえ | | | theme.chatbotMessageTextColor | string | いいえ | | | theme.userMessageTextColor | string | いいえ | | | theme.chatbotMessageBackgroundColor | string | いいえ | | | theme.userMessageBackgroundColor | string | いいえ | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.chatbotMessageGradientEnabled | boolean | いいえ | | | theme.userMessageGradientEnabled | boolean | いいえ | | | darkTheme | object | はい | | | darkTheme.primaryColor | string | いいえ | | | darkTheme.navbarTextColor | string | いいえ | | | darkTheme.conversationBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageTextColor | string | いいえ | | | darkTheme.userMessageTextColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundColor | string | いいえ | | | darkTheme.userMessageBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.chatbotMessageGradientEnabled | boolean | いいえ | | | darkTheme.userMessageGradientEnabled | boolean | いいえ | | | enableFileUpload | boolean | いいえ | | | enableDisplayCitations | boolean | いいえ | | | toolDisplayMode | string (enum: full, compact, hidden) | いいえ | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | いいえ | 有効にすると、ask\_user\_question の選択肢が入力欄の上にボタン列として表示されます（入力欄は引き続き使用できます）。無効にすると、従来のオーバーレイパネルが表示されます。段階的な展開用のスイッチで、いつでも無効にして元の動作に戻せます。 | | enableConversationHandoff | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、継続ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎスイッチにも制御されます（グローバルスイッチが無効の場合、すべて無効になります）。MaiGPT では、このスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは、別途「コンテキスト使用量を表示」で制御されます。デフォルトでは無効で、お客様が外部に公開する webchat には引き継ぎ UI が表示されません。段階的な展開用のスイッチで、無効にすると即座に元の動作に戻り、リリースのロールバックは不要です。 | | enableDisplayContextUsage | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバルな引き継ぎスイッチを含む）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT では、このスイッチに関係なく常に表示されます。デフォルトでは無効です。無効にすると即座に元の動作に戻り、リリースのロールバックは不要です。 | | enableDisplayThinking | boolean | いいえ | | | enableUserThinkingControl | boolean | いいえ | | | enableDisplayQueryMetadata | boolean | いいえ | | | enableDisplayHookMarkers | boolean | いいえ | | | hookMarkerTextInputModify | string | いいえ | | | hookMarkerTextOutputModify | string | いいえ | | | hookMarkerTextInputBlock | string | いいえ | | | hookMarkerTextOutputBlock | string | いいえ | | | enableShareConversation | boolean | いいえ | | | enableLocation | boolean | いいえ | | | enableShowPoweredBy | boolean | いいえ | | | poweredByLogo | string (uri) | いいえ | | | enableAnonymous | boolean | いいえ | | | enableDisplayPreviousConversation | boolean | いいえ | | | enableDisplayConversationHistory | boolean | いいえ | | | enableConversationTimer | boolean | いいえ | | | conversationTimerDuration | integer | いいえ | タイマーのタイムアウト時間です。範囲は 3-60 分です | | enableAutoNewConversationOnTimeout | boolean | いいえ | | | enableSatisfactionSurvey | boolean | いいえ | | | satisfactionSurveyDelayMinutes | integer | いいえ | 最後の AI 応答からアンケートが表示されるまでの時間（分）です。範囲は 1-60 分です | | satisfactionSurveyPrompt | string | いいえ | アンケートのタイトルをカスタマイズします。空欄の場合は、フロントエンドの各言語のデフォルトテキストを使用します | | enableThemeModeToggle | boolean | いいえ | | | enableDisplayFontSizeSwitch | boolean | いいえ | | | defaultThemeMode | object | いいえ | | | enableDownloadCitations | boolean | いいえ | | | customDomain | object (3 個のプロパティを含みます: id, domain, status) | いいえ | | | customDomain.domain | string | はい | | | enableDisplayChatbotAvatar | boolean | いいえ | | | enableDisplayChatbotName | boolean | いいえ | | | buttonIcon | string (uri) | いいえ | | | conversationStartersDisplayCount | integer | いいえ | | | preChatFormEnabled | boolean | いいえ | | | preChatFormFields | object | いいえ | | | preChatFormTitle | object | いいえ | | | preChatFormSubtitle | object | いいえ | | | loadingDisplayMode | object | いいえ | Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured beh... | | loadingStageCopyByLocale | object | いいえ | Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a... | | loadingLongWaitCopyByLocale | object | いいえ | Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt... | | loadingLongWaitThresholdSeconds | integer | いいえ | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | いいえ | True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ... | | loadingAnimationSharedAssetUrl | string (uri) | いいえ | | | loadingAnimationAssetUrlsByStage | object | いいえ | Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. | | loadingTypingShowCopy | boolean | いいえ | Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line.... | | toolCardRunningIconUrl | string (uri) | いいえ | | | toolCardCompletedIconUrl | string (uri) | いいえ | | **リクエストスキーマの例** ```typescript { "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示されます（入力欄は引き続き使用できます）。無効にすると、従来のオーバーレイパネルが表示されます。段階的な展開用のスイッチで、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、継続ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎスイッチにも制御されます（グローバルスイッチが無効の場合、すべて無効になります）。MaiGPT では、このスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは、別途「コンテキスト使用量を表示」で制御されます。デフォルトでは無効で、お客様が外部に公開する webchat には引き継ぎ UI が表示されません。段階的な展開用のスイッチで、無効にすると即座に元の動作に戻り、リリースのロールバックは不要です。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバルな引き継ぎスイッチを含む）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT では、このスイッチに関係なく常に表示されます。デフォルトでは無効です。無効にすると即座に元の動作に戻り、リリースのロールバックは不要です。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3-60 分です (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI 応答からアンケートが表示されるまでの時間（分）です。範囲は 1-60 分です (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズします。空欄の場合は、フロントエンドの各言語のデフォルトテキストを使用します (任意) "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "conversationStartersDisplayCount"?: integer // 任意 "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 } ``` **リクエスト値の例** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト内容 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト内容 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": True, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "enableFileUpload": True, "enableDisplayCitations": True, "toolDisplayMode": "full", "enableAskOptionButtons": True, "enableConversationHandoff": True, "enableDisplayContextUsage": True, "enableDisplayThinking": True, "enableUserThinkingControl": True, "enableDisplayQueryMetadata": True, "enableDisplayHookMarkers": True, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": True, "enableLocation": True, "enableShowPoweredBy": True, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": True, "enableDisplayPreviousConversation": True, "enableDisplayConversationHistory": True, "enableConversationTimer": True, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": True, "enableSatisfactionSurvey": True, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": True, "enableDisplayChatbotName": True, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": True, "preChatFormFields": None, "preChatFormTitle": None, "preChatFormSubtitle": None, "loadingDisplayMode": {}, "loadingStageCopyByLocale": None, "loadingLongWaitCopyByLocale": None, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": True, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": None, "loadingTypingShowCopy": True, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.post(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'avatar' => 'https://example.com/file.jpg', 'logo' => 'https://example.com/file.jpg', 'description' => 'サンプル文字列', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'サンプル文字列', 'isActive' => true, 'theme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'enableFileUpload' => true, 'enableDisplayCitations' => true, 'toolDisplayMode' => 'full', 'enableAskOptionButtons' => true, 'enableConversationHandoff' => true, 'enableDisplayContextUsage' => true, 'enableDisplayThinking' => true, 'enableUserThinkingControl' => true, 'enableDisplayQueryMetadata' => true, 'enableDisplayHookMarkers' => true, 'hookMarkerTextInputModify' => 'サンプル文字列', 'hookMarkerTextOutputModify' => 'サンプル文字列', 'hookMarkerTextInputBlock' => 'サンプル文字列', 'hookMarkerTextOutputBlock' => 'サンプル文字列', 'enableShareConversation' => true, 'enableLocation' => true, 'enableShowPoweredBy' => true, 'poweredByLogo' => 'https://example.com/file.jpg', 'enableAnonymous' => true, 'enableDisplayPreviousConversation' => true, 'enableDisplayConversationHistory' => true, 'enableConversationTimer' => true, 'conversationTimerDuration' => 123, 'enableAutoNewConversationOnTimeout' => true, 'enableSatisfactionSurvey' => true, 'satisfactionSurveyDelayMinutes' => 123, 'satisfactionSurveyPrompt' => 'サンプル文字列', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'サンプル文字列' ], 'enableDisplayChatbotAvatar' => true, 'enableDisplayChatbotName' => true, 'buttonIcon' => 'https://example.com/file.jpg', 'conversationStartersDisplayCount' => 123, 'preChatFormEnabled' => true, 'preChatFormFields' => null, 'preChatFormTitle' => null, 'preChatFormSubtitle' => null, 'loadingDisplayMode' => new \stdClass(), 'loadingStageCopyByLocale' => null, 'loadingLongWaitCopyByLocale' => null, 'loadingLongWaitThresholdSeconds' => 123, 'loadingAnimationUseSharedAsset' => true, 'loadingAnimationSharedAssetUrl' => 'https://example.com/file.jpg', 'loadingAnimationAssetUrlsByStage' => null, 'loadingTypingShowCopy' => true, 'toolCardRunningIconUrl' => 'https://example.com/file.jpg', 'toolCardCompletedIconUrl' => 'https://example.com/file.jpg' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 201** **レスポンススキーマの例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示され、入力欄は引き続き使用できます。無効にすると、従来のオーバーレイパネルが維持されます。段階的なリリース用の切り替え設定で、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、続行ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎ設定にも従います（グローバル設定が無効の場合はすべて無効になります）。MaiGPT ではこの設定に関係なく常に表示されます。下部のコンテキスト使用率バーは、別の「コンテキスト使用量を表示」設定で制御されます。デフォルトでは無効で、お客様が外部向けに提供する webchat には引き継ぎ UI は表示されません。段階的なリリース用の切り替え設定で、無効にすると元の動作に戻り、リリースをロールバックする必要はありません。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎ設定（グローバル設定を含みます）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT ではこの設定に関係なく常に表示されます。デフォルトでは無効です。無効にすると元の動作に戻り、リリースをロールバックする必要はありません。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3-60 分です。 (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI の返信からアンケートを表示するまでの時間（分）です。範囲は 1-60 分です。 (任意) "satisfactionSurveyPrompt"?: string // アンケートのカスタムタイトルです。空欄の場合は、フロントエンドの多言語対応のデフォルトテキストを使用します。 (任意) "accessType": { } "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 任意 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **レスポンスのサンプル値** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "レスポンス文字列", "cover": "https://example.com/file.jpg", "backUrl": "レスポンス文字列", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "レスポンス文字列" ], "theme": { "primaryColor": "レスポンス文字列", "navbarTextColor": "レスポンス文字列", "conversationBackgroundColor": "レスポンス文字列", "chatbotMessageTextColor": "レスポンス文字列", "userMessageTextColor": "レスポンス文字列", "chatbotMessageBackgroundColor": "レスポンス文字列", "userMessageBackgroundColor": "レスポンス文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "レスポンス文字列", "navbarTextColor": "レスポンス文字列", "conversationBackgroundColor": "レスポンス文字列", "chatbotMessageTextColor": "レスポンス文字列", "userMessageTextColor": "レスポンス文字列", "chatbotMessageBackgroundColor": "レスポンス文字列", "userMessageBackgroundColor": "レスポンス文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableConversationHandoff": false, "enableDisplayContextUsage": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "レスポンス文字列", "hookMarkerTextOutputModify": "レスポンス文字列", "hookMarkerTextInputBlock": "レスポンス文字列", "hookMarkerTextOutputBlock": "レスポンス文字列", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "レスポンス文字列", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "レスポンス文字列", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前例", "description": "レスポンスの説明例" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前例", "description": "レスポンスの説明例" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前例", "description": "レスポンスの説明例" } } ``` *** ### Web Chat 一覧の取得 GET `/api/v1/web-chats/` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/web-chats/", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/web-chats/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript [ { "id": string (uuid) "avatar"?: string (uri) // 任意 "name": string } ] ``` **レスポンス値の例** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "avatar": "https://example.com/file.jpg", "name": "レスポンス文字列" } ] ``` *** ### 特定の Web Chat の取得 GET `/api/v1/web-chats/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示され、入力欄は引き続き使用できます。無効にすると、従来のオーバーレイパネルが表示されます。段階的なロールアウト用のスイッチで、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、再開ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎスイッチにも従います（グローバルスイッチが無効の場合は、すべて無効になります）。MaiGPT では、このスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは、「コンテキスト使用量を表示」で別途制御します。デフォルトでは無効で、顧客向けの webchat に引き継ぎ UI は表示されません。段階的なロールアウト用のスイッチで、無効にすればリリースをロールバックせずに元の動作に戻せます。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバルな引き継ぎスイッチを含みます）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT では、このスイッチに関係なく常に表示されます。デフォルトでは無効です。無効にすればリリースをロールバックせずに元の動作に戻せます。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3～60 分です。 (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI 応答からアンケートが表示されるまでの時間（分）です。範囲は 1～60 分です。 (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズできます。空欄の場合は、フロントエンドの各言語のデフォルトテキストを使用します。 (任意) "accessType": { } "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 任意 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **レスポンス値の例** ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "テスト doc", "avatar": "https://example.com/static/images/default-chatbot-avatar.png", "logo": null, "description": "", "cover": null, "backUrl": "", "isActive": true, "enableSpeech": false, "displayGreeting": null, "displayConversationStarters": [], "theme": { "primaryColor": "#3854d8", "dialogColor": "#ddeaf6", "navbarTextColor": "#ffffff" }, "enableFileUpload": true, "enableDisplayCitations": true, "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": true, "poweredByLogo": null, "accessType": "web", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "テスト doc", "signAuth": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "signSource": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "accessType": "keycloak" }, "signParams": { "keycloak": { "url": "example.com", "realm": "example", "clientId": "example" } } } } } ``` *** ### Web Chat の更新 PUT `/api/v1/web-chats/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ----------------------------------------------- | ------------------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | avatar | string (uri) | いいえ | | | logo | string (uri) | いいえ | | | description | string | いいえ | | | cover | string (uri) | いいえ | | | backUrl | string | いいえ | | | isActive | boolean | いいえ | | | theme | object | はい | | | theme.primaryColor | string | いいえ | | | theme.navbarTextColor | string | いいえ | | | theme.conversationBackgroundColor | string | いいえ | | | theme.chatbotMessageTextColor | string | いいえ | | | theme.userMessageTextColor | string | いいえ | | | theme.chatbotMessageBackgroundColor | string | いいえ | | | theme.userMessageBackgroundColor | string | いいえ | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.chatbotMessageGradientEnabled | boolean | いいえ | | | theme.userMessageGradientEnabled | boolean | いいえ | | | darkTheme | object | はい | | | darkTheme.primaryColor | string | いいえ | | | darkTheme.navbarTextColor | string | いいえ | | | darkTheme.conversationBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageTextColor | string | いいえ | | | darkTheme.userMessageTextColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundColor | string | いいえ | | | darkTheme.userMessageBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.chatbotMessageGradientEnabled | boolean | いいえ | | | darkTheme.userMessageGradientEnabled | boolean | いいえ | | | enableFileUpload | boolean | いいえ | | | enableDisplayCitations | boolean | いいえ | | | toolDisplayMode | string (enum: full, compact, hidden) | いいえ | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | いいえ | 有効にすると、ask\_user\_question の選択肢が入力欄の上にボタンの列として表示されます（入力欄は引き続き使用できます）。無効にすると、現在のオーバーレイパネルが維持されます。段階的なロールアウト用のスイッチで、いつでも無効にして以前の動作に戻せます。 | | enableConversationHandoff | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、続行ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎスイッチの制御を受けます（グローバルスイッチが無効の場合は、すべて無効になります）。MaiGPT ではこのスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは、別途「コンテキスト使用量を表示」で制御します。デフォルトは無効で、顧客向けの webchat には引き継ぎ UI が表示されません。段階的なロールアウト用のスイッチで、無効にするとすぐに以前の動作に戻り、リリースのロールバックは不要です。 | | enableDisplayContextUsage | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat で、入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバルな引き継ぎスイッチを含む）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT ではこのスイッチに関係なく常に表示されます。デフォルトは無効です。無効にするとすぐに以前の動作に戻り、リリースのロールバックは不要です。 | | enableDisplayThinking | boolean | いいえ | | | enableUserThinkingControl | boolean | いいえ | | | enableDisplayQueryMetadata | boolean | いいえ | | | enableDisplayHookMarkers | boolean | いいえ | | | hookMarkerTextInputModify | string | いいえ | | | hookMarkerTextOutputModify | string | いいえ | | | hookMarkerTextInputBlock | string | いいえ | | | hookMarkerTextOutputBlock | string | いいえ | | | enableShareConversation | boolean | いいえ | | | enableLocation | boolean | いいえ | | | enableShowPoweredBy | boolean | いいえ | | | poweredByLogo | string (uri) | いいえ | | | enableAnonymous | boolean | いいえ | | | enableDisplayPreviousConversation | boolean | いいえ | | | enableDisplayConversationHistory | boolean | いいえ | | | enableConversationTimer | boolean | いいえ | | | conversationTimerDuration | integer | いいえ | タイマーのタイムアウト時間です。範囲は 3-60 分です。 | | enableAutoNewConversationOnTimeout | boolean | いいえ | | | enableSatisfactionSurvey | boolean | いいえ | | | satisfactionSurveyDelayMinutes | integer | いいえ | 最後の AI 応答からアンケートが表示されるまでの時間（分）です。範囲は 1-60 分です。 | | satisfactionSurveyPrompt | string | いいえ | アンケートのタイトルをカスタマイズします。空欄の場合は、フロントエンドの言語別のデフォルトテキストを使用します。 | | enableThemeModeToggle | boolean | いいえ | | | enableDisplayFontSizeSwitch | boolean | いいえ | | | defaultThemeMode | object | いいえ | | | enableDownloadCitations | boolean | いいえ | | | customDomain | object (3 つのプロパティを含みます: id, domain, status) | いいえ | | | customDomain.domain | string | はい | | | enableDisplayChatbotAvatar | boolean | いいえ | | | enableDisplayChatbotName | boolean | いいえ | | | buttonIcon | string (uri) | いいえ | | | conversationStartersDisplayCount | integer | いいえ | | | preChatFormEnabled | boolean | いいえ | | | preChatFormFields | object | いいえ | | | preChatFormTitle | object | いいえ | | | preChatFormSubtitle | object | いいえ | | | loadingDisplayMode | object | いいえ | Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured beh... | | loadingStageCopyByLocale | object | いいえ | Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a... | | loadingLongWaitCopyByLocale | object | いいえ | Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt... | | loadingLongWaitThresholdSeconds | integer | いいえ | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | いいえ | True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ... | | loadingAnimationSharedAssetUrl | string (uri) | いいえ | | | loadingAnimationAssetUrlsByStage | object | いいえ | Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. | | loadingTypingShowCopy | boolean | いいえ | Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line.... | | toolCardRunningIconUrl | string (uri) | いいえ | | | toolCardCompletedIconUrl | string (uri) | いいえ | | **リクエスト構造の例** ```typescript { "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタンの列として表示されます（入力欄は引き続き使用できます）。無効にすると、現在のオーバーレイパネルが維持されます。段階的なロールアウト用のスイッチで、いつでも無効にして以前の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、続行ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎスイッチの制御を受けます（グローバルスイッチが無効の場合は、すべて無効になります）。MaiGPT ではこのスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは、別途「コンテキスト使用量を表示」で制御します。デフォルトは無効で、顧客向けの webchat には引き継ぎ UI が表示されません。段階的なロールアウト用のスイッチで、無効にするとすぐに以前の動作に戻り、リリースのロールバックは不要です。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で、入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバルな引き継ぎスイッチを含む）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT ではこのスイッチに関係なく常に表示されます。デフォルトは無効です。無効にするとすぐに以前の動作に戻り、リリースのロールバックは不要です。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3-60 分です。 (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI 応答からアンケートが表示されるまでの時間（分）です。範囲は 1-60 分です。 (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズします。空欄の場合は、フロントエンドの言語別のデフォルトテキストを使用します。 (任意) "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "conversationStartersDisplayCount"?: integer // 任意 "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 } ``` **リクエスト値の例** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PUT "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト内容 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.put("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト内容 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": True, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "enableFileUpload": True, "enableDisplayCitations": True, "toolDisplayMode": "full", "enableAskOptionButtons": True, "enableConversationHandoff": True, "enableDisplayContextUsage": True, "enableDisplayThinking": True, "enableUserThinkingControl": True, "enableDisplayQueryMetadata": True, "enableDisplayHookMarkers": True, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": True, "enableLocation": True, "enableShowPoweredBy": True, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": True, "enableDisplayPreviousConversation": True, "enableDisplayConversationHistory": True, "enableConversationTimer": True, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": True, "enableSatisfactionSurvey": True, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": True, "enableDisplayChatbotName": True, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": True, "preChatFormFields": None, "preChatFormTitle": None, "preChatFormSubtitle": None, "loadingDisplayMode": {}, "loadingStageCopyByLocale": None, "loadingLongWaitCopyByLocale": None, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": True, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": None, "loadingTypingShowCopy": True, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.put(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php put("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'avatar' => 'https://example.com/file.jpg', 'logo' => 'https://example.com/file.jpg', 'description' => 'サンプル文字列', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'サンプル文字列', 'isActive' => true, 'theme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'enableFileUpload' => true, 'enableDisplayCitations' => true, 'toolDisplayMode' => 'full', 'enableAskOptionButtons' => true, 'enableConversationHandoff' => true, 'enableDisplayContextUsage' => true, 'enableDisplayThinking' => true, 'enableUserThinkingControl' => true, 'enableDisplayQueryMetadata' => true, 'enableDisplayHookMarkers' => true, 'hookMarkerTextInputModify' => 'サンプル文字列', 'hookMarkerTextOutputModify' => 'サンプル文字列', 'hookMarkerTextInputBlock' => 'サンプル文字列', 'hookMarkerTextOutputBlock' => 'サンプル文字列', 'enableShareConversation' => true, 'enableLocation' => true, 'enableShowPoweredBy' => true, 'poweredByLogo' => 'https://example.com/file.jpg', 'enableAnonymous' => true, 'enableDisplayPreviousConversation' => true, 'enableDisplayConversationHistory' => true, 'enableConversationTimer' => true, 'conversationTimerDuration' => 123, 'enableAutoNewConversationOnTimeout' => true, 'enableSatisfactionSurvey' => true, 'satisfactionSurveyDelayMinutes' => 123, 'satisfactionSurveyPrompt' => 'サンプル文字列', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'サンプル文字列' ], 'enableDisplayChatbotAvatar' => true, 'enableDisplayChatbotName' => true, 'buttonIcon' => 'https://example.com/file.jpg', 'conversationStartersDisplayCount' => 123, 'preChatFormEnabled' => true, 'preChatFormFields' => null, 'preChatFormTitle' => null, 'preChatFormSubtitle' => null, 'loadingDisplayMode' => new \stdClass(), 'loadingStageCopyByLocale' => null, 'loadingLongWaitCopyByLocale' => null, 'loadingLongWaitThresholdSeconds' => 123, 'loadingAnimationUseSharedAsset' => true, 'loadingAnimationSharedAssetUrl' => 'https://example.com/file.jpg', 'loadingAnimationAssetUrlsByStage' => null, 'loadingTypingShowCopy' => true, 'toolCardRunningIconUrl' => 'https://example.com/file.jpg', 'toolCardCompletedIconUrl' => 'https://example.com/file.jpg' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示されます（入力欄は引き続き使用できます）。無効にすると、従来のオーバーレイパネルを使用します。段階的なロールアウト用のスイッチで、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、再開ボタン）を表示し、引き継ぎツールを登録します。ただし、システム設定のグローバルな引き継ぎスイッチにも従います（グローバルスイッチが無効の場合はすべて無効になります）。MaiGPT ではこのスイッチに関係なく常に表示します。下部のコンテキスト使用率バーは、別途「コンテキスト使用量の表示」で制御します。デフォルトは無効で、顧客向けの公開 webchat には引き継ぎ UI を表示しません。段階的なロールアウト用のスイッチで、無効にすると即座に元の動作に戻り、バージョンのロールバックは不要です。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーを表示します。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバルな引き継ぎスイッチを含む）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT ではこのスイッチに関係なく常に表示します。デフォルトは無効です。無効にすると即座に元の動作に戻り、バージョンのロールバックは不要です。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3-60 分です。 (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI の返信からアンケートを表示するまでの分数です。範囲は 1-60 分です。 (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズします。空欄の場合はフロントエンドの各言語のデフォルトテキストを使用します。 (任意) "accessType": { } "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 任意 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "応答文字列", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "応答文字列", "cover": "https://example.com/file.jpg", "backUrl": "応答文字列", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "応答文字列" ], "theme": { "primaryColor": "応答文字列", "navbarTextColor": "応答文字列", "conversationBackgroundColor": "応答文字列", "chatbotMessageTextColor": "応答文字列", "userMessageTextColor": "応答文字列", "chatbotMessageBackgroundColor": "応答文字列", "userMessageBackgroundColor": "応答文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "応答文字列", "navbarTextColor": "応答文字列", "conversationBackgroundColor": "応答文字列", "chatbotMessageTextColor": "応答文字列", "userMessageTextColor": "応答文字列", "chatbotMessageBackgroundColor": "応答文字列", "userMessageBackgroundColor": "応答文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableConversationHandoff": false, "enableDisplayContextUsage": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "応答文字列", "hookMarkerTextOutputModify": "応答文字列", "hookMarkerTextInputBlock": "応答文字列", "hookMarkerTextOutputBlock": "応答文字列", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "応答文字列", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "応答文字列", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "応答名の例", "description": "応答説明の例" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "応答名の例", "description": "応答説明の例" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "応答名の例", "description": "応答説明の例" } } ``` *** ### Web Chat の部分更新 PATCH `/api/v1/web-chats/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ----------------------------------------------- | ------------------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | avatar | string (uri) | いいえ | | | logo | string (uri) | いいえ | | | description | string | いいえ | | | cover | string (uri) | いいえ | | | backUrl | string | いいえ | | | isActive | boolean | いいえ | | | theme | object | いいえ | | | theme.primaryColor | string | いいえ | | | theme.navbarTextColor | string | いいえ | | | theme.conversationBackgroundColor | string | いいえ | | | theme.chatbotMessageTextColor | string | いいえ | | | theme.userMessageTextColor | string | いいえ | | | theme.chatbotMessageBackgroundColor | string | いいえ | | | theme.userMessageBackgroundColor | string | いいえ | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.chatbotMessageGradientEnabled | boolean | いいえ | | | theme.userMessageGradientEnabled | boolean | いいえ | | | darkTheme | object | いいえ | | | darkTheme.primaryColor | string | いいえ | | | darkTheme.navbarTextColor | string | いいえ | | | darkTheme.conversationBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageTextColor | string | いいえ | | | darkTheme.userMessageTextColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundColor | string | いいえ | | | darkTheme.userMessageBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.chatbotMessageGradientEnabled | boolean | いいえ | | | darkTheme.userMessageGradientEnabled | boolean | いいえ | | | enableFileUpload | boolean | いいえ | | | enableDisplayCitations | boolean | いいえ | | | toolDisplayMode | string (enum: full, compact, hidden) | いいえ | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | いいえ | 有効にすると、ask\_user\_question の選択肢が入力欄の上にボタン列として表示され、入力欄は引き続き使用できます。無効にすると、従来のオーバーレイパネルが維持されます。段階的な展開用の切り替え設定で、いつでも無効にして元の動作に戻せます。 | | enableConversationHandoff | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、続行ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎ設定にも従い、グローバル設定が無効の場合はすべて無効になります。MaiGPT では、このプラットフォーム設定にかかわらず常に表示されます。下部のコンテキスト使用率バーは、別の「コンテキスト使用量を表示」設定で制御されます。デフォルトでは無効で、顧客向けの webchat に引き継ぎ UI は表示されません。段階的な展開用の切り替え設定で、無効にするとリリースをロールバックせずに元の動作に戻せます。 | | enableDisplayContextUsage | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、グローバル設定を含む引き継ぎ設定の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT では、この設定にかかわらず常に表示されます。デフォルトでは無効です。無効にすると、リリースをロールバックせずに元の動作に戻せます。 | | enableDisplayThinking | boolean | いいえ | | | enableUserThinkingControl | boolean | いいえ | | | enableDisplayQueryMetadata | boolean | いいえ | | | enableDisplayHookMarkers | boolean | いいえ | | | hookMarkerTextInputModify | string | いいえ | | | hookMarkerTextOutputModify | string | いいえ | | | hookMarkerTextInputBlock | string | いいえ | | | hookMarkerTextOutputBlock | string | いいえ | | | enableShareConversation | boolean | いいえ | | | enableLocation | boolean | いいえ | | | enableShowPoweredBy | boolean | いいえ | | | poweredByLogo | string (uri) | いいえ | | | enableAnonymous | boolean | いいえ | | | enableDisplayPreviousConversation | boolean | いいえ | | | enableDisplayConversationHistory | boolean | いいえ | | | enableConversationTimer | boolean | いいえ | | | conversationTimerDuration | integer | いいえ | タイマーのタイムアウト時間です。範囲は 3-60 分です。 | | enableAutoNewConversationOnTimeout | boolean | いいえ | | | enableSatisfactionSurvey | boolean | いいえ | | | satisfactionSurveyDelayMinutes | integer | いいえ | 最後の AI 応答からアンケートが表示されるまでの分数です。範囲は 1-60 分です。 | | satisfactionSurveyPrompt | string | いいえ | アンケートのタイトルをカスタマイズするテキストです。空欄の場合は、フロントエンドの各言語のデフォルトテキストが使用されます。 | | enableThemeModeToggle | boolean | いいえ | | | enableDisplayFontSizeSwitch | boolean | いいえ | | | defaultThemeMode | object | いいえ | | | enableDownloadCitations | boolean | いいえ | | | customDomain | object (3 つのプロパティを含みます: id, domain, status) | いいえ | | | customDomain.domain | string | はい | | | enableDisplayChatbotAvatar | boolean | いいえ | | | enableDisplayChatbotName | boolean | いいえ | | | buttonIcon | string (uri) | いいえ | | | conversationStartersDisplayCount | integer | いいえ | | | preChatFormEnabled | boolean | いいえ | | | preChatFormFields | object | いいえ | | | preChatFormTitle | object | いいえ | | | preChatFormSubtitle | object | いいえ | | | loadingDisplayMode | object | いいえ | Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured beh... | | loadingStageCopyByLocale | object | いいえ | Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a... | | loadingLongWaitCopyByLocale | object | いいえ | Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt... | | loadingLongWaitThresholdSeconds | integer | いいえ | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | いいえ | True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ... | | loadingAnimationSharedAssetUrl | string (uri) | いいえ | | | loadingAnimationAssetUrlsByStage | object | いいえ | Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. | | loadingTypingShowCopy | boolean | いいえ | Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line.... | | toolCardRunningIconUrl | string (uri) | いいえ | | | toolCardCompletedIconUrl | string (uri) | いいえ | | **リクエスト構造の例** ```typescript { "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "theme"?: { // 任意 { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme"?: { // 任意 { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示され、入力欄は引き続き使用できます。無効にすると、従来のオーバーレイパネルが維持されます。段階的な展開用の切り替え設定で、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、続行ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎ設定にも従い、グローバル設定が無効の場合はすべて無効になります。MaiGPT では、このプラットフォーム設定にかかわらず常に表示されます。下部のコンテキスト使用率バーは、別の「コンテキスト使用量を表示」設定で制御されます。デフォルトでは無効で、顧客向けの webchat に引き継ぎ UI は表示されません。段階的な展開用の切り替え設定で、無効にするとリリースをロールバックせずに元の動作に戻せます。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、グローバル設定を含む引き継ぎ設定の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT では、この設定にかかわらず常に表示されます。デフォルトでは無効です。無効にすると、リリースをロールバックせずに元の動作に戻せます。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3-60 分です。 (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI 応答からアンケートが表示されるまでの分数です。範囲は 1-60 分です。 (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズするテキストです。空欄の場合は、フロントエンドの各言語のデフォルトテキストが使用されます。 (任意) "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "conversationStartersDisplayCount"?: integer // 任意 "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 } ``` **リクエスト値の例** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト本文 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.patch("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('応答を正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト本文 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": True, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "enableFileUpload": True, "enableDisplayCitations": True, "toolDisplayMode": "full", "enableAskOptionButtons": True, "enableConversationHandoff": True, "enableDisplayContextUsage": True, "enableDisplayThinking": True, "enableUserThinkingControl": True, "enableDisplayQueryMetadata": True, "enableDisplayHookMarkers": True, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": True, "enableLocation": True, "enableShowPoweredBy": True, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": True, "enableDisplayPreviousConversation": True, "enableDisplayConversationHistory": True, "enableConversationTimer": True, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": True, "enableSatisfactionSurvey": True, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": True, "enableDisplayChatbotName": True, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": True, "preChatFormFields": None, "preChatFormTitle": None, "preChatFormSubtitle": None, "loadingDisplayMode": {}, "loadingStageCopyByLocale": None, "loadingLongWaitCopyByLocale": None, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": True, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": None, "loadingTypingShowCopy": True, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.patch(url, json=data, headers=headers) try: print("応答を正常に取得しました:") print(response.json()) except Exception as e: print("リクエストエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'avatar' => 'https://example.com/file.jpg', 'logo' => 'https://example.com/file.jpg', 'description' => 'サンプル文字列', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'サンプル文字列', 'isActive' => true, 'theme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'enableFileUpload' => true, 'enableDisplayCitations' => true, 'toolDisplayMode' => 'full', 'enableAskOptionButtons' => true, 'enableConversationHandoff' => true, 'enableDisplayContextUsage' => true, 'enableDisplayThinking' => true, 'enableUserThinkingControl' => true, 'enableDisplayQueryMetadata' => true, 'enableDisplayHookMarkers' => true, 'hookMarkerTextInputModify' => 'サンプル文字列', 'hookMarkerTextOutputModify' => 'サンプル文字列', 'hookMarkerTextInputBlock' => 'サンプル文字列', 'hookMarkerTextOutputBlock' => 'サンプル文字列', 'enableShareConversation' => true, 'enableLocation' => true, 'enableShowPoweredBy' => true, 'poweredByLogo' => 'https://example.com/file.jpg', 'enableAnonymous' => true, 'enableDisplayPreviousConversation' => true, 'enableDisplayConversationHistory' => true, 'enableConversationTimer' => true, 'conversationTimerDuration' => 123, 'enableAutoNewConversationOnTimeout' => true, 'enableSatisfactionSurvey' => true, 'satisfactionSurveyDelayMinutes' => 123, 'satisfactionSurveyPrompt' => 'サンプル文字列', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'サンプル文字列' ], 'enableDisplayChatbotAvatar' => true, 'enableDisplayChatbotName' => true, 'buttonIcon' => 'https://example.com/file.jpg', 'conversationStartersDisplayCount' => 123, 'preChatFormEnabled' => true, 'preChatFormFields' => null, 'preChatFormTitle' => null, 'preChatFormSubtitle' => null, 'loadingDisplayMode' => new \stdClass(), 'loadingStageCopyByLocale' => null, 'loadingLongWaitCopyByLocale' => null, 'loadingLongWaitThresholdSeconds' => 123, 'loadingAnimationUseSharedAsset' => true, 'loadingAnimationSharedAssetUrl' => 'https://example.com/file.jpg', 'loadingAnimationAssetUrlsByStage' => null, 'loadingTypingShowCopy' => true, 'toolCardRunningIconUrl' => 'https://example.com/file.jpg', 'toolCardCompletedIconUrl' => 'https://example.com/file.jpg' ] ]); $data = json_decode($response->getBody(), true); echo "応答を正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### 応答内容 **ステータスコード: 200** **応答スキーマの例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示され、入力欄は引き続き使用できます。無効の場合は既存のオーバーレイパネルを使用します。段階的なロールアウト用のスイッチで、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、継続ボタン）が表示され、引き継ぎツールが登録されます。システム設定のグローバル引き継ぎスイッチにも制御され、グローバル設定が無効の場合はすべて無効になります。MaiGPT ではこのスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは「コンテキスト使用量を表示」で別途制御されます。デフォルトは無効で、顧客向けの webchat に引き継ぎ UI は表示されません。段階的なロールアウト用のスイッチで、無効にすればリリースをロールバックせずに元の動作に戻せます。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバル引き継ぎスイッチを含む）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT ではこのスイッチに関係なく常に表示されます。デフォルトは無効で、無効にすればリリースをロールバックせずに元の動作に戻せます。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3-60 分です。 (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI 応答からアンケートが表示されるまでの時間です。範囲は 1-60 分です。 (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズできます。空欄の場合はフロントエンドの各言語のデフォルトテキストを使用します。 (任意) "accessType": { } "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 任意 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "レスポンス文字列", "cover": "https://example.com/file.jpg", "backUrl": "レスポンス文字列", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "レスポンス文字列" ], "theme": { "primaryColor": "レスポンス文字列", "navbarTextColor": "レスポンス文字列", "conversationBackgroundColor": "レスポンス文字列", "chatbotMessageTextColor": "レスポンス文字列", "userMessageTextColor": "レスポンス文字列", "chatbotMessageBackgroundColor": "レスポンス文字列", "userMessageBackgroundColor": "レスポンス文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "レスポンス文字列", "navbarTextColor": "レスポンス文字列", "conversationBackgroundColor": "レスポンス文字列", "chatbotMessageTextColor": "レスポンス文字列", "userMessageTextColor": "レスポンス文字列", "chatbotMessageBackgroundColor": "レスポンス文字列", "userMessageBackgroundColor": "レスポンス文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableConversationHandoff": false, "enableDisplayContextUsage": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "レスポンス文字列", "hookMarkerTextOutputModify": "レスポンス文字列", "hookMarkerTextInputBlock": "レスポンス文字列", "hookMarkerTextOutputBlock": "レスポンス文字列", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "レスポンス文字列", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "レスポンス文字列", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" } } ``` *** ### 連絡先の認証情報の設定 POST `/api/v1/web-chats/{id}/setup-contact-credentials/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ---------------------- | ---------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | sourceId | string | はい | Unique identifier for the contact | | name | string | いいえ | Contact display name | | mcpCredentials | object (2 個のプロパティを含みます: toolId, headers) | いいえ | MCP credentials configuration | | mcpCredentials.toolId | string (uuid) | はい | MCP Tool ID | | mcpCredentials.headers | object | いいえ | Authentication headers | | embedOrigin | string | いいえ | Origin of the embedding page (forwarded by the web chat frontend) for allowlist validation | | ts | integer | いいえ | Unix timestamp (seconds, UTC) the signature was computed with. Required when the inbox login settings enable Source ID access with signature verification. | | sig | string | いいえ | Hex HMAC-SHA256 of "{webChatId}.{sourceId}.{ts}" computed by the embedding site backend | **リクエスト構造の例** ```typescript { "sourceId": string // Unique identifier for the contact "name"?: string // Contact display name (任意) "mcpCredentials"?: // MCP credentials configuration (任意) { "toolId": string (uuid) // MCP Tool ID "headers"?: object // Authentication headers (任意) } "embedOrigin"?: string // Origin of the embedding page (forwarded by the web chat frontend) for allowlist validation (任意) "ts"?: integer // Unix timestamp (seconds, UTC) the signature was computed with. Required when the inbox login settings enable Source ID access with signature verification. (任意) "sig"?: string // Hex HMAC-SHA256 of "{webChatId}.{sourceId}.{ts}" computed by the embedding site backend (任意) } ``` **リクエストの値の例** ```json { "sourceId": "サンプル文字列", "name": "サンプル名", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "サンプル文字列", "ts": 123, "sig": "サンプル文字列" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sourceId": "サンプル文字列", "name": "サンプル名", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "サンプル文字列", "ts": 123, "sig": "サンプル文字列" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーの設定 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト内容 (payload) const data = { "sourceId": "サンプル文字列", "name": "サンプル名", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "サンプル文字列", "ts": 123, "sig": "サンプル文字列" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/", data, config) .then(response => { console.log('応答を正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト内容 (payload) data = { "sourceId": "サンプル文字列", "name": "サンプル名", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "サンプル文字列", "ts": 123, "sig": "サンプル文字列" } response = requests.post(url, json=data, headers=headers) try: print("応答を正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'sourceId' => 'サンプル文字列', 'name' => 'サンプル名', 'mcpCredentials' => [ 'toolId' => '550e8400-e29b-41d4-a716-446655440000', 'headers' => new \stdClass() ], 'embedOrigin' => 'サンプル文字列', 'ts' => 123, 'sig' => 'サンプル文字列' ] ]); $data = json_decode($response->getBody(), true); echo "応答を正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "contactId": string (uuid) // The created or existing contact ID "created": boolean // Whether the contact was created by this call. False means an existing contact matched the source_id; in that case the request name is not applied (update names via PATCH /contacts/{id}/). } ``` **レスポンスの値の例** ```json { "contactId": "550e8400-e29b-41d4-a716-446655440000", "created": false } ``` **ステータスコード: 400 - No response body** *** ### 音声アシスタントの Token の取得 POST `/api/v1/web-chats/{id}/voice-agent/token/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ----------------------------------------------- | ------------------------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | avatar | string (uri) | いいえ | | | logo | string (uri) | いいえ | | | description | string | いいえ | | | cover | string (uri) | いいえ | | | backUrl | string | いいえ | | | isActive | boolean | いいえ | | | theme | object | はい | | | theme.primaryColor | string | いいえ | | | theme.navbarTextColor | string | いいえ | | | theme.conversationBackgroundColor | string | いいえ | | | theme.chatbotMessageTextColor | string | いいえ | | | theme.userMessageTextColor | string | いいえ | | | theme.chatbotMessageBackgroundColor | string | いいえ | | | theme.userMessageBackgroundColor | string | いいえ | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | theme.chatbotMessageGradientEnabled | boolean | いいえ | | | theme.userMessageGradientEnabled | boolean | いいえ | | | darkTheme | object | はい | | | darkTheme.primaryColor | string | いいえ | | | darkTheme.navbarTextColor | string | いいえ | | | darkTheme.conversationBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageTextColor | string | いいえ | | | darkTheme.userMessageTextColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundColor | string | いいえ | | | darkTheme.userMessageBackgroundColor | string | いいえ | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | いいえ | | | darkTheme.chatbotMessageGradientEnabled | boolean | いいえ | | | darkTheme.userMessageGradientEnabled | boolean | いいえ | | | enableFileUpload | boolean | いいえ | | | enableDisplayCitations | boolean | いいえ | | | toolDisplayMode | string (enum: full, compact, hidden) | いいえ | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | いいえ | 有効にすると、ask\_user\_question の選択肢が入力欄の上にボタン列として表示され、入力欄は引き続き使用できます。無効にすると、従来のオーバーレイパネルが維持されます。段階的なロールアウト用のスイッチで、いつでも無効にして元の動作に戻せます。 | | enableConversationHandoff | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、継続ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎスイッチによる制御は引き続き適用されます（グローバル設定が無効の場合はすべて無効になります）。MaiGPT ではこのスイッチにかかわらず常に表示されます。下部のコンテキスト使用量の割合を示すバーは、「コンテキスト使用量の表示」で個別に制御されます。デフォルトでは無効で、顧客が公開する webchat には引き継ぎ UI は表示されません。段階的なロールアウト用のスイッチで、リリースをロールバックせずに無効にするだけで元の動作に戻せます。 | | enableDisplayContextUsage | boolean | いいえ | 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用量の割合を示すバーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバルな引き継ぎスイッチを含みます）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT ではこのスイッチにかかわらず常に表示されます。デフォルトでは無効です。リリースをロールバックせずに無効にするだけで元の動作に戻せます。 | | enableDisplayThinking | boolean | いいえ | | | enableUserThinkingControl | boolean | いいえ | | | enableDisplayQueryMetadata | boolean | いいえ | | | enableDisplayHookMarkers | boolean | いいえ | | | hookMarkerTextInputModify | string | いいえ | | | hookMarkerTextOutputModify | string | いいえ | | | hookMarkerTextInputBlock | string | いいえ | | | hookMarkerTextOutputBlock | string | いいえ | | | enableShareConversation | boolean | いいえ | | | enableLocation | boolean | いいえ | | | enableShowPoweredBy | boolean | いいえ | | | poweredByLogo | string (uri) | いいえ | | | enableAnonymous | boolean | いいえ | | | enableDisplayPreviousConversation | boolean | いいえ | | | enableDisplayConversationHistory | boolean | いいえ | | | enableConversationTimer | boolean | いいえ | | | conversationTimerDuration | integer | いいえ | タイマーのタイムアウト時間です。範囲は 3～60 分です。 | | enableAutoNewConversationOnTimeout | boolean | いいえ | | | enableSatisfactionSurvey | boolean | いいえ | | | satisfactionSurveyDelayMinutes | integer | いいえ | 最後の AI 応答からアンケートを表示するまでの時間（分）です。範囲は 1～60 分です。 | | satisfactionSurveyPrompt | string | いいえ | アンケートのタイトルをカスタマイズできます。空欄の場合は、フロントエンドの各言語のデフォルトテキストを使用します。 | | enableThemeModeToggle | boolean | いいえ | | | enableDisplayFontSizeSwitch | boolean | いいえ | | | defaultThemeMode | object | いいえ | | | enableDownloadCitations | boolean | いいえ | | | customDomain | object (3 個のプロパティを含みます: id, domain, status) | いいえ | | | customDomain.domain | string | はい | | | enableDisplayChatbotAvatar | boolean | いいえ | | | enableDisplayChatbotName | boolean | いいえ | | | buttonIcon | string (uri) | いいえ | | | conversationStartersDisplayCount | integer | いいえ | | | preChatFormEnabled | boolean | いいえ | | | preChatFormFields | object | いいえ | | | preChatFormTitle | object | いいえ | | | preChatFormSubtitle | object | いいえ | | | loadingDisplayMode | object | いいえ | Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured beh... | | loadingStageCopyByLocale | object | いいえ | Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid a... | | loadingLongWaitCopyByLocale | object | いいえ | Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empt... | | loadingLongWaitThresholdSeconds | integer | いいえ | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | いいえ | True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is ... | | loadingAnimationSharedAssetUrl | string (uri) | いいえ | | | loadingAnimationAssetUrlsByStage | object | いいえ | Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. | | loadingTypingShowCopy | boolean | いいえ | Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line.... | | toolCardRunningIconUrl | string (uri) | いいえ | | | toolCardCompletedIconUrl | string (uri) | いいえ | | **リクエスト構造の例** ```typescript { "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示されます（入力欄は引き続き使用できます）。無効にすると、従来のオーバーレイパネルを使用します。段階的なロールアウト用のスイッチで、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、続行ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバルな引き継ぎスイッチによる制御は引き続き適用されます（グローバル設定が無効の場合、すべて無効になります）。MaiGPT では、このスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは、別途「コンテキスト使用量を表示」で制御します。デフォルトでは無効で、顧客向けの webchat に引き継ぎ UI は表示されません。段階的なロールアウト用のスイッチで、無効にすると元の動作に戻り、リリースをロールバックする必要はありません。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しています。引き継ぎスイッチ（グローバルな引き継ぎスイッチを含みます）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT では、このスイッチに関係なく常に表示されます。デフォルトでは無効です。無効にすると元の動作に戻り、リリースをロールバックする必要はありません。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーのタイムアウト時間です。範囲は 3-60 分です (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI の応答からアンケートが表示されるまでの時間（分）です。範囲は 1-60 分です (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズできます。空欄の場合、フロントエンドの各言語のデフォルトテキストを使用します (任意) "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "domain": string } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "conversationStartersDisplayCount"?: integer // 任意 "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 } ``` **リクエストのサンプル値** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト本文 (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": true, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "enableFileUpload": true, "enableDisplayCitations": true, "toolDisplayMode": "full", "enableAskOptionButtons": true, "enableConversationHandoff": true, "enableDisplayContextUsage": true, "enableDisplayThinking": true, "enableUserThinkingControl": true, "enableDisplayQueryMetadata": true, "enableDisplayHookMarkers": true, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": true, "enableLocation": true, "enableShowPoweredBy": true, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": true, "enableDisplayPreviousConversation": true, "enableDisplayConversationHistory": true, "enableConversationTimer": true, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": true, "enableSatisfactionSurvey": true, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": true, "enableDisplayChatbotName": true, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": true, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": true, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": true, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/", data, config) .then(response => { console.log('応答を正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト本文 (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "サンプル文字列", "cover": "https://example.com/file.jpg", "backUrl": "サンプル文字列", "isActive": True, "theme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "サンプル文字列", "navbarTextColor": "サンプル文字列", "conversationBackgroundColor": "サンプル文字列", "chatbotMessageTextColor": "サンプル文字列", "userMessageTextColor": "サンプル文字列", "chatbotMessageBackgroundColor": "サンプル文字列", "userMessageBackgroundColor": "サンプル文字列", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "enableFileUpload": True, "enableDisplayCitations": True, "toolDisplayMode": "full", "enableAskOptionButtons": True, "enableConversationHandoff": True, "enableDisplayContextUsage": True, "enableDisplayThinking": True, "enableUserThinkingControl": True, "enableDisplayQueryMetadata": True, "enableDisplayHookMarkers": True, "hookMarkerTextInputModify": "サンプル文字列", "hookMarkerTextOutputModify": "サンプル文字列", "hookMarkerTextInputBlock": "サンプル文字列", "hookMarkerTextOutputBlock": "サンプル文字列", "enableShareConversation": True, "enableLocation": True, "enableShowPoweredBy": True, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": True, "enableDisplayPreviousConversation": True, "enableDisplayConversationHistory": True, "enableConversationTimer": True, "conversationTimerDuration": 123, "enableAutoNewConversationOnTimeout": True, "enableSatisfactionSurvey": True, "satisfactionSurveyDelayMinutes": 123, "satisfactionSurveyPrompt": "サンプル文字列", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "サンプル文字列" }, "enableDisplayChatbotAvatar": True, "enableDisplayChatbotName": True, "buttonIcon": "https://example.com/file.jpg", "conversationStartersDisplayCount": 123, "preChatFormEnabled": True, "preChatFormFields": None, "preChatFormTitle": None, "preChatFormSubtitle": None, "loadingDisplayMode": {}, "loadingStageCopyByLocale": None, "loadingLongWaitCopyByLocale": None, "loadingLongWaitThresholdSeconds": 123, "loadingAnimationUseSharedAsset": True, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": None, "loadingTypingShowCopy": True, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg" } response = requests.post(url, json=data, headers=headers) try: print("応答を正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/voice-agent/token/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'avatar' => 'https://example.com/file.jpg', 'logo' => 'https://example.com/file.jpg', 'description' => 'サンプル文字列', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'サンプル文字列', 'isActive' => true, 'theme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'サンプル文字列', 'navbarTextColor' => 'サンプル文字列', 'conversationBackgroundColor' => 'サンプル文字列', 'chatbotMessageTextColor' => 'サンプル文字列', 'userMessageTextColor' => 'サンプル文字列', 'chatbotMessageBackgroundColor' => 'サンプル文字列', 'userMessageBackgroundColor' => 'サンプル文字列', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'enableFileUpload' => true, 'enableDisplayCitations' => true, 'toolDisplayMode' => 'full', 'enableAskOptionButtons' => true, 'enableConversationHandoff' => true, 'enableDisplayContextUsage' => true, 'enableDisplayThinking' => true, 'enableUserThinkingControl' => true, 'enableDisplayQueryMetadata' => true, 'enableDisplayHookMarkers' => true, 'hookMarkerTextInputModify' => 'サンプル文字列', 'hookMarkerTextOutputModify' => 'サンプル文字列', 'hookMarkerTextInputBlock' => 'サンプル文字列', 'hookMarkerTextOutputBlock' => 'サンプル文字列', 'enableShareConversation' => true, 'enableLocation' => true, 'enableShowPoweredBy' => true, 'poweredByLogo' => 'https://example.com/file.jpg', 'enableAnonymous' => true, 'enableDisplayPreviousConversation' => true, 'enableDisplayConversationHistory' => true, 'enableConversationTimer' => true, 'conversationTimerDuration' => 123, 'enableAutoNewConversationOnTimeout' => true, 'enableSatisfactionSurvey' => true, 'satisfactionSurveyDelayMinutes' => 123, 'satisfactionSurveyPrompt' => 'サンプル文字列', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'サンプル文字列' ], 'enableDisplayChatbotAvatar' => true, 'enableDisplayChatbotName' => true, 'buttonIcon' => 'https://example.com/file.jpg', 'conversationStartersDisplayCount' => 123, 'preChatFormEnabled' => true, 'preChatFormFields' => null, 'preChatFormTitle' => null, 'preChatFormSubtitle' => null, 'loadingDisplayMode' => new \stdClass(), 'loadingStageCopyByLocale' => null, 'loadingLongWaitCopyByLocale' => null, 'loadingLongWaitThresholdSeconds' => 123, 'loadingAnimationUseSharedAsset' => true, 'loadingAnimationSharedAssetUrl' => 'https://example.com/file.jpg', 'loadingAnimationAssetUrlsByStage' => null, 'loadingTypingShowCopy' => true, 'toolCardRunningIconUrl' => 'https://example.com/file.jpg', 'toolCardCompletedIconUrl' => 'https://example.com/file.jpg' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // 任意 "logo"?: string (uri) // 任意 "description"?: string // 任意 "cover"?: string (uri) // 任意 "backUrl"?: string // 任意 "isActive"?: boolean // 任意 "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "darkTheme": { { "primaryColor"?: string // 任意 "navbarTextColor"?: string // 任意 "conversationBackgroundColor"?: string // 任意 "chatbotMessageTextColor"?: string // 任意 "userMessageTextColor"?: string // 任意 "chatbotMessageBackgroundColor"?: string // 任意 "userMessageBackgroundColor"?: string // 任意 "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意 "userMessageBackgroundShadowEnabled"?: boolean // 任意 "chatbotMessageGradientEnabled"?: boolean // 任意 "userMessageGradientEnabled"?: boolean // 任意 } } "enableFileUpload"?: boolean // 任意 "enableDisplayCitations"?: boolean // 任意 "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (任意) "enableAskOptionButtons"?: boolean // 有効にすると、ask_user_question の選択肢が入力欄の上にボタン列として表示され、入力欄は引き続き使用できます。無効にすると、従来のオーバーレイパネルが使用されます。段階的な展開用のスイッチで、いつでも無効にして元の動作に戻せます。 (任意) "enableConversationHandoff"?: boolean // 有効にすると、この会話プラットフォームの webchat に引き継ぎ UI（通知バー、要約カード、続行ボタン）が表示され、引き継ぎツールが登録されます。ただし、システム設定のグローバル引き継ぎスイッチによる制御は引き続き適用されます（グローバルスイッチが無効の場合は、すべて無効になります）。MaiGPT ではこのスイッチに関係なく常に表示されます。下部のコンテキスト使用率バーは、別途「コンテキスト使用量の表示」で制御されます。デフォルトでは無効のため、顧客向けの webchat に引き継ぎ UI は表示されません。段階的な展開用のスイッチで、無効にすると元の動作に戻り、バージョンのロールバックは不要です。 (任意) "enableDisplayContextUsage"?: boolean // 有効にすると、この会話プラットフォームの webchat で入力欄の下にコンテキスト使用率バーが表示されます。会話の引き継ぎとは独立しており、引き継ぎスイッチ（グローバル引き継ぎスイッチを含む）の影響を受けず、引き継ぎ通知バーにも影響しません。MaiGPT ではこのスイッチに関係なく常に表示されます。デフォルトでは無効です。無効にすると元の動作に戻り、バージョンのロールバックは不要です。 (任意) "enableDisplayThinking"?: boolean // 任意 "enableUserThinkingControl"?: boolean // 任意 "enableDisplayQueryMetadata"?: boolean // 任意 "enableDisplayHookMarkers"?: boolean // 任意 "hookMarkerTextInputModify"?: string // 任意 "hookMarkerTextOutputModify"?: string // 任意 "hookMarkerTextInputBlock"?: string // 任意 "hookMarkerTextOutputBlock"?: string // 任意 "enableShareConversation"?: boolean // 任意 "enableLocation"?: boolean // 任意 "enableShowPoweredBy"?: boolean // 任意 "poweredByLogo"?: string (uri) // 任意 "enableAnonymous"?: boolean // 任意 "enableDisplayPreviousConversation"?: boolean // 任意 "enableDisplayConversationHistory"?: boolean // 任意 "enableConversationTimer"?: boolean // 任意 "conversationTimerDuration"?: integer // タイマーがタイムアウトするまでの時間です。範囲は 3-60 分です (任意) "enableAutoNewConversationOnTimeout"?: boolean // 任意 "enableSatisfactionSurvey"?: boolean // 任意 "satisfactionSurveyDelayMinutes"?: integer // 最後の AI 応答からアンケートが表示されるまでの分数です。範囲は 1-60 分です (任意) "satisfactionSurveyPrompt"?: string // アンケートのタイトルをカスタマイズできます。空欄の場合は、フロントエンドのデフォルトの多言語テキストを使用します (任意) "accessType": { } "enableThemeModeToggle"?: boolean // 任意 "enableDisplayFontSizeSwitch"?: boolean // 任意 "defaultThemeMode"?: // 任意 { } "enableDownloadCitations"?: boolean // 任意 "customDomain"?: // 任意 { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // 任意 "enableDisplayChatbotName"?: boolean // 任意 "buttonIcon"?: string (uri) // 任意 "enableCodeInterpreter": boolean // Read enable_code_interpreter from the inbox's chatbot. "voiceAgentEnabled": boolean // Whether the bound chatbot has the voice agent turned on (read-only) "conversationStartersDisplayCount"?: integer // 任意 "includeGreetingInContext": boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. "tools": [ // Expose chatbot tools to SDK for the tool_mask selector. Name resolution prefers ``display_name`` (set on MCP tools, where ``name`` is null) and falls back to ``name`` for API tools where ``display_name`` is null. Tools missing both are skipped — SDK should never show an unnamed tool to a contact. Quick Menu tools are static input-bar UI, never an LLM tool, so masking one is meaningless. object ] "preChatFormEnabled"?: boolean // 任意 "preChatFormFields"?: object // 任意 "preChatFormTitle"?: object // 任意 "preChatFormSubtitle"?: object // 任意 "loadingDisplayMode"?: // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed. * `narrative` - Narrative copy * `brand_animation` - Brand animation (任意) { } "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意) "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意) "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意) "loadingAnimationSharedAssetUrl"?: string (uri) // 任意 "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意) "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意) "toolCardRunningIconUrl"?: string (uri) // 任意 "toolCardCompletedIconUrl"?: string (uri) // 任意 "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "レスポンス文字列", "cover": "https://example.com/file.jpg", "backUrl": "レスポンス文字列", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "レスポンス文字列" ], "theme": { "primaryColor": "レスポンス文字列", "navbarTextColor": "レスポンス文字列", "conversationBackgroundColor": "レスポンス文字列", "chatbotMessageTextColor": "レスポンス文字列", "userMessageTextColor": "レスポンス文字列", "chatbotMessageBackgroundColor": "レスポンス文字列", "userMessageBackgroundColor": "レスポンス文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "レスポンス文字列", "navbarTextColor": "レスポンス文字列", "conversationBackgroundColor": "レスポンス文字列", "chatbotMessageTextColor": "レスポンス文字列", "userMessageTextColor": "レスポンス文字列", "chatbotMessageBackgroundColor": "レスポンス文字列", "userMessageBackgroundColor": "レスポンス文字列", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "enableFileUpload": false, "enableDisplayCitations": false, "toolDisplayMode": "full", "enableAskOptionButtons": false, "enableConversationHandoff": false, "enableDisplayContextUsage": false, "enableDisplayThinking": false, "enableUserThinkingControl": false, "enableDisplayQueryMetadata": false, "enableDisplayHookMarkers": false, "hookMarkerTextInputModify": "レスポンス文字列", "hookMarkerTextOutputModify": "レスポンス文字列", "hookMarkerTextInputBlock": "レスポンス文字列", "hookMarkerTextOutputBlock": "レスポンス文字列", "enableShareConversation": false, "enableLocation": false, "enableShowPoweredBy": false, "poweredByLogo": "https://example.com/file.jpg", "enableAnonymous": false, "enableDisplayPreviousConversation": false, "enableDisplayConversationHistory": false, "enableConversationTimer": false, "conversationTimerDuration": 456, "enableAutoNewConversationOnTimeout": false, "enableSatisfactionSurvey": false, "satisfactionSurveyDelayMinutes": 456, "satisfactionSurveyPrompt": "レスポンス文字列", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "レスポンス文字列", "status": {} }, "enableDisplayChatbotAvatar": false, "enableDisplayChatbotName": false, "buttonIcon": "https://example.com/file.jpg", "enableCodeInterpreter": false, "voiceAgentEnabled": false, "conversationStartersDisplayCount": 456, "includeGreetingInContext": false, "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" } ], "preChatFormEnabled": false, "preChatFormFields": null, "preChatFormTitle": null, "preChatFormSubtitle": null, "loadingDisplayMode": {}, "loadingStageCopyByLocale": null, "loadingLongWaitCopyByLocale": null, "loadingLongWaitThresholdSeconds": 456, "loadingAnimationUseSharedAsset": false, "loadingAnimationSharedAssetUrl": "https://example.com/file.jpg", "loadingAnimationAssetUrlsByStage": null, "loadingTypingShowCopy": false, "toolCardRunningIconUrl": "https://example.com/file.jpg", "toolCardCompletedIconUrl": "https://example.com/file.jpg", "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" } } ``` *** ### バッチ QA ファイルをアップロード POST `/api/v1/web-chats/{webchatPk}/batch-qas/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ----------- | -- | ------ | -- | | `webchatPk` | ✅ | string | | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ----- | ------------ | -- | -- | | file | string (uri) | はい | | **リクエストスキーマの例** ```typescript { "file": string (uri) } ``` **リクエストの値の例** ```json { "file": "https://example.com/file.jpg" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "file": "https://example.com/file.jpg" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "file": "https://example.com/file.jpg" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "file": "https://example.com/file.jpg" } response = requests.post(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'file' => 'https://example.com/file.jpg' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 201** **レスポンススキーマの例** ```typescript { "id": string (uuid) "file": string (uri) "createdAt": string (timestamp) } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "file": "https://example.com/file.jpg", "createdAt": "レスポンス文字列" } ``` *** ### バッチ QA を Excel にエクスポート GET `/api/v1/web-chats/{webchatPk}/batch-qas/{id}/export-excel/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ----------- | -- | ------ | ----------------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Chatbot Batch QA File. | | `webchatPk` | ✅ | string | | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/batch-qas/550e8400-e29b-41d4-a716-446655440000/export-excel/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 | ステータスコード | 説明 | | -------- | ----------------- | | 200 | Excel ファイルのダウンロード | *** ### LLM 使用統計の取得 GET `/api/v1/chatbots/{chatbotPk}/llm-usage-statistics/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ----------------- | -- | ------ | ----------------------------------------- | | `chatbotPk` | ✅ | string | A UUID string identifying this Chatbot ID | | `endDate` | ❌ | string | 終了日、形式: YYYY-MM-DD | | `startDate` | ✅ | string | 開始日、形式: YYYY-MM-DD | | `timeGranularity` | ✅ | string | 時間粒度 (day/month) | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript [ { "llmDetails": [ { "chatbotId": string (uuid) "wordsCount": integer "inputTokenUsage": integer "outputTokenUsage": integer "cacheCreationInputTokens": integer "cacheReadInputTokens": integer "totalTokenUsage": integer "llmModelId": string (uuid) "llmModelName": string "llmModelProvider": string } ] "date"?: string (date) // time_granularity=day の場合の日付 (任意) "month"?: string (date) // time_granularity=month の場合の月（その月の 1 日） (任意) "totalWordsCount": integer "totalInputTokenUsage": integer "totalOutputTokenUsage": integer "totalCacheCreationInputTokens": integer "totalCacheReadInputTokens": integer "totalTokenUsage": integer } ] ``` **レスポンスの値の例** ```json [ [ { "totalWordsCount": 511, "totalInputTokenUsage": 1200, "totalOutputTokenUsage": 300, "totalCacheCreationInputTokens": 0, "totalCacheReadInputTokens": 0, "totalTokenUsage": 1500, "month": "2025-03-01", "llmDetails": [ { "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b", "wordsCount": 511, "inputTokenUsage": 1200, "outputTokenUsage": 300, "cacheCreationInputTokens": 0, "cacheReadInputTokens": 0, "totalTokenUsage": 1500, "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383", "llmModelName": "GPT-4o-2024-08-06", "llmModelProvider": "openai" } ] } ] ] ``` **ステータスコード: 400** **レスポンス構造の例** ```typescript { "detail"?: string // 任意 "valid_types"?: [ // 任意 string ] } ``` **レスポンスの値の例** ```json [ [ { "totalWordsCount": 511, "totalInputTokenUsage": 1200, "totalOutputTokenUsage": 300, "totalCacheCreationInputTokens": 0, "totalCacheReadInputTokens": 0, "totalTokenUsage": 1500, "month": "2025-03-01", "llmDetails": [ { "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b", "wordsCount": 511, "inputTokenUsage": 1200, "outputTokenUsage": 300, "cacheCreationInputTokens": 0, "cacheReadInputTokens": 0, "totalTokenUsage": 1500, "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383", "llmModelName": "GPT-4o-2024-08-06", "llmModelProvider": "openai" } ] } ] ] ``` *** ### AI アシスタントの統計データの取得 GET `/api/v1/chatbots/{chatbotPk}/statistics/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ----------------- | -- | ------ | ----------------------------------------- | | `chatbotPk` | ✅ | string | A UUID string identifying this Chatbot ID | | `endDate` | ❌ | string | 終了日 (YYYY-MM-DD)、デフォルトは今日です | | `startDate` | ❌ | string | 開始日 (YYYY-MM-DD)、デフォルトは今日です | | `timeGranularity` | ✅ | string | 時間粒度 (hour/day/month) | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?endDate=example&startDate=example&timeGranularity=day" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?endDate=example&startDate=example&timeGranularity=day", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?endDate=example&startDate=example&timeGranularity=day" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?endDate=example&startDate=example&timeGranularity=day", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript [ { "datetime": string // タイムスタンプ（ミリ秒、文字列） "messagesCount": integer // メッセージ数 "conversationsCount": integer // 会話数 "avgMessagesPerConversation": number (double) // 会話あたりの平均メッセージ数 "avgLikesPerFeedback": number (double) // 満足度：高評価数 / (高評価数 + 低評価数)、フィードバックがない場合は 0 です "likesCount": integer // 高評価数（オープニングメッセージへのフィードバックを除きます。日／月の場合は期間内の合計です） "dislikesCount": integer // 低評価数（オープニングメッセージへのフィードバックを除きます。日／月の場合は期間内の合計です） } ] ``` **レスポンスの値の例** ```json [ { "datetime": "レスポンス文字列", "messagesCount": 456, "conversationsCount": 456, "avgMessagesPerConversation": 456, "avgLikesPerFeedback": 456, "likesCount": 456, "dislikesCount": 456 } ] ``` *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/api/ja/api-reference/dui-hua-widget.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.