Toggle Block

The toggle block renders a labeled on/off switch. Requires channel mode: "interactive". Set send_on_change: true to fire an input_change webhook when the toggle changes; otherwise the value is only sent as part of card_state when a button is clicked.

Fields

Field	Type	Required	Description
type	string	Yes	"toggle"
label	string	Yes	Label displayed next to the toggle
enabled	boolean	Yes	Initial on/off state
disabled	boolean	No	Prevents the user from changing the toggle
description	string	No	Small helper text below the label
clear_on_submit	boolean	No	Reset to initial enabled state when any button in the card is pressed
send_on_change	boolean	No	Send an input_change webhook when the toggle changes

Examples

Basic Toggle

{
  "type": "toggle",
  "label": "Enable Notifications",
  "enabled": true
}

With Description

{
  "id": "maintenance-toggle",
  "type": "toggle",
  "label": "Maintenance Mode",
  "enabled": false,
  "description": "Pauses all incoming orders while enabled"
}

Read-only / Disabled

{
  "type": "toggle",
  "label": "Auto-assign",
  "enabled": true,
  "disabled": true
}

Feature Flag

{
  "id": "dark-mode-flag",
  "type": "toggle",
  "label": "Dark Mode Beta",
  "enabled": false,
  "description": "Roll out to 10% of users"
}

Webhook Payload

Fired only when send_on_change: true. Triggered immediately when the toggle is flipped.

{
  "type": "input_change",
  "card_id": "card-uuid",
  "payload": {
    "block_type": "toggle",
    "value": true
  }
}

value is true when toggled on, false when off.

Tip: The toggle state is always included in the card_state of any button click, so send_on_change is only needed if you want to react immediately without waiting for a button press.

Patching

Update Toggle State

After receiving the webhook, you can sync the toggle back:

{
  "id": "maintenance-toggle",
  "patch": {
    "enabled": true,
    "description": "System is in maintenance mode"
  }
}

Lock the Toggle

{
  "id": "maintenance-toggle",
  "patch": {
    "disabled": true
  }
}