widgets
widgets.create
Create Widget
Effects: write
Create a new livechat widget for your website.
The widget will be created with default settings.
You can customize theme, auto-reply mode, and more.
Use this when user wants to add a chat widget to their site.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
allow_voice | boolean | no | Master switch for voice — set true to show the mic so visitors can talk to the agent. Everything else voice-related 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 voice off (the default). |
auto_reply_mode | string | no | Auto-reply mode: 'draft' (review before sending) or 'auto' (send immediately) (one of draft, auto; default draft) |
display_mode | string | no | Visual mode of the widget. Pick exactly one: - 'chat' (default): full chat panel + voice mic — use for support / sales / general. - 'voice_only': mic-only bubble that launches a voice call directly — pick only when the user explicitly asks for a voice-only widget (e.g. 'just a voice button', 'no chat, just call'). - 'headless': no UI; customer drives via window.DialogBrain JS API — pick only when the user explicitly says 'embed in our own design' / 'no widget chrome'. (one of chat, voice_only, headless; default chat) |
header_title | string | no | Title shown in chat header (default Chat with us) |
name | string | yes | Name for the widget (e.g., 'Website Chat', 'Support Widget') |
position | string | no | Widget position on screen (one of bottom-right, bottom-left; default bottom-right) |
primary_color | string | no | Primary color for widget theme (hex, e.g., '#2563eb') (default #2563eb) |
voice_button_label | string | no | 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 omitted. |
widgets.delete
Delete Widget
Effects: delete
Delete a livechat widget permanently.
This will remove the widget and its embed code will stop working.
Its conversations and their messages are deleted with it: the widget IS the channel, and thread.channel_account_id cascades.
Use this when user wants to remove a chat widget.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
widget_id | integer | yes | ID of the widget to delete |
widgets.get
Get Widget
Effects: read
Get full configuration of a single livechat widget.
Returns all settings including theme, identification, actions, and more.
Use this when user wants to see or verify a specific widget's settings.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
widget_id | integer | yes | ID of the widget to retrieve |
widgets.get_embed_code
Get Widget Embed Code
Effects: read
Get the embed code snippet for a livechat widget.
Returns HTML/JavaScript code to add to your website.
The code should be placed before the closing </body> tag.
Use this when user wants to install the chat widget on their site.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
widget_id | integer | yes | ID of the widget to get embed code for |
widgets.list
List Widgets
Effects: read
List all livechat widgets.
Returns widgets with their configuration, embed code, and status.
Use this when user wants to see their widgets or chat widgets.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
active_only | boolean | no | Only return active widgets. OMIT to include inactive widgets too. |
widgets.update
Update Widget
Effects: write
Update an existing livechat widget configuration.
You can change name, theme, auto-reply mode, and other settings.
Only provided fields will be updated.
Use this when user wants to modify their chat widget settings.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
allow_voice | boolean | no | 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. |
allowed_domains | array | no | List of allowed domains for the widget |
auto_reply_mode | string | no | Auto-reply mode: 'draft' or 'auto'. OMIT to leave the auto-reply mode unchanged. (one of draft, auto) |
calendly_url | string | no | Booking URL for calendar action (e.g., 'https://calendly.com/yourname') |
color_scheme | string | no | Widget color scheme. 'auto' follows the visitor's OS dark/light mode preference. OMIT to leave the color scheme unchanged. (one of light, dark, auto) |
contact_form_fields | array | no | Fields to collect in contact form (e.g., ['name', 'email', 'phone']) |
display_mode | string | no | Visual mode of the widget. Pick exactly one: - 'chat': full chat panel + voice mic — default for support / sales / general. - 'voice_only': mic-only bubble that launches a voice call directly — pick only when the user explicitly asks for a voice-only widget. - 'headless': no UI; customer drives via window.DialogBrain JS API — pick only when the user explicitly says 'embed in our own design'. OMIT to leave the display mode unchanged. (one of chat, voice_only, headless) |
enable_calendar_action | boolean | no | Enable or disable the calendar booking action button. OMIT to leave this flag unchanged. |
enable_form_action | boolean | no | Enable or disable the contact form action button. OMIT to leave this flag unchanged. |
enable_search_action | boolean | no | Enable or disable the search action button. OMIT to leave this flag unchanged. |
greeting_behavior | string | no | 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. (one of notification, auto_open, on_open) |
greeting_delay_seconds | integer | no | Delay in seconds before the proactive greeting appears (0–300). 0 = send immediately on page load. Default: 30. |
greeting_enabled | boolean | no | Enable or disable the proactive greeting. OMIT to leave this flag unchanged. |
greeting_text | string | no | Custom greeting message shown when visitor opens the chat (e.g., 'Hello! How can I help you today?') |
header_subtitle | string | no | Subtitle shown in chat header |
header_title | string | no | Title shown in chat header |
identification_fields | array | no | Fields to require for visitor identification (e.g., ['name', 'email']) |
is_active | boolean | no | Enable or disable the widget. OMIT to leave the active flag unchanged. |
launcher_color | string | no | Color of the closed launcher bubble ONLY (hex, e.g., '#ffffff'). Use when the site pairs a light button with a dark panel and one colour cannot express both. Pass an empty string to clear it and let the launcher follow primary_color. Text and glyphs pick themselves from the background, so a light value stays readable. |
max_voice_duration_seconds | integer | no | Hard cap on a single voice call from this widget, in seconds (default 300). OMIT to leave the cap unchanged. |
name | string | no | New name for the widget |
position | string | no | Widget position on screen. OMIT to leave the position unchanged. (one of bottom-right, bottom-left) |
primary_color | string | no | 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. |
require_identification | boolean | no | Require visitor to identify before chatting. OMIT to leave the identification policy unchanged. |
returning_greeting_text | string | no | 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. |
show_visitor_history | boolean | no | Show full chat history to returning visitors. OMIT to leave this flag unchanged. |
voice_button_label | string | no | 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. |
voice_greeting | string | no | 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. |
website_url | string | no | Website URL for product/site search integration |
widget_id | integer | yes | ID of the widget to update |