> 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/en/api-reference/dui-hua-widget.md). # Chat Widget ### Create Web Chat POST `/api/v1/web-chats/` #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | avatar | string (uri) | No | | | logo | string (uri) | No | | | description | string | No | | | cover | string (uri) | No | | | backUrl | string | No | | | isActive | boolean | No | | | theme | object | Yes | | | theme.primaryColor | string | No | | | theme.navbarTextColor | string | No | | | theme.conversationBackgroundColor | string | No | | | theme.chatbotMessageTextColor | string | No | | | theme.userMessageTextColor | string | No | | | theme.chatbotMessageBackgroundColor | string | No | | | theme.userMessageBackgroundColor | string | No | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | theme.userMessageBackgroundShadowEnabled | boolean | No | | | theme.chatbotMessageGradientEnabled | boolean | No | | | theme.userMessageGradientEnabled | boolean | No | | | darkTheme | object | Yes | | | darkTheme.primaryColor | string | No | | | darkTheme.navbarTextColor | string | No | | | darkTheme.conversationBackgroundColor | string | No | | | darkTheme.chatbotMessageTextColor | string | No | | | darkTheme.userMessageTextColor | string | No | | | darkTheme.chatbotMessageBackgroundColor | string | No | | | darkTheme.userMessageBackgroundColor | string | No | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.chatbotMessageGradientEnabled | boolean | No | | | darkTheme.userMessageGradientEnabled | boolean | No | | | enableFileUpload | boolean | No | | | enableDisplayCitations | boolean | No | | | toolDisplayMode | string (enum: full, compact, hidden) | No | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | No | When enabled, ask\_user\_question options appear as a row of buttons above the input field, which remains usable. When disabled, the existing overlay panel is used. This gradual rollout switch can be disabled at any time to revert to the previous behavior. | | enableConversationHandoff | boolean | No | When enabled, the webchat for this conversation platform displays the handoff UI (notification bar, summary card, and continuation button) and registers handoff tools. It is still governed by the global handoff switch in system settings: disabling the global switch disables handoff everywhere. MaiGPT always displays the handoff UI regardless of this switch. The context usage percentage bar at the bottom is controlled separately by "Display Context Usage". Disabled by default, so customer-facing webchats show no handoff UI. This gradual rollout switch can be disabled to revert immediately without rolling back the release. | | enableDisplayContextUsage | boolean | No | When enabled, the webchat for this conversation platform displays a context usage percentage bar below the input field. It is independent of conversation handoff: handoff switches (including the global handoff switch) do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the context usage bar regardless of this switch. Disabled by default; disabling it reverts the behavior immediately without rolling back the release. | | enableDisplayThinking | boolean | No | | | enableUserThinkingControl | boolean | No | | | enableDisplayQueryMetadata | boolean | No | | | enableDisplayHookMarkers | boolean | No | | | hookMarkerTextInputModify | string | No | | | hookMarkerTextOutputModify | string | No | | | hookMarkerTextInputBlock | string | No | | | hookMarkerTextOutputBlock | string | No | | | enableShareConversation | boolean | No | | | enableLocation | boolean | No | | | enableShowPoweredBy | boolean | No | | | poweredByLogo | string (uri) | No | | | enableAnonymous | boolean | No | | | enableDisplayPreviousConversation | boolean | No | | | enableDisplayConversationHistory | boolean | No | | | enableConversationTimer | boolean | No | | | conversationTimerDuration | integer | No | Timer timeout duration, ranging from 3-60 minutes | | enableAutoNewConversationOnTimeout | boolean | No | | | enableSatisfactionSurvey | boolean | No | | | satisfactionSurveyDelayMinutes | integer | No | Minutes after the last AI reply before the survey appears, ranging from 1-60 minutes | | satisfactionSurveyPrompt | string | No | Custom survey title text. Leave blank to use the default localized text in the frontend | | enableThemeModeToggle | boolean | No | | | enableDisplayFontSizeSwitch | boolean | No | | | defaultThemeMode | object | No | | | enableDownloadCitations | boolean | No | | | customDomain | object (with 3 properties: id, domain, status) | No | | | customDomain.domain | string | Yes | | | enableDisplayChatbotAvatar | boolean | No | | | enableDisplayChatbotName | boolean | No | | | buttonIcon | string (uri) | No | | | conversationStartersDisplayCount | integer | No | | | preChatFormEnabled | boolean | No | | | preChatFormFields | object | No | | | preChatFormTitle | object | No | | | preChatFormSubtitle | object | No | | | loadingDisplayMode | object | No | 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 | No | 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 | No | 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 | No | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | No | 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) | No | | | loadingAnimationAssetUrlsByStage | object | No | 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 | No | 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) | No | | | toolCardCompletedIconUrl | string (uri) | No | | **Example Request Schema** ```typescript { "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input field, which remains usable. When disabled, the existing overlay panel is used. This gradual rollout switch can be disabled at any time to revert to the previous behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, the webchat for this conversation platform displays the handoff UI (notification bar, summary card, and continuation button) and registers handoff tools. It is still governed by the global handoff switch in system settings: disabling the global switch disables handoff everywhere. MaiGPT always displays the handoff UI regardless of this switch. The context usage percentage bar at the bottom is controlled separately by "Display Context Usage". Disabled by default, so customer-facing webchats show no handoff UI. This gradual rollout switch can be disabled to revert immediately without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, the webchat for this conversation platform displays a context usage percentage bar below the input field. It is independent of conversation handoff: handoff switches (including the global handoff switch) do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the context usage bar regardless of this switch. Disabled by default; disabling it reverts the behavior immediately without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3-60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey appears, ranging from 1-60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text. Leave blank to use the default localized text in the frontend (Optional) "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "domain": string } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "conversationStartersDisplayCount"?: integer // Optional "preChatFormEnabled"?: boolean // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional } ``` **Example Request Values** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API call (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": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Configure request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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" } # Request body (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": True, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "Example string" }, "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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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' => 'Example string', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'Example string', 'isActive' => true, 'theme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', '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' => 'Example string', 'hookMarkerTextOutputModify' => 'Example string', 'hookMarkerTextInputBlock' => 'Example string', 'hookMarkerTextOutputBlock' => 'Example string', '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' => 'Example string', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'Example string' ], '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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status code: 201** **Example Response Schema** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input field, which remains usable. When disabled, the current overlay panel is retained. This gradual rollout toggle can be disabled at any time to revert the behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, this conversation platform's webchat displays the handoff UI (notification bar, summary card, and continue button) and registers handoff tools. It remains subject to the global handoff toggle in system settings: disabling the global toggle disables handoff everywhere. MaiGPT always displays this UI regardless of this toggle. The context usage percentage bar at the bottom is controlled separately by "Display context usage". Disabled by default, so customers' public-facing webchats show no handoff UI. This gradual rollout toggle can be disabled to revert the behavior without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, this conversation platform's webchat displays a context usage percentage bar below the input field. This is independent of conversation handoff: handoff toggles (including the global handoff toggle) do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays this bar regardless of this toggle. Disabled by default; disabling it reverts the behavior without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3-60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Number of minutes after the last AI reply before the survey appears, ranging from 1-60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave blank to use the frontend's default localized text (Optional) "accessType": { } "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "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 // Optional "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 // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Response string", "cover": "https://example.com/file.jpg", "backUrl": "Response string", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "Response string" ], "theme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "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": "Response string", "hookMarkerTextOutputModify": "Response string", "hookMarkerTextInputBlock": "Response string", "hookMarkerTextOutputBlock": "Response string", "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": "Response string", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "Response string", "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": "Example response name", "description": "Example response 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": "Example response name", "description": "Example response description" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" } } ``` *** ### List Web Chats GET `/api/v1/web-chats/` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/web-chats/", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status Code: 200** **Example Response Structure** ```typescript [ { "id": string (uuid) "avatar"?: string (uri) // Optional "name": string } ] ``` **Example Response Values** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "avatar": "https://example.com/file.jpg", "name": "Response string" } ] ``` *** ### Retrieve a Specific Web Chat GET `/api/v1/web-chats/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers 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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status Code: 200** **Example Response Structure** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input field, which remains usable. When disabled, the existing overlay panel is retained. This gradual rollout switch can be disabled at any time to revert the behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, this conversation platform’s webchat displays the handoff UI (notification bar, summary card, and resume button) and registers handoff tools. The global handoff switch in system settings still applies: disabling it disables handoff everywhere. MaiGPT always displays this UI regardless of this switch. The context usage percentage bar at the bottom is controlled separately by “Display context usage”. Disabled by default, so customer-facing webchats display no handoff UI. This gradual rollout switch can be disabled to revert the behavior without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, this conversation platform’s webchat displays a context usage percentage bar below the input field. This is independent of conversation handoff: handoff switches, including the global handoff switch, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the bar regardless of this switch. Disabled by default; disabling it reverts the behavior without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, from 3 to 60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Number of minutes after the last AI reply before the survey appears, from 1 to 60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave blank to use the frontend’s default localized text (Optional) "accessType": { } "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "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 // Optional "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 // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **Example Response Values** ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Test 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": "Test 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" } } } } } ``` *** ### Update Web Chat PUT `/api/v1/web-chats/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### Request Content **Request Parameters** | Field | Type | Required | Description | | ----------------------------------------------- | -------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | avatar | string (uri) | No | | | logo | string (uri) | No | | | description | string | No | | | cover | string (uri) | No | | | backUrl | string | No | | | isActive | boolean | No | | | theme | object | Yes | | | theme.primaryColor | string | No | | | theme.navbarTextColor | string | No | | | theme.conversationBackgroundColor | string | No | | | theme.chatbotMessageTextColor | string | No | | | theme.userMessageTextColor | string | No | | | theme.chatbotMessageBackgroundColor | string | No | | | theme.userMessageBackgroundColor | string | No | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | theme.userMessageBackgroundShadowEnabled | boolean | No | | | theme.chatbotMessageGradientEnabled | boolean | No | | | theme.userMessageGradientEnabled | boolean | No | | | darkTheme | object | Yes | | | darkTheme.primaryColor | string | No | | | darkTheme.navbarTextColor | string | No | | | darkTheme.conversationBackgroundColor | string | No | | | darkTheme.chatbotMessageTextColor | string | No | | | darkTheme.userMessageTextColor | string | No | | | darkTheme.chatbotMessageBackgroundColor | string | No | | | darkTheme.userMessageBackgroundColor | string | No | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.chatbotMessageGradientEnabled | boolean | No | | | darkTheme.userMessageGradientEnabled | boolean | No | | | enableFileUpload | boolean | No | | | enableDisplayCitations | boolean | No | | | toolDisplayMode | string (enum: full, compact, hidden) | No | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | No | When enabled, ask\_user\_question options appear as a row of buttons above the input box, which remains usable. When disabled, the current overlay panel is retained. This gradual rollout toggle can be disabled at any time to revert to the previous behavior. | | enableConversationHandoff | boolean | No | When enabled, this conversation platform's webchat displays the handoff UI (notification bar, summary card, and continue button) and registers handoff tools. It remains subject to the global handoff toggle in system settings: disabling the global toggle disables handoff everywhere. MaiGPT always displays the UI regardless of this toggle. The context usage percentage bar at the bottom is controlled separately by "Display context usage". Disabled by default, so customer-facing webchats display no handoff UI. This gradual rollout toggle can be disabled to revert immediately without rolling back the release. | | enableDisplayContextUsage | boolean | No | When enabled, this conversation platform's webchat displays a context usage percentage bar below the input box. It is independent of conversation handoff: handoff toggles, including the global handoff toggle, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the bar regardless of this toggle. Disabled by default; disabling it reverts immediately without rolling back the release. | | enableDisplayThinking | boolean | No | | | enableUserThinkingControl | boolean | No | | | enableDisplayQueryMetadata | boolean | No | | | enableDisplayHookMarkers | boolean | No | | | hookMarkerTextInputModify | string | No | | | hookMarkerTextOutputModify | string | No | | | hookMarkerTextInputBlock | string | No | | | hookMarkerTextOutputBlock | string | No | | | enableShareConversation | boolean | No | | | enableLocation | boolean | No | | | enableShowPoweredBy | boolean | No | | | poweredByLogo | string (uri) | No | | | enableAnonymous | boolean | No | | | enableDisplayPreviousConversation | boolean | No | | | enableDisplayConversationHistory | boolean | No | | | enableConversationTimer | boolean | No | | | conversationTimerDuration | integer | No | Timer timeout duration, ranging from 3-60 minutes | | enableAutoNewConversationOnTimeout | boolean | No | | | enableSatisfactionSurvey | boolean | No | | | satisfactionSurveyDelayMinutes | integer | No | Number of minutes after the last AI reply before the survey appears, ranging from 1-60 minutes | | satisfactionSurveyPrompt | string | No | Custom survey title text; leave blank to use the frontend's default localized text | | enableThemeModeToggle | boolean | No | | | enableDisplayFontSizeSwitch | boolean | No | | | defaultThemeMode | object | No | | | enableDownloadCitations | boolean | No | | | customDomain | object (contains 3 properties: id, domain, status) | No | | | customDomain.domain | string | Yes | | | enableDisplayChatbotAvatar | boolean | No | | | enableDisplayChatbotName | boolean | No | | | buttonIcon | string (uri) | No | | | conversationStartersDisplayCount | integer | No | | | preChatFormEnabled | boolean | No | | | preChatFormFields | object | No | | | preChatFormTitle | object | No | | | preChatFormSubtitle | object | No | | | loadingDisplayMode | object | No | 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 | No | 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 | No | 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 | No | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | No | 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) | No | | | loadingAnimationAssetUrlsByStage | object | No | 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 | No | 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) | No | | | toolCardCompletedIconUrl | string (uri) | No | | **Example Request Structure** ```typescript { "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input box, which remains usable. When disabled, the current overlay panel is retained. This gradual rollout toggle can be disabled at any time to revert to the previous behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, this conversation platform's webchat displays the handoff UI (notification bar, summary card, and continue button) and registers handoff tools. It remains subject to the global handoff toggle in system settings: disabling the global toggle disables handoff everywhere. MaiGPT always displays the UI regardless of this toggle. The context usage percentage bar at the bottom is controlled separately by "Display context usage". Disabled by default, so customer-facing webchats display no handoff UI. This gradual rollout toggle can be disabled to revert immediately without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, this conversation platform's webchat displays a context usage percentage bar below the input box. It is independent of conversation handoff: handoff toggles, including the global handoff toggle, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the bar regardless of this toggle. Disabled by default; disabling it reverts immediately without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3-60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Number of minutes after the last AI reply before the survey appears, ranging from 1-60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave blank to use the frontend's default localized text (Optional) "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "domain": string } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "conversationStartersDisplayCount"?: integer // Optional "preChatFormEnabled"?: boolean // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional } ``` **Example Request Values** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Configure request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request failed:'); 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" } # Request body (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": True, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "Example string" }, "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("Response received successfully:") print(response.json()) except Exception as e: print("Request failed:", 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' => 'Example string', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'Example string', 'isActive' => true, 'theme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', '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' => 'Example string', 'hookMarkerTextOutputModify' => 'Example string', 'hookMarkerTextInputBlock' => 'Example string', 'hookMarkerTextOutputBlock' => 'Example string', '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' => 'Example string', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'Example string' ], '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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request failed: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status code: 200** **Example Response Schema** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input field, which remains usable. When disabled, the existing overlay panel is retained. This gradual rollout switch can be disabled at any time to revert the behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, this conversation platform's webchat displays the handoff UI (notification bar, summary card, and resume button) and registers handoff tools. It remains subject to the global handoff switch in system settings (when the global switch is off, handoff is disabled everywhere). MaiGPT always displays the UI regardless of this switch. The context usage percentage bar at the bottom is controlled separately by “Display context usage”. Disabled by default, so customer-facing webchat displays no handoff UI. This gradual rollout switch reverts the behavior immediately when disabled, without a version rollback. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, this conversation platform's webchat displays a context usage percentage bar below the input field. It is independent of conversation handoff: handoff switches (including the global handoff switch) do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the bar regardless of this switch. Disabled by default; disabling it immediately reverts the behavior without a version rollback. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3 to 60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Number of minutes after the last AI reply before the survey appears, ranging from 1 to 60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the frontend's default localized text (Optional) "accessType": { } "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "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 // Optional "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 // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Response string", "cover": "https://example.com/file.jpg", "backUrl": "Response string", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "Response string" ], "theme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "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": "Response string", "hookMarkerTextOutputModify": "Response string", "hookMarkerTextInputBlock": "Response string", "hookMarkerTextOutputBlock": "Response string", "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": "Response string", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "Response string", "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": "Example Response Name", "description": "Example Response 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": "Example Response Name", "description": "Example Response Description" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example Response Name", "description": "Example Response Description" } } ``` *** ### Partially Update Web Chat PATCH `/api/v1/web-chats/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------------------------------- | -------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | avatar | string (uri) | No | | | logo | string (uri) | No | | | description | string | No | | | cover | string (uri) | No | | | backUrl | string | No | | | isActive | boolean | No | | | theme | object | No | | | theme.primaryColor | string | No | | | theme.navbarTextColor | string | No | | | theme.conversationBackgroundColor | string | No | | | theme.chatbotMessageTextColor | string | No | | | theme.userMessageTextColor | string | No | | | theme.chatbotMessageBackgroundColor | string | No | | | theme.userMessageBackgroundColor | string | No | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | theme.userMessageBackgroundShadowEnabled | boolean | No | | | theme.chatbotMessageGradientEnabled | boolean | No | | | theme.userMessageGradientEnabled | boolean | No | | | darkTheme | object | No | | | darkTheme.primaryColor | string | No | | | darkTheme.navbarTextColor | string | No | | | darkTheme.conversationBackgroundColor | string | No | | | darkTheme.chatbotMessageTextColor | string | No | | | darkTheme.userMessageTextColor | string | No | | | darkTheme.chatbotMessageBackgroundColor | string | No | | | darkTheme.userMessageBackgroundColor | string | No | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.chatbotMessageGradientEnabled | boolean | No | | | darkTheme.userMessageGradientEnabled | boolean | No | | | enableFileUpload | boolean | No | | | enableDisplayCitations | boolean | No | | | toolDisplayMode | string (enum: full, compact, hidden) | No | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | No | When enabled, ask\_user\_question options appear as a row of buttons above the input box, which remains usable. When disabled, the existing overlay panel is retained. This rollout toggle can be disabled at any time to revert the behavior. | | enableConversationHandoff | boolean | No | When enabled, this conversation platform’s webchat displays the handoff UI (notification bar, summary card, and continue button) and registers handoff tools. It remains subject to the global handoff toggle in system settings: disabling the global toggle disables handoff everywhere. MaiGPT always displays it regardless of this platform toggle. The context usage percentage bar at the bottom is controlled separately by “Display context usage”. Disabled by default, so customer-facing webchats show no handoff UI. This rollout toggle can be disabled to revert the behavior without rolling back the release. | | enableDisplayContextUsage | boolean | No | When enabled, this conversation platform’s webchat displays a context usage percentage bar below the input box. This is independent of conversation handoff: handoff toggles, including the global handoff toggle, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays it regardless of this toggle. Disabled by default; disable it to revert the behavior without rolling back the release. | | enableDisplayThinking | boolean | No | | | enableUserThinkingControl | boolean | No | | | enableDisplayQueryMetadata | boolean | No | | | enableDisplayHookMarkers | boolean | No | | | hookMarkerTextInputModify | string | No | | | hookMarkerTextOutputModify | string | No | | | hookMarkerTextInputBlock | string | No | | | hookMarkerTextOutputBlock | string | No | | | enableShareConversation | boolean | No | | | enableLocation | boolean | No | | | enableShowPoweredBy | boolean | No | | | poweredByLogo | string (uri) | No | | | enableAnonymous | boolean | No | | | enableDisplayPreviousConversation | boolean | No | | | enableDisplayConversationHistory | boolean | No | | | enableConversationTimer | boolean | No | | | conversationTimerDuration | integer | No | Timer timeout duration, ranging from 3-60 minutes | | enableAutoNewConversationOnTimeout | boolean | No | | | enableSatisfactionSurvey | boolean | No | | | satisfactionSurveyDelayMinutes | integer | No | Number of minutes after the last AI reply before the survey appears, ranging from 1-60 minutes | | satisfactionSurveyPrompt | string | No | Custom survey title text; leave blank to use the frontend’s default localized text | | enableThemeModeToggle | boolean | No | | | enableDisplayFontSizeSwitch | boolean | No | | | defaultThemeMode | object | No | | | enableDownloadCitations | boolean | No | | | customDomain | object (contains 3 properties: id, domain, status) | No | | | customDomain.domain | string | Yes | | | enableDisplayChatbotAvatar | boolean | No | | | enableDisplayChatbotName | boolean | No | | | buttonIcon | string (uri) | No | | | conversationStartersDisplayCount | integer | No | | | preChatFormEnabled | boolean | No | | | preChatFormFields | object | No | | | preChatFormTitle | object | No | | | preChatFormSubtitle | object | No | | | loadingDisplayMode | object | No | 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 | No | 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 | No | 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 | No | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | No | 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) | No | | | loadingAnimationAssetUrlsByStage | object | No | 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 | No | 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) | No | | | toolCardCompletedIconUrl | string (uri) | No | | **Request Schema Example** ```typescript { "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "theme"?: { // Optional { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme"?: { // Optional { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input box, which remains usable. When disabled, the existing overlay panel is retained. This rollout toggle can be disabled at any time to revert the behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, this conversation platform’s webchat displays the handoff UI (notification bar, summary card, and continue button) and registers handoff tools. It remains subject to the global handoff toggle in system settings: disabling the global toggle disables handoff everywhere. MaiGPT always displays it regardless of this platform toggle. The context usage percentage bar at the bottom is controlled separately by “Display context usage”. Disabled by default, so customer-facing webchats show no handoff UI. This rollout toggle can be disabled to revert the behavior without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, this conversation platform’s webchat displays a context usage percentage bar below the input box. This is independent of conversation handoff: handoff toggles, including the global handoff toggle, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays it regardless of this toggle. Disabled by default; disable it to revert the behavior without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3-60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Number of minutes after the last AI reply before the survey appears, ranging from 1-60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave blank to use the frontend’s default localized text (Optional) "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "domain": string } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "conversationStartersDisplayCount"?: integer // Optional "preChatFormEnabled"?: boolean // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional } ``` **Example Request Values** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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" } # Request body (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": True, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "Example string" }, "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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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' => 'Example string', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'Example string', 'isActive' => true, 'theme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', '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' => 'Example string', 'hookMarkerTextOutputModify' => 'Example string', 'hookMarkerTextInputBlock' => 'Example string', 'hookMarkerTextOutputBlock' => 'Example string', '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' => 'Example string', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'Example string' ], '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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status code: 200** **Example response schema** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input field, which remains usable. When disabled, the existing overlay panel is retained. This gradual rollout toggle can be disabled at any time to revert the behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, this conversation platform's webchat displays the handoff UI (notification bar, summary card, and continuation button) and registers handoff tools. The global handoff toggle in system settings still applies: disabling it disables handoff everywhere. MaiGPT always displays the UI regardless of this toggle. The context usage percentage bar at the bottom is controlled separately by "Display Context Usage". Disabled by default, so customer-facing webchat displays no handoff UI. This gradual rollout toggle lets you revert the behavior by disabling it without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, this conversation platform's webchat displays a context usage percentage bar below the input field. This is independent of conversation handoff: handoff toggles, including the global handoff toggle, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays it regardless of this toggle. Disabled by default; disabling it reverts the behavior without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3-60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey appears, ranging from 1-60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave blank to use the frontend's default localized text (Optional) "accessType": { } "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "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 // Optional "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 // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **Response Example Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Response string", "cover": "https://example.com/file.jpg", "backUrl": "Response string", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "Response string" ], "theme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "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": "Response string", "hookMarkerTextOutputModify": "Response string", "hookMarkerTextInputBlock": "Response string", "hookMarkerTextOutputBlock": "Response string", "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": "Response string", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "Response string", "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": "Example response name", "description": "Example response 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": "Example response name", "description": "Example response description" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" } } ``` *** ### Set Up Contact Credentials POST `/api/v1/web-chats/{id}/setup-contact-credentials/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ---------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | sourceId | string | Yes | Unique identifier for the contact | | name | string | No | Contact display name | | mcpCredentials | object (contains 2 properties: toolId, headers) | No | MCP credentials configuration | | mcpCredentials.toolId | string (uuid) | Yes | MCP Tool ID | | mcpCredentials.headers | object | No | Authentication headers | | embedOrigin | string | No | Origin of the embedding page (forwarded by the web chat frontend) for allowlist validation | | ts | integer | No | Unix timestamp (seconds, UTC) the signature was computed with. Required when the inbox login settings enable Source ID access with signature verification. | | sig | string | No | Hex HMAC-SHA256 of "{webChatId}.{sourceId}.{ts}" computed by the embedding site backend | **Request Schema Example** ```typescript { "sourceId": string // Unique identifier for the contact "name"?: string // Contact display name (Optional) "mcpCredentials"?: // MCP credentials configuration (Optional) { "toolId": string (uuid) // MCP Tool ID "headers"?: object // Authentication headers (Optional) } "embedOrigin"?: string // Origin of the embedding page (forwarded by the web chat frontend) for allowlist validation (Optional) "ts"?: integer // Unix timestamp (seconds, UTC) the signature was computed with. Required when the inbox login settings enable Source ID access with signature verification. (Optional) "sig"?: string // Hex HMAC-SHA256 of "{webChatId}.{sourceId}.{ts}" computed by the embedding site backend (Optional) } ``` **Request Example Values** ```json { "sourceId": "Example string", "name": "Example name", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "Example string", "ts": 123, "sig": "Example string" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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": "Example string", "name": "Example name", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "Example string", "ts": 123, "sig": "Example string" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "sourceId": "Example string", "name": "Example name", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "Example string", "ts": 123, "sig": "Example string" }; axios.post("https://api.maiagent.ai/api/v1/web-chats/550e8400-e29b-41d4-a716-446655440000/setup-contact-credentials/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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" } # Request body (payload) data = { "sourceId": "Example string", "name": "Example name", "mcpCredentials": { "toolId": "550e8400-e29b-41d4-a716-446655440000", "headers": {} }, "embedOrigin": "Example string", "ts": 123, "sig": "Example string" } response = requests.post(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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' => 'Example string', 'name' => 'Example name', 'mcpCredentials' => [ 'toolId' => '550e8400-e29b-41d4-a716-446655440000', 'headers' => new \stdClass() ], 'embedOrigin' => 'Example string', 'ts' => 123, 'sig' => 'Example string' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Response Schema Example** ```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}/). } ``` **Response Example Values** ```json { "contactId": "550e8400-e29b-41d4-a716-446655440000", "created": false } ``` **Status Code: 400 - No response body** *** ### Get Voice Agent Token POST `/api/v1/web-chats/{id}/voice-agent/token/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ---------------------------------------- | | `id` | ✅ | string | A UUID string identifying this web chat. | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------------------------------- | -------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | avatar | string (uri) | No | | | logo | string (uri) | No | | | description | string | No | | | cover | string (uri) | No | | | backUrl | string | No | | | isActive | boolean | No | | | theme | object | Yes | | | theme.primaryColor | string | No | | | theme.navbarTextColor | string | No | | | theme.conversationBackgroundColor | string | No | | | theme.chatbotMessageTextColor | string | No | | | theme.userMessageTextColor | string | No | | | theme.chatbotMessageBackgroundColor | string | No | | | theme.userMessageBackgroundColor | string | No | | | theme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | theme.userMessageBackgroundShadowEnabled | boolean | No | | | theme.chatbotMessageGradientEnabled | boolean | No | | | theme.userMessageGradientEnabled | boolean | No | | | darkTheme | object | Yes | | | darkTheme.primaryColor | string | No | | | darkTheme.navbarTextColor | string | No | | | darkTheme.conversationBackgroundColor | string | No | | | darkTheme.chatbotMessageTextColor | string | No | | | darkTheme.userMessageTextColor | string | No | | | darkTheme.chatbotMessageBackgroundColor | string | No | | | darkTheme.userMessageBackgroundColor | string | No | | | darkTheme.chatbotMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.userMessageBackgroundShadowEnabled | boolean | No | | | darkTheme.chatbotMessageGradientEnabled | boolean | No | | | darkTheme.userMessageGradientEnabled | boolean | No | | | enableFileUpload | boolean | No | | | enableDisplayCitations | boolean | No | | | toolDisplayMode | string (enum: full, compact, hidden) | No | `full`: Full ; `compact`: Compact ; `hidden`: Hidden; | | enableAskOptionButtons | boolean | No | When enabled, ask\_user\_question options appear as a row of buttons above the input field, which remains usable. When disabled, the existing overlay panel is retained. This gradual rollout switch can be turned off at any time to revert the behavior. | | enableConversationHandoff | boolean | No | When enabled, this conversation platform's webchat displays the handoff UI (notification bar, summary card, and continuation button) and registers handoff tools. The global handoff switch in system settings still applies: when it is off, handoff is disabled everywhere. MaiGPT always displays the handoff UI regardless of this switch. The context usage percentage bar at the bottom is controlled separately by "Display context usage". Disabled by default, so customers' public webchats show no handoff UI. This gradual rollout switch can be turned off to revert the behavior without rolling back the release. | | enableDisplayContextUsage | boolean | No | When enabled, this conversation platform's webchat displays a context usage percentage bar below the input field. It is independent of conversation handoff: handoff switches, including the global handoff switch, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the bar regardless of this switch. Disabled by default; turn it off to revert the behavior without rolling back the release. | | enableDisplayThinking | boolean | No | | | enableUserThinkingControl | boolean | No | | | enableDisplayQueryMetadata | boolean | No | | | enableDisplayHookMarkers | boolean | No | | | hookMarkerTextInputModify | string | No | | | hookMarkerTextOutputModify | string | No | | | hookMarkerTextInputBlock | string | No | | | hookMarkerTextOutputBlock | string | No | | | enableShareConversation | boolean | No | | | enableLocation | boolean | No | | | enableShowPoweredBy | boolean | No | | | poweredByLogo | string (uri) | No | | | enableAnonymous | boolean | No | | | enableDisplayPreviousConversation | boolean | No | | | enableDisplayConversationHistory | boolean | No | | | enableConversationTimer | boolean | No | | | conversationTimerDuration | integer | No | Timer timeout duration, from 3 to 60 minutes | | enableAutoNewConversationOnTimeout | boolean | No | | | enableSatisfactionSurvey | boolean | No | | | satisfactionSurveyDelayMinutes | integer | No | Number of minutes after the last AI reply before the survey appears, from 1 to 60 minutes | | satisfactionSurveyPrompt | string | No | Custom survey title text; leave blank to use the frontend's default localized text | | enableThemeModeToggle | boolean | No | | | enableDisplayFontSizeSwitch | boolean | No | | | defaultThemeMode | object | No | | | enableDownloadCitations | boolean | No | | | customDomain | object (contains 3 properties: id, domain, status) | No | | | customDomain.domain | string | Yes | | | enableDisplayChatbotAvatar | boolean | No | | | enableDisplayChatbotName | boolean | No | | | buttonIcon | string (uri) | No | | | conversationStartersDisplayCount | integer | No | | | preChatFormEnabled | boolean | No | | | preChatFormFields | object | No | | | preChatFormTitle | object | No | | | preChatFormSubtitle | object | No | | | loadingDisplayMode | object | No | 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 | No | 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 | No | 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 | No | How long a single reply must be pending before the long-wait copy appears. | | loadingAnimationUseSharedAsset | boolean | No | 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) | No | | | loadingAnimationAssetUrlsByStage | object | No | 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 | No | 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) | No | | | toolCardCompletedIconUrl | string (uri) | No | | **Request Schema Example** ```typescript { "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input box, which remains usable. When disabled, the existing overlay panel is used. This gradual rollout toggle can be disabled at any time to revert the behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, this conversation platform's webchat displays the handoff UI (notification bar, summary card, and continuation button) and registers handoff tools. The global handoff toggle in system settings still applies: disabling it disables handoff everywhere. MaiGPT always displays the UI regardless of this toggle. The context usage percentage bar at the bottom is controlled separately by "Display Context Usage". Disabled by default, so customer-facing webchats display no handoff UI. This gradual rollout toggle reverts the behavior when disabled, without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, this conversation platform's webchat displays a context usage percentage bar below the input box. This is independent of conversation handoff: handoff toggles, including the global toggle, do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the bar regardless of this toggle. Disabled by default; disabling it reverts the behavior without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3-60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey appears, ranging from 1-60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave blank to use the frontend's default localized text (Optional) "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "domain": string } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "conversationStartersDisplayCount"?: integer // Optional "preChatFormEnabled"?: boolean // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional } ``` **Example Request Values** ```json { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": true, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": true, "userMessageBackgroundShadowEnabled": true, "chatbotMessageGradientEnabled": true, "userMessageGradientEnabled": true }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": true, "enableDisplayFontSizeSwitch": true, "defaultThemeMode": {}, "enableDownloadCitations": true, "customDomain": { "domain": "Example string" }, "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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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" } # Request body (payload) data = { "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Example string", "cover": "https://example.com/file.jpg", "backUrl": "Example string", "isActive": True, "theme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "chatbotMessageBackgroundShadowEnabled": True, "userMessageBackgroundShadowEnabled": True, "chatbotMessageGradientEnabled": True, "userMessageGradientEnabled": True }, "darkTheme": { "primaryColor": "Example string", "navbarTextColor": "Example string", "conversationBackgroundColor": "Example string", "chatbotMessageTextColor": "Example string", "userMessageTextColor": "Example string", "chatbotMessageBackgroundColor": "Example string", "userMessageBackgroundColor": "Example string", "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": "Example string", "hookMarkerTextOutputModify": "Example string", "hookMarkerTextInputBlock": "Example string", "hookMarkerTextOutputBlock": "Example string", "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": "Example string", "enableThemeModeToggle": True, "enableDisplayFontSizeSwitch": True, "defaultThemeMode": {}, "enableDownloadCitations": True, "customDomain": { "domain": "Example string" }, "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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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' => 'Example string', 'cover' => 'https://example.com/file.jpg', 'backUrl' => 'Example string', 'isActive' => true, 'theme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', 'chatbotMessageBackgroundShadowEnabled' => true, 'userMessageBackgroundShadowEnabled' => true, 'chatbotMessageGradientEnabled' => true, 'userMessageGradientEnabled' => true ], 'darkTheme' => [ 'primaryColor' => 'Example string', 'navbarTextColor' => 'Example string', 'conversationBackgroundColor' => 'Example string', 'chatbotMessageTextColor' => 'Example string', 'userMessageTextColor' => 'Example string', 'chatbotMessageBackgroundColor' => 'Example string', 'userMessageBackgroundColor' => 'Example string', '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' => 'Example string', 'hookMarkerTextOutputModify' => 'Example string', 'hookMarkerTextInputBlock' => 'Example string', 'hookMarkerTextOutputBlock' => 'Example string', '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' => 'Example string', 'enableThemeModeToggle' => true, 'enableDisplayFontSizeSwitch' => true, 'defaultThemeMode' => new \stdClass(), 'enableDownloadCitations' => true, 'customDomain' => [ 'domain' => 'Example string' ], '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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "id": string (uuid) "name": string "avatar"?: string (uri) // Optional "logo"?: string (uri) // Optional "description"?: string // Optional "cover"?: string (uri) // Optional "backUrl"?: string // Optional "isActive"?: boolean // Optional "enableSpeech": boolean "displayConversationStarters": [ string ] "theme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "darkTheme": { { "primaryColor"?: string // Optional "navbarTextColor"?: string // Optional "conversationBackgroundColor"?: string // Optional "chatbotMessageTextColor"?: string // Optional "userMessageTextColor"?: string // Optional "chatbotMessageBackgroundColor"?: string // Optional "userMessageBackgroundColor"?: string // Optional "chatbotMessageBackgroundShadowEnabled"?: boolean // Optional "userMessageBackgroundShadowEnabled"?: boolean // Optional "chatbotMessageGradientEnabled"?: boolean // Optional "userMessageGradientEnabled"?: boolean // Optional } } "enableFileUpload"?: boolean // Optional "enableDisplayCitations"?: boolean // Optional "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full * `compact` - Compact * `hidden` - Hidden (Optional) "enableAskOptionButtons"?: boolean // When enabled, ask_user_question options appear as a row of buttons above the input box, which remains usable. When disabled, the existing overlay panel is used. This gradual rollout toggle can be disabled at any time to revert the behavior. (Optional) "enableConversationHandoff"?: boolean // When enabled, webchat on this conversation platform displays the handoff UI (notification bar, summary card, and continue button) and registers handoff tools. The global handoff toggle in system settings still applies: when it is off, handoff is disabled everywhere. MaiGPT always displays the UI regardless of this toggle. The context usage percentage bar at the bottom is controlled separately by "Display context usage". Disabled by default, so customer-facing webchat shows no handoff UI. This gradual rollout toggle can be disabled to revert the behavior without rolling back the release. (Optional) "enableDisplayContextUsage"?: boolean // When enabled, webchat on this conversation platform displays a context usage percentage bar below the input box. This is independent of conversation handoff: handoff toggles (including the global handoff toggle) do not affect it, and it does not affect the handoff notification bar. MaiGPT always displays the bar regardless of this toggle. Disabled by default; disabling it reverts the behavior without rolling back the release. (Optional) "enableDisplayThinking"?: boolean // Optional "enableUserThinkingControl"?: boolean // Optional "enableDisplayQueryMetadata"?: boolean // Optional "enableDisplayHookMarkers"?: boolean // Optional "hookMarkerTextInputModify"?: string // Optional "hookMarkerTextOutputModify"?: string // Optional "hookMarkerTextInputBlock"?: string // Optional "hookMarkerTextOutputBlock"?: string // Optional "enableShareConversation"?: boolean // Optional "enableLocation"?: boolean // Optional "enableShowPoweredBy"?: boolean // Optional "poweredByLogo"?: string (uri) // Optional "enableAnonymous"?: boolean // Optional "enableDisplayPreviousConversation"?: boolean // Optional "enableDisplayConversationHistory"?: boolean // Optional "enableConversationTimer"?: boolean // Optional "conversationTimerDuration"?: integer // Timer timeout duration, ranging from 3-60 minutes (Optional) "enableAutoNewConversationOnTimeout"?: boolean // Optional "enableSatisfactionSurvey"?: boolean // Optional "satisfactionSurveyDelayMinutes"?: integer // Number of minutes after the last AI reply before the survey appears, ranging from 1-60 minutes (Optional) "satisfactionSurveyPrompt"?: string // Custom survey title text; leave blank to use the default localized text in the frontend (Optional) "accessType": { } "enableThemeModeToggle"?: boolean // Optional "enableDisplayFontSizeSwitch"?: boolean // Optional "defaultThemeMode"?: // Optional { } "enableDownloadCitations"?: boolean // Optional "customDomain"?: // Optional { "id": string (uuid) "domain": string "status": { } } "enableDisplayChatbotAvatar"?: boolean // Optional "enableDisplayChatbotName"?: boolean // Optional "buttonIcon"?: string (uri) // Optional "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 // Optional "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 // Optional "preChatFormFields"?: object // Optional "preChatFormTitle"?: object // Optional "preChatFormSubtitle"?: object // Optional "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 (Optional) { } "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. (Optional) "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. (Optional) "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (Optional) "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. (Optional) "loadingAnimationSharedAssetUrl"?: string (uri) // Optional "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. (Optional) "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. (Optional) "toolCardRunningIconUrl"?: string (uri) // Optional "toolCardCompletedIconUrl"?: string (uri) // Optional "inbox": object "quickMenu": object // Mounted Quick Menu Agent UI config for the web chat input bar; null when absent (read-only) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "avatar": "https://example.com/file.jpg", "logo": "https://example.com/file.jpg", "description": "Response string", "cover": "https://example.com/file.jpg", "backUrl": "Response string", "isActive": false, "enableSpeech": false, "displayConversationStarters": [ "Response string" ], "theme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "chatbotMessageBackgroundShadowEnabled": false, "userMessageBackgroundShadowEnabled": false, "chatbotMessageGradientEnabled": false, "userMessageGradientEnabled": false }, "darkTheme": { "primaryColor": "Response string", "navbarTextColor": "Response string", "conversationBackgroundColor": "Response string", "chatbotMessageTextColor": "Response string", "userMessageTextColor": "Response string", "chatbotMessageBackgroundColor": "Response string", "userMessageBackgroundColor": "Response string", "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": "Response string", "hookMarkerTextOutputModify": "Response string", "hookMarkerTextInputBlock": "Response string", "hookMarkerTextOutputBlock": "Response string", "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": "Response string", "accessType": {}, "enableThemeModeToggle": false, "enableDisplayFontSizeSwitch": false, "defaultThemeMode": {}, "enableDownloadCitations": false, "customDomain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "Response string", "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": "Example response name", "description": "Example response 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": "Example response name", "description": "Example response description" }, "quickMenu": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" } } ``` *** ### Upload a Batch QA File POST `/api/v1/web-chats/{webchatPk}/batch-qas/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `webchatPk` | ✅ | string | | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----- | ------------ | -------- | ----------- | | file | string (uri) | Yes | | **Example Request Schema** ```typescript { "file": string (uri) } ``` **Example Request Values** ```json { "file": "https://example.com/file.jpg" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request Body (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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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" } # Request Body (payload) data = { "file": "https://example.com/file.jpg" } response = requests.post(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 201** **Example Response Schema** ```typescript { "id": string (uuid) "file": string (uri) "createdAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "file": "https://example.com/file.jpg", "createdAt": "Response string" } ``` *** ### Export Batch QA to Excel GET `/api/v1/web-chats/{webchatPk}/batch-qas/{id}/export-excel/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Chatbot Batch QA File. | | `webchatPk` | ✅ | string | | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers 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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content | Status Code | Description | | ----------- | ------------------- | | 200 | Excel File Download | *** ### Get LLM Usage Statistics GET `/api/v1/chatbots/{chatbotPk}/llm-usage-statistics/` #### Parameters | Parameter Name | Required | Type | Description | | ----------------- | -------- | ------ | ----------------------------------------- | | `chatbotPk` | ✅ | string | A UUID string identifying this Chatbot ID | | `endDate` | ❌ | string | End date, format: YYYY-MM-DD | | `startDate` | ✅ | string | Start date, format: YYYY-MM-DD | | `timeGranularity` | ✅ | string | Time granularity (day/month) | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers 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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status Code: 200** **Example Response Schema** ```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) // Date when time_granularity=day (optional) "month"?: string (date) // Month when time_granularity=month (first day of the month) (optional) "totalWordsCount": integer "totalInputTokenUsage": integer "totalOutputTokenUsage": integer "totalCacheCreationInputTokens": integer "totalCacheReadInputTokens": integer "totalTokenUsage": integer } ] ``` **Example Response Values** ```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" } ] } ] ] ``` **Status Code: 400** **Example Response Schema** ```typescript { "detail"?: string // Optional "valid_types"?: [ // Optional string ] } ``` **Example Response Values** ```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" } ] } ] ] ``` *** ### Get AI Assistant Statistics GET `/api/v1/chatbots/{chatbotPk}/statistics/` #### Parameters | Parameter Name | Required | Type | Description | | ----------------- | -------- | ------ | ------------------------------------------ | | `chatbotPk` | ✅ | string | A UUID string identifying this Chatbot ID | | `endDate` | ❌ | string | End date (YYYY-MM-DD), defaults to today | | `startDate` | ❌ | string | Start date (YYYY-MM-DD), defaults to today | | `timeGranularity` | ✅ | string | Time granularity (hour/day/month) | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers 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('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request 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("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", 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 "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status Code: 200** **Example Response Schema** ```typescript [ { "datetime": string // Timestamp (milliseconds, string) "messagesCount": integer // Message count "conversationsCount": integer // Conversation count "avgMessagesPerConversation": number (double) // Average messages per conversation "avgLikesPerFeedback": number (double) // Satisfaction: likes / (likes + dislikes), 0 when there is no feedback "likesCount": integer // Like count (excluding feedback on opening messages; daily/monthly values are totals for the period) "dislikesCount": integer // Dislike count (excluding feedback on opening messages; daily/monthly values are totals for the period) } ] ``` **Example Response Values** ```json [ { "datetime": "Response string", "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/en/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.