Widgets

Update Widget

Update a widget. Fields you leave out keep their current value.

patch/api/v1/widgets/{widget_id}

Request

  • Base URL: https://api.dialogbrain.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.dialogbrain.com/api/v1/widgets/{widget_id}
  • Auth: none declared

Path parameters

widget_idinteger required

Request body

namestring nullable

New name for the widget

auto_reply_mode'auto' | 'draft' nullable

Auto-reply mode: 'draft' or 'auto'. OMIT to leave the auto-reply mode unchanged.

primary_colorstring nullable

Primary color for widget theme (hex, e.g., '#2563eb'). Paints the header, the visitor's message bubbles and the send button — and the launcher bubble too unless launcher_color overrides it.

launcher_colorstring nullable

Hex color for the closed launcher bubble (e.g., '#ffffff'). Override this to use a different color than primary_color. Clear it to revert to primary_color.

position'bottom-right' | 'bottom-left' nullable

Widget position on screen. OMIT to leave the position unchanged.

header_titlestring nullable

Title shown in chat header

header_subtitlestring nullable

Subtitle shown in chat header

is_activeboolean nullable

Enable or disable the widget. OMIT to leave the active flag unchanged.

calendly_urlstring nullable

Booking URL for calendar action (e.g., 'https://calendly.com/yourname')

require_identificationboolean nullable

Require visitor to identify before chatting. OMIT to leave the identification policy unchanged.

website_urlstring nullable

Website URL for product/site search integration

enable_search_actionboolean nullable

Enable or disable the search action button. OMIT to leave this flag unchanged.

enable_form_actionboolean nullable

Enable or disable the contact form action button. OMIT to leave this flag unchanged.

enable_calendar_actionboolean nullable

Enable or disable the calendar booking action button. OMIT to leave this flag unchanged.

greeting_textstring nullable

Custom greeting message shown when visitor opens the chat (e.g., 'Hello! How can I help you today?')

returning_greeting_textstring nullable

Greeting for returning visitors who already have chat history (e.g., 'Welcome back! How can I help you today?'). Falls back to greeting_text if not set.

greeting_enabledboolean nullable

Enable or disable the proactive greeting. OMIT to leave this flag unchanged.

greeting_delay_secondsinteger nullable

Delay in seconds before the proactive greeting appears (0–300). 0 = send immediately on page load. Default: 30.

greeting_behavior'notification' | 'auto_open' | 'on_open' nullable

notification = show badge after delay; auto_open = open widget automatically after delay; on_open = greet only when visitor manually opens. OMIT to leave the greeting behavior unchanged.

color_scheme'light' | 'dark' | 'auto' nullable

Widget color scheme. 'auto' follows the visitor's OS dark/light mode preference. OMIT to leave the color scheme unchanged.

show_visitor_historyboolean nullable

Show full chat history to returning visitors. OMIT to leave this flag unchanged.

allow_voiceboolean nullable

Master switch for voice on this widget — set true to show the mic and let visitors talk to the agent. Everything else voice-related (greeting, button label, STT/TTS from the agent's own config) is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave the setting unchanged.

max_voice_duration_secondsinteger nullable

Hard cap on a single voice call from this widget, in seconds (default 300). OMIT to leave the cap unchanged.

voice_greetingstring nullable

Spoken opening line when a visitor starts a voice call through this widget. Played via TTS before the AI model runs. Empty string disables the greeting. Requires allow_voice=true to be audible.

display_mode'chat' | 'voice_only' | 'headless' nullable

How the widget renders: 'chat' (default) for the full panel with a microphone, 'voice_only' for a mic-only bubble that starts a call, 'headless' for no interface at all, driven through window.DialogBrain.

voice_button_labelstring nullable

Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if not set.

Response

Successful Response

unknown required

Changes

No recorded changes to this operation across all 5 revisions of this API.