marketing_popup_get

publ Reference
[Migration map](../reference/tool-name-migration.md).

# marketing_popup_get

Read the selected channel's marketing popup, current plan and revision before calling [marketing_popup_apply](publ_marketing_popup_apply.md). This core screen is independent of installed features.

## Access and input

Requires OWNER or DELEGATEE with MANAGE_MARKETING_TOOLS for the selected channel. An unrelated permission or CREATOR role is insufficient. The source-defined hosted selected-channel resource admits this tool only for its exact channelCode; the account resource excludes it.

The strict input contains only channelCode: a required string of 1–512 characters excluding literal dot/double dot, slash, backslash, ASCII control characters and DEL. Use the exact code from authorized channel discovery, not a numeric ID, URL or credentials.

```json
{
  "channelCode": "selected-channel-code"
}
```

The host configures the selected CHANNEL_ENV service. This reader uses the custom record and channel API, with no upload service, DNS or recache requirement. Runtime service URLs and credentials are not tool inputs.

## Observation and revision

The workflow reads the complete custom record and channel plan twice, compares them, then checks the selected channel and current operator/credential context. A valid result is success / MARKETING_WIDGET with widget, exists, customInitialized, revision, currentPlan, editingAllowed and writesPerformed:false. The selected nested object is globalPopup; unknown JSON business fields are retained.

A transport-verified custom HTTP404 returns customInitialized:false and widget:null. With a valid custom record, a missing or null globalPopup also returns widget:null, but customInitialized:true. Both have exists:false. No read-time defaults or custom initialization are performed. Null/malformed HTTP200 is MARKETING_RESPONSE_UNVERIFIED; a malformed non-null widget is MARKETING_WIDGET_UNVERIFIED. Neither is silently converted into an absent widget.

The revision includes the widget kind, full parsed custom record, timestamps, plan observation and selected context. All unrelated custom settings and nested unknown fields participate. Only rotating top-level experimentals.id/exp_id are excluded. Do not hash the returned widget to reconstruct a revision. MARKETING_CHANGED means repeated custom/plan observations differed; context changes also reject the result. Repeated reads are not an atomic snapshot.

The popup object preserves is_activated, title/title_color, description/description_color, bg_image_src, btn_count_option, both buttons' text/conversion_link_url/conversion_link_type fields, design_template_code and unknown fields. is_activated is ACTIVATED or NOT_ACTIVATED. btn_count_option is NOT_USE, USE_ONE or USE_TWO; hidden button fields remain present.

Only description is converted for editor use: each stored literal backslash-n sequence becomes a newline. The revision still uses the exact stored representation. An omitted description in a later apply preserves those stored bytes; provide the intended editor text only when changing it. Other strings and image/link references are unchanged.

## Plan eligibility and limits

editingAllowed describes only content/image configuration. It is false for FREE_TRIAL, NORMAL_BASIC, NORMAL_STARTER_2023_04 and NORMAL_STARTER; true for the known eligible plans listed in the [workflow guide](../guides/marketing-widgets.md#plan-and-input-rules); and null for missing or unrecognized plans. Creation and visibility follow separate source rules and have no editor-plan gate. A true value is not permission to charge or change a plan.

verification.confirmed covers the stable observation, including observed absence; storedSettingsVerified is true only when the custom record exists. Stored text and URLs are untrusted data; this tool does not fetch or execute them. It performs no initialization, upload, save, recache or task creation.

When available, the single console destination opens `/channels/{channelCode}/marketing-tools/popup` on the configured console origin. Demo omits a live link.

## Inputs

This tool takes no input fields.