App-Defined Actions — Discovery, Schemas, Input Mapping
TL;DR
- An action is
appId+actionKey. Find real ones with Resolve Actions (site catalog), then read the version active on the site with Get Runtime Action. Never invent keys. - The configuration is
appDefinedInfo.inputMapping: an object keyed ONLY by input-schema property names, with values of the schema's type — literals, or{{…}}formulas in fields the UI schema marks as dynamic. - Fields marked
updateSchemaOnChange: truereveal more inputs once set → Get Action Dynamic Input Schema. Output that depends on configuration → Get Action Dynamic Output Schema after the mapping is final, except user-defined LLM result fields: declare their override schema directly (§4). - Send an email (
triggered-emails): initialize each NEW step with Generate Action Input Mapping, persist the returned mapping unchanged, then configure content with Get / Set Email Content (§5.1, Automations Email Actions). Existing content-only edits do not initialize another email. - Entity-selector fields take ids, never display names (Automations Entity and Provider Configuration).
- Before accepting any action, prove its side effect and its recipient (§6).
1. APIs used here
Site-scoped (wix-site-id header), SDK module actionCatalog: Resolve Actions · Get Runtime Action (the version this site runs — use it) · Get Action Dynamic Input / Output Schema (+ bulk output). Paths and request shapes: Automations API Catalog §4.
2. Finding the right action
- Resolve Actions with small pages (
{"query": {"paging": {"limit": 25}}}); filter byappIdwhen known, otherwise search locally overdisplayName,description,actionKeywith a keyword ladder (phrase → domain verb/noun → synonyms). - Read the
description. A name like "Add a coupon" or "Get a …" can be a value-producing step that notifies nobody. - Get Runtime Action for the 1–3 best candidates; build against that version's
inputSchema,outputSchema,interfaceConfiguration. - An action missing from Resolve Actions is not usable on this site. The builder shows such a step as "action not found" and blocks it.
Do not use unsupported or deprecated actions — send-mail (→ triggered-emails), send-coupon-action (→ wixcoupons-retrieve_coupon + a delivery step that uses its code), wix_automations-velo_action, wix_automations-data_manipulation_code (code variable; public Create refuses it — Automations Delays Variables and Branches §4), whatsapp-send-message (WhatsApp), forward-to-zapier (Zapier), and site actions wix_automations-wix_api_integration (non-public). Match these by actionKey (+ appId), not by app or display name — other actions of the same app are fine. Use the supported replacements above; unavailable widget setup requires the automations builder.
Selection rules
- Prefer a normal built-in action over any AI action.
- Direct action beats communication: "apply the change" is the change, not an email about it — unless messaging was asked for.
- Delivery beats retrieval: "send the customer a coupon" needs a delivery step. A staging action alone is incomplete; its output must be consumed by a delivery step on the same path.
- Replacing an unsupported external integration: keep the channel (chat stays chat-like).
- AI ladder — first that fits: (1) Delegate to Aria
ai_assistants-delegate-to-assistant: autonomous agent, output NOT used downstream (exposes onlysummary); (2) Custom agentai_custom_agent_bm-delegate_to_agent: autonomous agent whose output IS used downstream; (3) Generate or analyze textwix_automations-llm_call: pure LLM over data already in the payload; no tools, no internet. "LLM step" → (3). When later steps need several structured fields, use (3) with an override output schema — not a single-string text action. - Ask the user to choose between overlapping actions only when the difference is user-facing and context doesn't decide it.
3. Reading the action
inputSchema— JSON Schema of the mapping.required= must map.oneOf/const= enum.format,wixCustomType,identityTypeas in Automations Trigger Configuration §3.interfaceConfiguration.type—GENERIC→ the builder renders a form frominputSchema+genericOptions.uiSchema(rules in §5.2).WIDGET_COMPONENT→ the app's own configuration widget, which you can't see (below).interfaceConfiguration.genericOptions.uiSchema— per-field UI hints (below). It cannot add fields.outputSchema— fields downstream steps read asvar("<namespace>.<field>"). Empty and no dynamic output → later steps must not reference its namespace.implementedMethods—validateConfiguration(the app validates your mapping on Validate Automation),getQuotaInfo. It does not tell you about dynamic schemas — decide byupdateSchemaOnChangeand by calling the dynamic-output API.
WIDGET_COMPONENT actions. The widget owns the mapping; the builder's form rules don't apply to it. In these guides an opaque widget is a WIDGET_COMPONENT action whose inputSchema does not fully describe the requested configuration. If inputSchema fully describes what the user asked for (e.g. addLabelsToContact: contactId + labelKeys), hand-author it (§5.2) and tell the user to review the step; otherwise use its dedicated provider API if available (§5.1), or explain the manual setup. If the widget can't load (its app is uninstalled), the builder shows an "app not installed" state with a Replace button instead of the settings.
Conditional fields (if/then/dependencies, e.g. a due date shown only when "add a due date" is true): set the toggle and the dependent field together, or leave both out.
UI-schema keys that change what you may write:
dynamicValuesOptions.enabled: true→ the field accepts{{…}}formulas.strict: true→ the formula must return the field's exact type/format. A field without it is static: literal only."ui:widget": "EntitySelector"+entitySelectorOptions(selectorId/tag,filters,dynamicFiltersMapping) → entity picker; value = id or array of ids (Automations Entity and Provider Configuration §1). Same for input properties carryingitemsSelectionConfiguration."ui:field": "AudienceSelector"→ app-owned recipient configuration. Use a documented provider workflow (Automations Email Actions for email); otherwise ask the user to configure it in the builder. Do not invent a generic audience mapping."ui:field": "TextSectionField"→ display-only text; never map it."ui:widget": "hidden",ui:readonly→ keep the schemadefault. Otherui:*keys are presentation only.- An input object schema’s
_UIRequiredarray lists additional required property names; map them even when absent fromrequired. In the UI schema,"ui:field": "fieldMapping"takes an object of destination-schema keys mapped to real sources; optional_ordermust list exactly those mapped keys."ui:field": "PropertyPicker"selects only paths in its declared source schema."ui:field": "SchemaViewer"is display-only; never map it. Treat unrecognized annotations as requiring their documented value contract; never invent a widget mapping.
4. Dynamic input and output schemas
- Input: a property with
updateSchemaOnChange: true(e.g. a template or form id) changes which inputs exist. Set it, then call Get Action Dynamic Input Schema with{appId, actionKey, inputMapping}(the mapping so far). The builder merges static properties with dynamic properties, with dynamic definitions replacing same-name static definitions;requiredis the deduplicated union. It merges UI-schema entries at the top level with dynamic entries winning, and ignores other dynamic input-schema top-level keys. Repeat if another controlling field is revealed. Never invent a field you expected but didn't get — it appears only after its controlling selection. The builder re-fetches this schema from your saved mapping every time the step is opened, so a dynamic key whose controlling value isn't in the mapping is dropped on the first edit. The request and endpoint are in Automations API Catalog §4; use the exact merge precedence above after each controlling selection. - Output: for
wix_automations-llm_callresult fields you define in its output configuration, declareoverrideOutputSchemadirectly (Automations Schemas and Scheduling §3); do not probe the dynamic-output SPI to discover your own declared fields or execute the AI during setup. For catalog-driven dynamic outputs, after the mapping is final, call Get Action Dynamic Output Schema (or the bulk variant) and use the returnedoutputSchemafor downstreamvar()paths. A dynamic output is a real schema — never replace it with an override (allowlist: Automations Schemas and Scheduling §3).
5. Building the input mapping
5.1 Provider-owned mappings — email and opaque widgets
Check the provider APIs registry (Automations Entity and Provider Configuration §3) before treating an opaque widget as unavailable. Send an email has a dedicated Generate Action Input Mapping API.
Before any email provider call, load Automations Email Actions and follow its complete permissions,
persistence, verification and failure-handling procedure. For each NEW triggered-emails step,
including one added during an update or duplicated into a branch, follow §1–2. An existing content
edit uses §3; recipient/type/topic changes use §4, and sender changes use §4–5. Never hand-author an
opaque email mapping. Generate Action Input Mapping is the provider initializer, distinct from
the unsupported catalog Generate Input Mapping From Intent.
Other opaque widgets with no public configuration API remain manual: do not invent their
app-owned keys. Tell the user which action to add, where, and its intended configuration.
Email attachments require the email editor; requested previews and test emails use Automations Email Actions §5. To duplicate a non-email step’s mapping, use Copy Input Mapping: POST https://www.wixapis.com/v1/actions/copy with {appId, actionKey, inputMapping} from the existing step (Set Up Automations scope). Use the returned inputMapping with a fresh action id and namespace; preserve the original step. Never use this to duplicate an email; initialize each new email separately.
5.2 Hand-authored mapping
MUST (builder renderability — the GENERIC form drops, rewrites or flags anything else):
- Keys: only properties of the current (merged dynamic) input schema. The form drops unknown keys on the first edit.
- Values: the schema's type — string→string, number/integer→number, boolean→boolean, array→array, object→object field by field (e.g. MONEY
{"value": "…", "currency": "…"}). - Every
requiredfield present. An action with visible fields and a missing/nullinputMappingis flagged "missing required info" and its panel can't be applied. - An action with no input properties (or only hidden ones): send
"inputMapping": {}— the builder writes{}itself on open otherwise. - Map fields the form would auto-fill, or opening the step silently changes the automation: fields with a schema
default(write the default or your value), everyidentityTypeinput (the form auto-maps it when exactly one matching payload path exists), requireddate/date-time/timestrings (else filled with "now"). - Enum fields (
oneOf/enum): one of the listed constants. - Entity-selector fields: real ids of the right kind and shape (Automations Entity and Provider Configuration §1).
{{…}}only in fields withdynamicValuesOptions.enabled(or anidentityTypefield), per Automations Mapping Expressions §4: number/boolean hold exactly one expression of that type; date-time a single date-time expression or ISO literal; strings may mix text and expressions. An array-typedvar()in a string field is flagged as a format mismatch.- Don't copy volatile values: dates →
now()/payload dates; ids → resolved at build time, never from examples. - Keep what the user describes for one field in that field. A subject described as "Order received, then the customer's first name" is one
subjectstring mixing text and expressions ("Order received {{var(…)}}"); don't split its values into other fields, such as a message'sfieldsrows.
Value kinds:
{
"subject": "Welcome, {{var(\"contact.name.first\")}}!",
"priority": "HIGH",
"notifyCustomer": true,
"amount": {
"value": "{{var(\"order.total.value\")}}",
"currency": "{{var(\"order.total.currency\")}}"
},
"contactId": "{{var(\"contactId\")}}",
"labelKeys": ["<label-key-1>"],
"note": "Order {{var(\"order_number\")}} from {{var(\"createTask-1.taskId\")}}"
}Trigger fields have no prefix; action outputs use the step's namespace (e.g. createTask-1.taskId); set-variables use setVariable.<key>.
Optional inputs with no default (e.g. isDueDate, onlyWhenAvailable): omit them unless the request needs them. A deprecated defaulted input (e.g. labelIds: [] on add-label) may be omitted.
Process: (1) fetch the effective schema (§4) before you write a mapping or any script that saves one — never guess an action's field names → (2) classify required vs optional; map optional fields only with a real source → (3) source each required field from payload, upstream outputs or the user; ask for user-specific content (text, recipient, which entity) → (4) build → (5) self-check against the list above → (6) Validate Automation.
5.3 Validation errors on actions
Error shape, error type → fix, and how the builder shows each: Automations Validation and Persistence §2. Must-know here: fix the field named by configurationError.fieldKey — never delete a field to silence it; CRITICAL blocks (status INVALID), WARNING doesn't but must be reported; a var() path that doesn't exist may NOT be reported — verify paths yourself.
6. Side-effect and recipient review
This section owns the semantic review (you, not code) required for every action before acceptance. Confirm from its catalog entry and effective schemas:
- Verb: it performs what was asked (assign/add/send/create/update/delete). A read-only "get" action can't satisfy a mutation; sending a message about a change is not the change.
- Entity: the affected entity has a matching input (e.g. a label picker for "add label").
- Identity input: the id it acts on, with the right
identityType. - Recipient lineage (email, chat, SMS, push): write down
{requestedAudience, resolvedAudienceKind (contact|visitor|owner|contributor|label|phone|device), resolvedIdentityPath}. The trigger contact and a contact created upstream are different people even if both arecontactId. Wording never proves the recipient.- Email: the audience fields decide — read
selectedAudience/contactIdexactly as in Automations Email Actions §3 ("Recipient encoding"). A rootcontactIdortriggerContactExcludedalone doesn't prove who receives it. - Chat (
send-message): only a schema-supported contact-id or visitor-id route; owner/team chat needs a different, proven component or a clarification. - SMS / push: prove the schema-supported contact, audience, phone or device route.
- Email: the audience fields decide — read
Under-required schemas: send-message requires only contactId/visitorId (anyOf), not the text. Always map the message too — a required-fields-only mapping ships an empty action.
For inbox-send-message, when the user requests an Inbox note for or about a contact, map contactId from the verified contact identity even if the runtime schema does not list it as required. Putting that contact's details in formMessage.fields does not associate the note with the contact.
7. Common failure modes
Missing required field or content-free required-only mapping · fabricated user values instead of asking · type/format mismatch, free text in an enum, a name in an id field · var() to a path absent from the aggregated schema (or from an unfetched dynamic schema) · formula in a static field or an unknown function · wrong verb or recipient · a single-value field filled from an array · unmapped defaults / identity fields / missing {} (the builder rewrites the step on first open).