Payload Schema
When you configure your app's triggers, you must provide a payload schema. The payload schema defines the required and validated fields in your event payloads, and it's used to display available options to your users when they configure their automations.
A payload schema allows you to define scheduled events and can give your users enriched payloads by linking your trigger to a site contact. Wix also uses the payload schema to determine the available actions for a trigger.
The payload schema must be a JSON Schema object. See the tables in Schema Properties (below) for the expected structure.
Tip: To create a starter schema with sample values and required properties, use the Convert from Payload option. You can then fill in the rest of the schema as needed.
Connecting payload schema properties
When you configure your trigger to connect a contact ID or a scheduled event, you're indicating that Wix can handle your trigger in a specialized way and present additional automation configuration options to users. The requirements for each property, as well as how Wix handles these changes, are covered in this section.
Contact ID property
You can connect a payload property to a contact ID when the property's value will always be a contact ID from Wix. You can retrieve the relevant contact ID using the Contacts API.
Requirements:
This option is available only for properties where the type is "string"
and the format is "uuid".
Effect on your user's automations:
Connecting a payload property to a contact ID
allows users to use the related contact information
(such as name, emails, or phone numbers) in their automation actions.
It also allows them to email the contact as an automation action.
Scheduled event property
You can set a payload property as a scheduled event when the property's date-time will always be at some point in the future, relative to the time the event is reported. Some examples of scheduled event properties are an invoice due date or a session start time. For more information, see Overview of events.
Requirements:
This option is available only for properties
where the type is "string" and the format is "date-time".
Effect on your user's automations:
Setting a payload property as a scheduled event
allows users to configure automations to run before,
at the time of, or after the time specified in the payload.
Schema properties
These properties are at the schema's root level:
| Property | Data type | 説明 |
|---|---|---|
$schema | ストリング | When you save the trigger configuration, Wix overrides this property to set it to "http://json-schema.org/draft-07/schema". |
タイプ | ストリング | Required. Must be "object". |
properties | object | Required. Object containing payload property metadata as key-object pairs. See the properties object below for details. |
必須 | 配列 | List of property keys that are required to be present in the reported event payload. |
additionalProperties | boolean | When you save the trigger configuration, Wix overrides this property to set the value to 真の, which allows additional, unspecified properties to be sent in the payload. |
について properties object
properties is an object that contains key-object pairs.
The key name can include only alphanumeric characters or underscores
(A-Z, a-z, 0-9, _).
It cannot start with an underscore.
The paired object contains display and validation metadata. This table gives the expected data structure:
| Property | Data type | 説明 |
|---|---|---|
タイプ | ストリング | Supported values: Required. Expected data type of the payload property. 注: Only the 1st-level |
タイトル | ストリング | Required. Display name for the property. Shown to users when they create or edit an automation. |
examples | 配列 | Example values, displayed as placeholders when users test certain automation actions. Must be the same data type defined in Required in the 1st-level |
format | ストリング | Validated string format. Used only when If set to If set to |
identityType | ストリング | Supported value: If the property is specified with Connect a property to a contactId, Limited to 1 payload property. |
futureDate | boolean | If the property is specified with Allow scheduled events with predefined date & time, Limited to 1 payload property. |
項目 | object | Object that contains a list of array items. Required if |
properties | object | Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level Required if |
必須 | 配列 | List of property keys that are required to be present in the reported event payload. Used only when |
について 項目 object
項目 is an object that contains an array schema.
| Property | Data type | 説明 |
|---|---|---|
タイプ | ストリング | Required. Must be set to "object". |
properties | object | Required. Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level properties object. See the properties object above for details. |
必須 | 配列 | List of property keys that are required to be present in the reported event payload. |