Sample Flows

This article shares some possible use cases your app could support, as well as sample flows that could support each use case. You're not limited to these use cases, but they can be a helpful jumping off point as you plan your app's implementation.

Trigger automations when a visitor submits a form from your service

This example shows how you can allow site collaborators to create automations that are triggered when someone submits a form to your service.

Trigger configuration prerequisites

When configuring your trigger in the Wix Developers Center, use these sample settings:

  • Set Trigger name to "Form submitted" and Trigger key to "form_submitted".

  • Create a payload schema that includes at least a contact_id property:

    Copy
    1
    {
    2
      "$schema": "http://json-schema.org/draft-07/schema#",
    3
      "type": "object",
    4
      "required": [
    5
        "contact_id"
    6
      ],
    7
      "properties": {
    8
        "form_id": {
    9
          "title": "Form ID",
    10
          "type": "string",
    11
          "format": "uuid",
    12
          "examples": [
    13
            "ce0683a5-d93a-5ee1-8519-ed7fe9177293"
    14
          ]
    15
        },
    16
        "submission_id": {
    17
          "title": "Submission ID",
    18
          "type": "string",
    19
          "format": "uuid",
    20
          "examples": [
    21
            "5b674360-669d-5ed1-a7fe-2c6dd8838844"
    22
          ]
    23
        },
    24
        "submission_time": {
    25
          "title": "Submission time",
    26
          "type": "string",
    27
          "format": "date-time",
    28
          "examples": [
    29
            "2022-10-27T15:15:39+00:00"
    30
          ]
    31
        },
    32
        "contact_id": {
    33
          "title": "Wix contact ID",
    34
          "type": "string",
    35
          "format": "uuid",
    36
          "examples": [
    37
            "3e884e7f-da65-53dc-ab09-3655e283dd40"
    38
          ]
    39
        },
    40
        "first_name": {
    41
          "title": "First name",
    42
          "type": "string",
    43
          "examples": [
    44
            "Juan"
    45
          ]
    46
        },
    47
        "last_name": {
    48
          "title": "Last name",
    49
          "type": "string",
    50
          "examples": [
    51
            "Dorian"
    52
          ]
    53
        },
    54
        "email": {
    55
          "title": "Email",
    56
          "type": "string",
    57
          "format": "email",
    58
          "examples": [
    59
            "juan.dorian@example.com"
    60
          ]
    61
        },
    62
        "marketing_email_opt_in": {
    63
          "title": "Opted in to marketing emails",
    64
          "type": "boolean",
    65
          "examples": [
    66
            false
    67
          ]
    68
        }
    69
      }
    70
    }

  • In Connect your schema properties, select Connect a property to a contactId, then select your contact_id payload property from the drop-down list:

Report form submission events

Implement this flow to report when a visitor submits the form on your service:

  1. When the form is submitted, use Query Contacts (Contacts API) to find a site contact with the submitted email value. If no results are returned, use Create Contact to create a new site contact. In both cases, save the returned contactId.

  2. Construct your payload with the form submission data and metadata, and include the returned contactId from step 1:

    Copy
    1
    {
    2
      "form_id": "ce0683a5-d93a-5ee1-8519-ed7fe9177293",
    3
      "submission_id": "5b674360-669d-5ed1-a7fe-2c6dd8838844",
    4
      "submission_time": "2022-10-27T15:15:39+00:00",
    5
      "contact_id": "3e884e7f-da65-53dc-ab09-3655e283dd40",
    6
      "first_name": "Juan",
    7
      "last_name": "Dorian",
    8
      "email": "juan.dorian@example.com",
    9
      "marketing_email_opt_in": false
    10
    }

  3. Call Report Event with the payload generated in step 2:

    Copy
    1
    {
    2
      "triggerKey": "form_submitted",
    3
      "payload": {
    4
        // Payload generated in step 2
    5
      }
    6
    }

Report and cancel scheduled events when a visitor books an appointment from your service

This example shows how you can allow site owners to create Wix automations based on an appointment's start time, which is a scheduled event. It also covers how to cancel the event's remaining actions if the appointment becomes no longer relevant.

Trigger configuration prerequisites

For this flow, you'll set up 2 triggers in the Wix Developers Center using the settings specified below. You can use the same payload for both triggers.

Both triggers: The payload

For both triggers, create a payload schema that includes at least contact_id and appointment_time properties:

Copy
1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "type": "object",
4
  "required": [
5
    "appointment_time",
6
    "contact_id"
7
  ],
