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

# Update Widget

`PUT /api/v1/widgets/{widget_id}`

## Request

- Base URL: `https://api.sendseven.com`
- URL: `https://api.sendseven.com/api/v1/widgets/{widget_id}`
- Auth: HTTP bearer

Update a widget

**Required Scopes:** `widgets:update`

## Path parameters

- `widget_id` string, required

## Request body

- WidgetUpdate: Schema for updating a widget
  - `name` string, nullable
  - `config` WidgetConfigCreate: Widget configuration schema
    - `primaryColor` string: Primary brand color (hex)
    - `backgroundColor` string: Background color (hex)
    - `textColor` string: Text color (hex)
    - `fontFamily` string: Font family
    - `welcomeMessage` string: Welcome message
    - `subtitle` string, nullable: Optional subtitle
    - `buttonText` string: Button text / CTA text
    - `position` string: Position: bottom-right, bottom-left, top-right, top-left
    - `offsetX` integer: Horizontal offset in pixels
    - `offsetY` integer: Vertical offset in pixels
    - `logoUrl` string, nullable: Customer logo URL
    - `companyName` string, nullable: Company name to display
    - `channelIds` string[], nullable: List of enabled channel IDs for deep linking
    - `categoryIds` string[], nullable: List of newsletter category IDs
    - `liveChatEnabled` boolean: Enable live chat widget
    - `liveChatOnlyWhenOnline` boolean: Show live chat only when agents online
    - `liveChatOfflineMessage` string: Offline message
    - `allowChannelSwitch` boolean: Allow visitors to switch to another channel during live chat
    - `autoStartLiveChat` boolean: Automatically start live chat when widget opens (skip channel selection)
    - `liveChatPopOutEnabled` boolean: Allow visitors to pop the live chat out into a separate window
    - `liveChatSchedule` LiveChatSchedule: Weekly SCHEDULE gate for the live-chat option. When ``enabled`` is True, the availability check restricts live chat to the configured per-weekday hours, evaluated in ``timezone`` (falls back to the tenant's ``default_timezone`` when None/empty). ``days`` is keyed by the lowercase 3-letter weekday abbreviation (mon..sun); a missing/disabled day means closed.
      - `enabled` boolean: Enable the weekly schedule gate
      - `timezone` string, nullable: IANA tz to evaluate the schedule in; None/empty falls back to tenant.default_timezone
      - `days` object, nullable: Per-weekday hours keyed by mon|tue|wed|thu|fri|sat|sun
    - `fullscreenOnMobile` boolean: Display the widget fullscreen on mobile devices
    - `bubbleLayout` 'classic' | 'panel': Bubble container layout style
    - `cardLayout` 'legacy' | 'inline' | 'hero' | 'grid': Card content layout style
    - `cornerRadius` number, nullable: Corner radius in px; omit to let the frontend default apply (no hard backend default)
    - `defaultSize` 'compact' | 'tall' | 'full', nullable: Default open size of the widget panel
    - `showAgentType` boolean: Show the agent type label (bot vs. human) in the widget
    - `allowReactions` boolean: Allow visitors to react to messages in the widget
    - `launcher_icon` 'default' | 'whatsapp' | 'telegram' | 'messenger' | 'instagram' | 'sms' | 'email' | 'message_circle' | 'chat_dots' | 'sparkles' | 'help' | 'headset' | 'phone' | 'life_buoy' | 'hand_wave', nullable: Icon on the closed bubble (launcher) button. One of: default, whatsapp, telegram, messenger, instagram, sms, email, message_circle, chat_dots, sparkles, help, headset, phone, life_buoy, hand_wave. null/omitted = default icon.
    - `channelButtonStyle` 'outline' | 'filled' | 'minimal' | 'brand', nullable: Channel list button style: outline | filled | minimal | brand. null/omitted = outline.
    - `channelDisplayMode` 'full' | 'icons-only' | 'tiles', nullable: Channel list display: full | icons-only | tiles. null/omitted = full.
    - `homeLayout` 'menu' | 'composer', nullable: Home screen layout: menu (channel list) | composer (message box first). null/omitted = menu.
    - `launcherMode` 'panel' | 'speed_dial', nullable: Bubble click behaviour: panel | speed_dial (fan-out of channel buttons). null/omitted = panel.
    - `desktopHandoff` boolean, nullable: On desktop, show a QR code + web link step instead of opening messenger apps directly. null/omitted = false.
    - `prechatMode` 'form' | 'composer', nullable: Pre-chat details: form (separate step) | composer (fields inside the message box). null/omitted = form.
    - `pushEnabled` boolean: Enable browser push notifications
    - `pushAutoPrompt` boolean: Automatically prompt for push permission on page load
    - `pushPromptDelay` integer: Delay in seconds before showing auto-prompt
    - `autoStartBotId` string, nullable: UUID of bot to auto-start when live chat session begins
    - `autoStartFlowId` string, nullable: UUID of flow to auto-start when live chat session begins
    - `customCss` string, nullable: Custom CSS for widget
    - `channelId` string, nullable: DEPRECATED: Single channel ID (use channelIds instead)
    - `categoryId` string, nullable: DEPRECATED: Single category ID (use categoryIds instead)
  - `privacy_url` string, nullable
  - `is_analytics_enabled` boolean, nullable
  - `is_active` boolean, nullable

## Response `200`

Successful Response

- WidgetResponse: Schema for widget response
  - `id` string, required
  - `tenant_id` string, required
  - `name` string, required
  - `widget_type` 'card' | 'bubble', required: Types of widgets
  - `use_case` 'support' | 'newsletter', required: Widget use cases
  - `config` object, required
  - `privacy_url` string, nullable
  - `is_analytics_enabled` boolean, required
  - `is_active` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sendseven/apis/sendseven.md) · [All operations](https://skmtc.dev/sendseven/apis/sendseven/llms.txt) · [OpenAPI document](https://skmtc.dev/sendseven/apis/sendseven/revisions/ea628483e29a?raw)