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

# Update Widget

`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

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

## Path parameters

- `widget_id` integer, required

## Request body

- SrcApiV1ToolSchemaWidgetUpdateRequest
  - `name` string, 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_color` string, 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_color` string, 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_title` string, nullable: Title shown in chat header
  - `header_subtitle` string, nullable: Subtitle shown in chat header
  - `is_active` boolean, nullable: Enable or disable the widget. OMIT to leave the active flag unchanged.
  - `allowed_domains` unknown[], nullable: List of allowed domains for the widget
    - unknown
  - `calendly_url` string, nullable: Booking URL for calendar action (e.g., 'https://calendly.com/yourname')
  - `contact_form_fields` unknown[], nullable: Fields to collect in contact form (e.g., ['name', 'email', 'phone'])
    - unknown
  - `require_identification` boolean, nullable: Require visitor to identify before chatting. OMIT to leave the identification policy unchanged.
  - `identification_fields` unknown[], nullable: Fields to require for visitor identification (e.g., ['name', 'email'])
    - unknown
  - `website_url` string, nullable: Website URL for product/site search integration
  - `enable_search_action` boolean, nullable: Enable or disable the search action button. OMIT to leave this flag unchanged.
  - `enable_form_action` boolean, nullable: Enable or disable the contact form action button. OMIT to leave this flag unchanged.
  - `enable_calendar_action` boolean, nullable: Enable or disable the calendar booking action button. OMIT to leave this flag unchanged.
  - `greeting_text` string, nullable: Custom greeting message shown when visitor opens the chat (e.g., 'Hello! How can I help you today?')
  - `returning_greeting_text` string, 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_enabled` boolean, nullable: Enable or disable the proactive greeting. OMIT to leave this flag unchanged.
  - `greeting_delay_seconds` integer, 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_history` boolean, nullable: Show full chat history to returning visitors. OMIT to leave this flag unchanged.
  - `allow_voice` boolean, 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_seconds` integer, nullable: Hard cap on a single voice call from this widget, in seconds (default 300). OMIT to leave the cap unchanged.
  - `voice_greeting` string, 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_label` string, 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 `200`

Successful Response

- unknown

## Other responses

- `404`: No widget with this id in the workspace.
- `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)