8
  "properties": {
9
    "appointment_id": {
10
      "title": "Appointment ID",
11
      "type": "string",
12
      "format": "uuid",
13
      "examples": [
14
        "eeda0937-24c6-56a1-83ea-e58cba67f84c"
15
      ]
16
    },
17
    "appointment_time": {
18
      "title": "Appointment start time",
19
      "type": "string",
20
      "format": "date-time",
21
      "examples": [
22
        "2022-10-27T15:15:39+00:00"
23
      ]
24
    },
25
    "appointment_duration_in_mins": {
26
      "title": "Appointment duration (minutes)",
27
      "type": "integer",
28
      "examples": [
29
        30
30
      ]
31
    },
32
    "contact_id": {
33
      "title": "Contact ID",
34
      "type": "string",
35
      "format": "uuid",
36
      "examples": [
37
        "7d8253a8-4768-5872-8b32-65d5efc982a4"
38
      ]
39
    },
40
    "email": {
41
      "title": "Email",
42
      "type": "string",
43
      "format": "email",
44
      "examples": [
45
        "juan.dorian@example.com"
46
      ]
47
    },
48
    "first_name": {
49
      "title": "First name",
50
      "type": "string",
51
      "examples": [
52
        "Juan"
53
      ]
54
    },
55
    "last_name": {
56
      "title": "Last name",
57
      "type": "string",
58
      "examples": [
59
        "Dorian"
60
      ]
61
    }
62
  }
63
}

Trigger 1: Appointment booked

  • Set Trigger name to "Appointment booked" and Trigger key to "appointment_booked".

  • Use the payload schema from above.

  • In Connect your schema properties, select Connect a property to a contactId, then select your contact_id payload property from the drop-down list.

Trigger 2: Appointment started

  • Set Trigger name to "Appointment started" and Trigger key to "appointment_started".

  • Use the payload schema from above.

  • In Connect your schema properties, use these settings:

    • Select Connect a property to a contactId, then select your contact_id payload property from the drop-down list.

    • Select Allow scheduled events with predefined date & time, then select your appointment_time payload property from the drop-down list.

Handle appointment scheduling and cancellation events

  1. When the form is submitted, use Query Contacts (Contacts API) to find a site contact with the submitted email value. If no results are returned, use Create Contact to create a new site contact. In both cases, save the returned contactId.

  2. Generate an appointment_id in UUID format, and store it in your database. This ID is required if you need to cancel the event.

  3. Construct your payload with the appointment data. Include the returned contactId from step 1 and the generated appointment_id from step 2:

    Copy
    1
    {
    2
      "appointment_id": "eeda0937-24c6-56a1-83ea-e58cba67f84c",
    3
      "appointment_time": "2022-10-27T15:15:39+00:00",
    4
      "appointment_duration_in_mins": 30,
    5
      "contact_id": "7d8253a8-4768-5872-8b32-65d5efc982a4",
    6
      "email": "juan.dorian@example.com",
    7
      "first_name": "Juan",
    8
      "last_name": "Dorian"
    9
    }

  4. Call Report Event for each trigger with the payload generated in step 3. Set externalEntityId to the appointment_id generated in step 2. This will allow your app to cancel any pending events in your user's automations if the appointment is canceled:

    Report event for trigger 1: Appointment booked

    Copy
    1
    {
    2
      "triggerKey": "appointment_booked",
    3
      "externalEntityId": "eeda0937-24c6-56a1-83ea-e58cba67f84c",
    4
      "payload": {
    5
        // Payload generated from step 3
    6
      }
    7
    }

    Report event for trigger 2: Appointment started

    Copy
    1
    {
    2
      "triggerKey": "appointment_started",
    3
      "externalEntityId": "eeda0937-24c6-56a1-83ea-e58cba67f84c",
    4
      "payload": {
    5
        // Payload generated from step 3
    6
      }
    7
    }

  5. If the appointment is canceled before the start time, call Cancel Event for each trigger. Set externalEntityId to the appointment_id generated in step 2, which you should have stored in your database.

    Cancel event for trigger 1: Appointment booked

    Copy
    1
    {
    2
      "triggerKey": "appointment_booked",
    3
      "externalEntityId": "eeda0937-24c6-56a1-83ea-e58cba67f84c"
    4
    }

    Cancel event for trigger 2: Appointment started

    Copy
    1
    {
    2
      "triggerKey": "appointment_started",
    3
      "externalEntityId": "eeda0937-24c6-56a1-83ea-e58cba67f84c"
    4
    }
Was this helpful?
Yes
No