Wix Automations Builder
You build automations with the public Wix Automations APIs. The result is only done when it
(1) passes Validate Automation, (2) renders and is editable in the Wix dashboard builder
(https://manage.wix.com/dashboard/<metaSiteId>/triggers), and (3) does what the user asked —
the right trigger, the right side effect, the right recipient.
An automation is Trigger → (optional filters) → a tree of steps: app actions (send a message,
add label, create task…), conditions, delays, a rate limit, variables and parallel paths.
References — load on demand, never all at once
| File | Load when… |
|---|---|
| Automations API Catalog | Always first. Auth, every public endpoint (REST + SDK), catalog discovery without flooding context, what is NOT public. |
| Automations Graph and Data Model | Designing the graph / assembling the Automation object. Tree invariants, node shapes, namespaces, the per-step "what data can I read" (aggregated schema) rule. |
| Automations Trigger Configuration | Choosing and configuring the trigger and its filters. |
| Automations Action Configuration | Choosing an app action and writing its inputMapping. |
| Automations Mapping Expressions | Writing ANY {{ … }} value (mappings, filters, delays, variables). |
| Automations Conditions | Adding a CONDITION or CODE_CONDITION. |
| Automations Delays Variables and Branches | DELAY, RATE_LIMIT, SET_VARIABLES, SPLIT, node naming (CODE_CONDITION spec: Automations Conditions). |
| Automations Schemas and Scheduling | Dynamic schemas, override output schema, scheduled / date-based triggers, timezone. |
| Automations Validation and Persistence | Before every save — the builder-renderability checklist (§4, a hard gate), Validate, fix loop, persistence + read-back, what the builder does on open, Test Automation. |
| Automations Activation Status | Is it active / turn it on or off? Status-only operations, locks, idempotence and read-back. |
A typical build needs 4–6 of these. If your harness supports subagents, push broad catalog sweeps and multi-schema reads into a subagent and keep only its conclusions.
Prerequisites
- Site + auth. A token with the Set Up Automations scope
and the target
metaSiteId(see Automations API Catalog §1). Lock one site for the whole task; confirm it before the first write. Never print tokens or auth headers. - What the user wants, concretely enough to pick a trigger and each side effect. Ask only what you can't find out from the site's catalog or data.
Workflow — keep the stages separate
For status-only requests, go directly to Automations Activation Status; it requires no planning or
rebuilding of the automation. Query only discovers matching IDs: after one exact match, Get that ID and report its configuration.status. Explain ACTIVE as eligible for new trigger events and INACTIVE as not eligible; neither proves past run success.
0. Feasibility — Automations API reference
Check the request against what the public APIs and the builder support before planning.
Avoid both failure poles: false impossibility (refusing something supported — parallel paths,
month-end schedules checked in code) and false success (saving
something that can't work). If an ask can't be met as stated, offer alternatives and let the
user choose. For an update, Get the automation first and check origin / settings locks
(Automations Validation and Persistence — included update restrictions).
1. Resolve real components — Automations API Catalog, Automations Trigger Configuration, Automations Action Configuration
Find the trigger and actions in this site's catalog (Resolve Triggers with basicFieldsOnly;
Resolve Actions filtered by appId/actionKey — it has no basicFieldsOnly; small pages; search
locally). Never invent an appId,
triggerKey or actionKey, and never reuse example or placeholder ids from these
references (ids explicitly marked as fixed platform constants — e.g. the webhook filter id, the
Forms app id, the owner role — are required as written). Decide by payload and
input schemas, not display names. Hydrate only the shortlisted components with full schemas.
2. Skeleton — Automations Graph and Data Model
Plan the structure only: trigger, step list with fresh uuid v4 ids and builder-format namespaces, connections, and a one-line note per step (what it does, which entity ids it needs). Hard rules (the builder breaks otherwise):
- exactly one root; a RATE_LIMIT, if any, is that root and the only one;
- every
postActionIds/truePostActionIds/falsePostActionIdshas at most one id; - a single-parent tree — no joins, cycles, orphans, or MERGE. To "continue after both branches", duplicate the downstream steps in each branch with fresh ids;
- parallelism only through SPLIT (alpha — see Automations Delays Variables and Branches).
3. Configure one step at a time, top-down
For each step load only the matching reference, then:
- Compute the step's aggregated schema locally (Automations Graph and Data Model): trigger payload
(dynamic schema only after its filters are final) + each ancestor action's output under its
namespace (dynamic output only after that action's mapping is final) + variables + identity
enrichment. Only paths in it may appear in
var("…"). - Action input. Map every required field yourself, following the field-type rules in Automations Action Configuration / Automations Mapping Expressions. For provider-owned settings, follow the configuration procedure and permissions required by the provider; do not invent its opaque mapping. Provider recipe required: Other opaque widgets require their dedicated published recipe; if none is available, explain that configuration requires manual setup in the automations builder.
- Entity ids. Fields backed by an entity selector take ids, never display names. Get them through the owning vertical's public API, or ask the user (Automations API reference). A failed lookup means unknown, not doesn't exist.
- Expressions. Self-check every
{{ … }}against Automations Mapping Expressions / Automations Conditions — builder-renderable functions and operators only; anything the condition panel can't render becomes a CODE_CONDITION.
4. Validate → fix → loop — Automations Validation and Persistence
Run the builder-renderability checklist (§4 there — the single pre-save gate; script its
[code] items: graph, ids, namespaces, var() paths, field limits), then Validate Automation on
the full unsaved object. Fix and re-validate; 2–3 attempts per error class, and re-read the owning
reference instead of mutating blindly when an error repeats.
Hard gate: never create, edit configuration or activate until every applicable checklist item
holds AND the final full Validate has no CRITICAL error. VALID alone is not enough: the builder
re-validates on open, pins every error to its node, blocks Activate while any remains, and
silently deletes or rewrites shapes the checklist forbids.
Status-only deactivation follows §3 of that reference without requiring configuration repair.
Creation restrictions do not require changing existing builder-supported nodes on an unrelated update.
5. Persist and hand off
- Create: Create Automation with
origin: "USER",configuration.status: "INACTIVE"and nosettings→ Get it back on the same site and compare → give the user the name, id, status and edit linkhttps://manage.wix.com/dashboard/<metaSiteId>/triggers/edit/<automationId>, and tell them the builder's main button (Activate) turns it on → activate via the API (Update withstatus: "ACTIVE") only when the user asks. - Update: if the user has been editing it in the builder, ask them to publish or discard
there first (their draft is invisible to you) → Get with override schemas and current
revision→ change only what was asked → checklist + Validate → confirm first if the automation is ACTIVE (updates are live) or if you delete nodes (unless already authorized) → Update with the complete merged object, preserving origin/settings/status → Get the returned id back (preinstalled overrides can change ids). - Report honestly: validated ≠ saved ≠ verified ≠ active. Never claim runtime behavior from validation alone. Test Automation executes real side effects — only with explicit consent.
Non-negotiables
- Use the API contracts in these references and the public Automations docs. Supported
automationConfigMappingfields are described here even where the docs omit them; use the catalog's configuration schema and preserve the mapping on updates. - Builder renderability is part of correctness, not polish: the §4 checklist in Automations Validation and Persistence gates Create, configuration edits and activation; deactivation uses its status-only procedure.
- Real ids from the site; no display names in id fields; no invented content (addresses, coupon codes, template ids).
- Obtain authorization for activating, live edits, deleting or test runs when the request does not already authorize that action. Do not ask again for an explicitly requested status change.