bricks_update_popup_settings

Phase 4IntermediateComplexity: 5/10

Update popup triggers, frequency limits, and display rules

Overview

Updates the trigger and/or appearance settings of an existing Bricks popup. Only the provided fields are changed — other settings remain untouched. This is a partial update tool: you can change just the trigger type without affecting the popup size, or adjust the animation without changing the trigger. Ideal for iterating on popup behavior after initial creation.

Key Features

Partial updates

Only changes the fields you specify — existing trigger and popup settings remain untouched for unspecified fields.

Trigger reconfiguration

Change trigger type, delay, scroll distance, repeat behavior, and cookie duration without recreating the popup.

Appearance tuning

Adjust position, animation, size, overlay, z-index, and close behavior independently.

Frequency adjustment

Update per-page, per-session, and total lifetime display limits based on analytics data.

When to Use

When changing a popup trigger type (e.g., switching from load to exit_intent)
When adjusting popup timing (delay, scroll distance, frequency limits)
When updating popup appearance (position, animation, size)
When enabling or disabling AJAX loading after observing performance impact
When changing frequency limits based on analytics

Prerequisites

Popup must exist (valid popup_id from bricks_create_popup)

When NOT to Use

When creating a new popup — use bricks_create_popup instead
When updating the popup visual content — use bricks_update_template_content with the popup ID
When changing popup display conditions — use bricks_update_template_conditions with the popup ID

Parameters

3 Total Parameters1 Required2 Optional

popup_idnumberREQUIRED

Popup template post ID.

triggerobjectoptional

Updated trigger configuration. Fields: type (load/scroll/exit_intent/click/timed/inactivity), delay (ms), scroll_distance, scroll_unit (px/%), repeat (once/every_visit/always), cookie_days.

popup_settingsobjectoptional

Updated appearance settings. Fields: width, height, position, animation, animation_out, animation_duration, overlay_color, close_on_overlay_click, close_on_esc, show_close_button, disable_page_scroll, z_index, limit_per_page, limit_per_session, limit_total, ajax_load.

Code Examples

Warning: Undefined array key "example_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 10

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Change popup trigger from load to scroll

JSON

{
  "tool": "bricks_update_popup_settings",
  "params": {
    "popup_id": 42,
    "trigger": {
      "type": "scroll",
      "scroll_distance": 50,
      "scroll_unit": "%"
    }
  }
}

Response

{
  "success": true,
  "trigger": {
    "type": "scroll",
    "scroll_distance": 50,
    "scroll_unit": "%",
    "repeat": "once",
    "cookie_days": 30
  },
  "popup_settings": {
    "width": "600px",
    "position": "center",
    "animation": "zoomIn"
  }
}

Warning: Undefined array key "example_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 10

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Update frequency limits and enable AJAX loading

JSON

{
  "tool": "bricks_update_popup_settings",
  "params": {
    "popup_id": 42,
    "popup_settings": {
      "limit_per_session": 1,
      "limit_total": 3,
      "ajax_load": true
    }
  }
}

Response

{
  "success": true,
  "trigger": { "type": "scroll", "scroll_distance": 50, "scroll_unit": "%" },
  "popup_settings": {
    "width": "600px",
    "position": "center",
    "limit_per_session": 1,
    "limit_total": 3,
    "ajax_load": true
  }
}

Common Mistakes

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

The trigger object is merged, not replaced. You can safely provide just the fields you want to change. For example, providing only { type: "scroll" } will change the type but keep existing delay, repeat, and cookie_days values.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

This tool updates visual/behavioral settings, NOT display conditions. To change which pages show the popup, use bricks_update_template_conditions with the popup ID.

Tips & Warnings

Iterative approach: Create popups with basic settings first, then use bricks_update_popup_settings to fine-tune based on testing. This is faster than recreating the popup each time.

AJAX loading: Enable ajax_load if the popup has heavy content (images, forms, embeds). Disable it if the popup must appear instantly on trigger (e.g., cookie consent that must render immediately).

Display conditions: Remember that popup display conditions are managed separately via bricks_update_template_conditions, not through this tool.

Return Values

Field	Type	Description
`success`	boolean	Whether the settings were successfully updated.
`trigger`	object	The full trigger configuration after the update.
`popup_settings`	object	The full popup settings after the update.

Related Tools

Technical Details

Tool ID

bricks_update_popup_settings

API Endpoint

/bricks-mcp/v1/popups/{popup_id}/settings

HTTP Method

PUT

Namespace

templates

Source File

templates/popups.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release

20250101