---
title: "Create Widget"
method: POST
path: "/api/livechat/widgets"
tags: ["livechat", "livechat"]
---

# Create Widget

`POST /api/livechat/widgets`

## 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`
- Auth: none declared

Create a new LiveChat widget.

## Request body

- SrcApiLivechatConfigWidgetCreateRequest: Request to create a new widget.
  - `name` string
  - `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
  - `identification_fields` string[]
  - `identification_field_config` object, nullable: Custom field rendering config. Keys are field names, values are {label, type, options?, required?}. type: 'text'|'email'|'tel'|'select'|'date'. options: list of strings for select type.
  - `show_visitor_history` boolean
  - `allowed_domains` string[]
  - `rate_limit_per_minute` integer
  - `calendly_url` string, nullable: Calendly/scheduling URL for calendar action (e.g., https://calendly.com/company/demo)
  - `contact_form_fields` string[]: Available fields for contact form action
  - `contact_form_field_config` object, nullable: Per-field config overrides: {field_name: {label?, type?, placeholder?, options?}}
  - `enable_search_action` boolean: Allow LLM to use search action in AUTO_REPLY_RULES
  - `enable_form_action` boolean: Allow LLM to use form action to collect visitor info
  - `enable_calendar_action` boolean: 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: Allow visitors to upload file attachments (images, PDFs)
  - `max_attachment_size_mb` integer: Maximum file size in MB for attachments
  - `allowed_attachment_types` string[]: Allowed MIME types for attachments
  - `sound_enabled` boolean: Play sound when new message arrives
  - `site_search_enabled` boolean: Enable direct product search on widget owner's website
  - `website_url` string, nullable: Widget owner's website URL for product search (e.g., https://beautique-store.com)
  - `ecommerce_platform` string, nullable: E-commerce platform: shopify, woocommerce, generic, or null for auto-detect
  - `allow_voice` boolean: Enable voice call mode in the widget
  - `allow_text_during_call` boolean: Allow typing messages during an active voice/avatar call
  - `allow_avatar` boolean: Enable avatar (talking-head video) call mode in the widget
  - `show_branding` boolean: Show the 'Powered by DialogBrain' badge under the chat. Hiding it needs a paid plan for this widget.
  - `voice_greeting` string, nullable: First message the agent speaks when a voice call starts. Empty = agent waits.
  - `voice_stt_model` string, nullable: STT model: 'flux' (context-aware turn detection) or 'nova-3' (classic)
  - `max_voice_duration_seconds` integer: Maximum voice call duration in seconds
  - `display_mode` 'chat' | 'voice_only' | 'headless': 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/d84e7dc9977d?raw)