thincms_create_popup
Creates a new popup/CTA linked to a form, configuring display type, targeting rules, and trigger logic. Handles presentation, suppression, and mobile behavior.
Instructions
Create a new popup/CTA. Each popup is linked to an existing form (by formId) which handles the actual data collection. The popup provides the presentation container, trigger logic, and targeting rules. Display types: 'overlay' (centered modal), 'sticky-top'/'sticky-bottom' (fixed bars), 'slide-in' (bottom-right card). On mobile, overlay auto-downgrades to sticky-bottom to avoid Google's interstitial penalty.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Popup name (required) | |
| slug | No | URL slug (auto-generated from name if omitted) | |
| formId | Yes | ID of the form to display inside the popup (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable popup (default: true) | |
| bodyText | No | Body text shown between headline and form | |
| headline | No | Headline text shown above the form | |
| priority | No | Priority (higher = more important). Specific-scope always beats site-wide regardless of priority. Default: 0 | |
| customCss | No | Custom CSS to override default popup styles | |
| targeting | No | Page targeting rules (default: site-wide) | |
| displayType | No | Display type (default: overlay) | |
| suppressDays | No | Days to suppress after visitor dismisses (default: 30) | |
| ctaButtonText | No | CTA button text shown in step 1 of the two-step popup flow (default: 'Sign up'). Examples: 'Sign up', 'Book now', 'Get started', 'Download' | |
| mobileEnabled | No | Show on mobile devices (default: true) | |
| triggerConfig | No | Trigger configuration (default: time-delay 8s) | |
| mobileDisplayType | No | Override display type on mobile (default: auto-downgrade overlay to sticky-bottom) | |
| suppressOnConvert | No | Days to suppress after visitor submits the form (default: 180) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |