---
title: "Update Widget"
method: PATCH
path: "/api/livechat/widgets/{widget_id}"
tags: ["livechat", "livechat"]
---

# Update Widget

`PATCH /api/livechat/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/livechat/widgets/{widget_id}`
- Auth: none declared

Update a LiveChat widget.

## Path parameters

- `widget_id` integer, required

## Request body

- SrcApiLivechatConfigWidgetUpdateRequest: Request to update widget settings.
  - `name` string, nullable
  - `theme` WidgetTheme: Widget appearance configuration.
    - `primaryColor` string
    - `launcherColor` string, nullable
    - `position` string
    - `buttonIcon` string
    - `headerTitle` string
    - `headerSubtitle` string
    - `colorScheme` 'light' | 'dark' | 'auto'
  - `require_identification` boolean, nullable
  - `identification_fields` string[], nullable
  - `identification_field_config` object, nullable: Custom field rendering config (set to {} to clear)
  - `show_visitor_history` boolean, nullable
  - `allowed_domains` string[], nullable
  - `rate_limit_per_minute` integer, nullable
  - `is_active` boolean, nullable
  - `calendly_url` string, nullable: Calendly/scheduling URL for calendar action (set to empty string to clear)
  - `contact_form_fields` string[], nullable: Available fields for contact form action
  - `contact_form_field_config` object, nullable: Per-field config overrides (set to {} to clear)
  - `enable_search_action` boolean, nullable: Allow LLM to use search action in AUTO_REPLY_RULES
  - `enable_form_action` boolean, nullable: Allow LLM to use form action to collect visitor info
  - `enable_calendar_action` boolean, nullable: Allow LLM to use calendar action to send scheduling links
  - `proactive_greeting` ProactiveGreetingConfig: Proactive greeting configuration for automatic visitor engagement.
    - `enabled` boolean
    - `delay_seconds` integer
    - `custom_greeting` string, nullable: Custom greeting message. If use_ai=True, AI will adapt/translate to visitor's language.
    - `returning_greeting` string, nullable: Greeting for returning visitors (who have prior chat history). Falls back to custom_greeting.
    - `use_ai` boolean: Use AI to generate/adapt greeting. If False and custom_greeting set, use as-is.
    - `prompt_id` integer, nullable
    - `fallback_message` string
    - `behavior` 'notification' | 'auto_open' | 'on_open'
    - `show_notification` boolean
    - `sound_enabled` boolean
  - `allow_attachments` boolean, nullable: Allow visitors to upload file attachments (images, PDFs)
  - `max_attachment_size_mb` integer, nullable: Maximum file size in MB for attachments
  - `allowed_attachment_types` string[], nullable: Allowed MIME types for attachments
  - `sound_enabled` boolean, nullable: Play sound when new message arrives
  - `site_search_enabled` boolean, nullable: Enable direct product search on widget owner's website
  - `website_url` string, nullable: Widget owner's website URL for product search
  - `ecommerce_platform` string, nullable: E-commerce platform: shopify, woocommerce, generic, or null for auto-detect
  - `allow_voice` boolean, nullable: Enable voice call mode in the widget
  - `allow_text_during_call` boolean, nullable: Allow typing messages during an active voice/avatar call
  - `allow_avatar` boolean, nullable: Enable avatar (talking-head video) call mode in the widget
  - `show_branding` boolean, nullable: Show the 'Powered by DialogBrain' badge under the chat. False needs a paid plan for this widget.
  - `max_voice_duration_seconds` integer, nullable: Maximum voice call duration in seconds
  - `voice_stt_model` string, nullable: STT model: 'flux' (context-aware turn detection) or 'nova-3' (classic)
  - `voice_greeting` string, nullable: First message the agent speaks when a voice call starts. Empty = agent waits.
  - `display_mode` 'chat' | 'voice_only' | 'headless', nullable: Visual mode of the widget. 'chat' (default): full chat panel + mic. 'voice_only': mic-only bubble that launches a voice call directly. 'headless': no UI; customer drives the widget via window.DialogBrain.* JS API.
  - `localization` WidgetLocalization: Per-widget localizable strings. v1 only consumes voice_button_label. Generic name (not voice-specific) so future fields — chat_input_placeholder, voice_unavailable_tooltip, etc. — extend this type without a v2 rename.
    - `voice_button_label` string, nullable: aria-label / hover tooltip for the voice-only mic bubble. Defaults to 'Talk to agent'.

## Response `200`

Successful Response

- WidgetResponse: Widget response model.
  - `id` integer, required
  - `widget_key` string, required
  - `name` string, required
  - `theme` object, required
  - `require_identification` boolean, required
  - `identification_fields` string[], required
  - `identification_field_config` object, nullable
  - `show_visitor_history` boolean, required
  - `allowed_domains` string[], required
  - `rate_limit_per_minute` integer, required
  - `is_active` boolean, required
  - `embed_code` string, required
  - `calendly_url` string, nullable
  - `contact_form_fields` string[]
  - `contact_form_field_config` object, nullable
  - `enable_search_action` boolean
  - `enable_form_action` boolean
  - `enable_calendar_action` boolean
  - `proactive_greeting` object, nullable
  - `allow_attachments` boolean
  - `max_attachment_size_mb` integer
  - `allowed_attachment_types` string[]
  - `sound_enabled` boolean
  - `site_search_enabled` boolean
  - `website_url` string, nullable
  - `ecommerce_platform` string, nullable
  - `allow_voice` boolean
  - `allow_text_during_call` boolean
  - `allow_avatar` boolean
  - `show_branding` boolean
  - `can_hide_branding` boolean
  - `max_voice_duration_seconds` integer
  - `voice_stt_model` string
  - `voice_greeting` string
  - `display_mode` 'chat' | 'voice_only' | 'headless'
  - `localization` object
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/77bef09a9209?raw)