See related
No related articles

Create an advanced form

Last Update: Sep 2024 • Est. Read Time: 11 MIN
To check plan availability, see the pricing page.

Forms offer an easy way for customers to get connected with your support team. Kustomer's standard forms provide an out-of-the-box contact form with minimal setup, but you can also created advanced forms for greater flexibility and customization.

In this article, we'll explain how to convert an existing form into an advanced form, and share an example of one way to reference custom attributes in an advanced form.

Who can access this feature?
User typesAdmins can access these settings pages.


In this article

Prerequisites

Before following the steps in this article, you should first be familiar with workflows, forms, and custom attributes.

You will also need to have an existing basic form already set up that you wish to convert into an advanced form. Set this up in advance before proceeding with the steps in this guide.

Create a form hook

The first step in this process will be to create a form hook. This form hook will take the data from a form submission and send it to an ingest workflow via a POST request.

To create a form hook:

  1. Go to Settings > Platform > Inbound Webhooks.
  2. Select Add Inbound Webhook.
  3. Give the hook a name and description and set the type to form. As a best practice, we always recommend adding clear, descriptive titles to hooks so your admin team can remember what this hook does in the future.
  4. Select Create to save the hook.
  5. To find your new hook, select the Form Hooks tab in the Inbound Webhooks settings.
  6. Locate your new hook and go to Menu  to select Copy Hook Address.

Save this hook address to a secure location to use later in this guide.

Create ingest workflow

Next, you will create the workflow that will be responsible for ingesting data through the POST request.

  1. Go to Settings > Platform > Workflows.
  2. Select Add Workflow, and choose Custom Workflow.
  3. Name the new workflow and add a description to help you remember what this workflow does in the future.
  4. Leave he Callable Workflow toggle off.
  5. Select Create. The workflow editor will open.
  6. Open the Workflow Options menu in the toolbar and select Edit Workflow JSON.
  7. A modal appears where you can edit the code for this workflow. Select and delete all the current JSON code.
  8. Copy the below code block, and paste it into the JSON text field in your Workflow Editor.
  9. Then, select Update to save the changes to the workflow and dismiss the JSON editor.
     {
  "description": "",
  "name": "form-ingest-v3",
  "steps": [
    {
      "transitions": [
        {
          "target": "4ulllrCjT",
          "condition": {
            "op": "contains",
            "values": [
              "{{#each steps.1.attributes.data.lastDeflection.articles}}{{this.deflected}}{{/each}}",
              "true"
            ]
          },
          "meta": {
            "name": "Deflected"
          }
        },
        {
          "target": "RzUykx4XT",
          "condition": {
            "op": "eq",
            "values": [
              "true",
              "true"
            ]
          },
          "meta": {
            "name": "Not Deflected"
          }
        }
      ],
      "errorCases": [],
      "id": "dR1mpnOzE",
      "action": "kustomer.conversation.find-by-external-id",
      "params": {
        "externalId": "/#steps.1.attributes.data.externalId"
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [
        {
          "target": "ZncXLm_TD",
          "condition": {
            "op": "exists",
            "values": [
              "/#steps.Hgvl_Nte4.id",
              ""
            ]
          },
          "meta": {
            "name": "Customer Exists"
          }
        },
        {
          "target": "_e8mq0ChF",
          "condition": {
            "op": "dne",
            "values": [
              "/#steps.Hgvl_Nte4.id"
            ]
          },
          "meta": {
            "name": "Customer DNE"
          }
        }
      ],
      "errorCases": [],
      "id": "Hgvl_Nte4",
      "action": "kustomer.customer.find-by-email",
      "params": {
        "email": "/#steps.1.attributes.data.customerEmail"
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [
        {
          "target": "bsT1Rvdz8",
          "condition": {
            "op": "true",
            "values": [
              true
            ]
          }
        }
      ],
      "errorCases": [],
      "id": "ZncXLm_TD"
    },
    {
      "transitions": [
        {
          "target": "Nvf94wHHl",
          "condition": {
            "op": "true",
            "values": [
              true
            ]
          }
        }
      ],
      "errorCases": [],
      "id": "bsT1Rvdz8",
      "action": "kustomer.conversation.create",
      "params": {
        "customer": "/#steps.Hgvl_Nte4.id",
        "name": "New Form Submission"
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [],
      "errorCases": [],
      "id": "4ulllrCjT",
      "action": "kustomer.conversation.update",
      "params": {
        "id": "/#steps.dR1mpnOzE.id",
        "status": "done",
        "ended": true,
        "endedReason": "user_ended",
        "lastDeflection": "/#steps.1.attributes.data.lastDeflection"
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [],
      "errorCases": [],
      "id": "RzUykx4XT",
      "action": "kustomer.conversation.update",
      "params": {
        "id": "/#steps.dR1mpnOzE.id",
        "lastDeflection": "/#steps.1.attributes.data.lastDeflection"
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [
        {
          "target": "OD1eZkCxj",
          "condition": {
            "op": "true",
            "values": [
              true
            ]
          }
        }
      ],
      "errorCases": [],
      "id": "_e8mq0ChF",
      "action": "kustomer.customer.create",
      "params": {
        "email": "/#steps.1.attributes.data.customerEmail"
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [
        {
          "target": "tmx9JRFIX",
          "condition": {
            "op": "true",
            "values": [
              true
            ]
          }
        }
      ],
      "errorCases": [],
      "id": "OD1eZkCxj",
      "action": "kustomer.conversation.create",
      "params": {
        "customer": "/#steps._e8mq0ChF.id",
        "name": "New Form Submission"
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [],
      "errorCases": [],
      "id": "tmx9JRFIX",
      "action": "kustomer.message.create",
      "params": {
        "customer": "/#steps._e8mq0ChF.id",
        "app": "Form",
        "size": 0,
        "channel": "email",
        "conversation": "/#steps.OD1eZkCxj.id",
        "body": "/#steps.1.attributes.data.messagePreview",
        "subject": "/#steps.1.attributes.data.messageSubject",
        "meta": {
          "meta": {
            "to": "YOUR_EMAIL_HERE",
            "from": "{{steps.1.attributes.data.customerEmail}}"
          }
        }
      },
      "appVersion": "kustomer-^1.9.2"
    },
    {
      "transitions": [],
      "errorCases": [],
      "id": "Nvf94wHHl",
      "action": "kustomer.message.create",
      "params": {
        "customer": "/#steps.Hgvl_Nte4.id",
        "app": "Form",
        "size": 0,
        "channel": "email",
        "conversation": "/#steps.bsT1Rvdz8.id",
        "body": "/#steps.1.attributes.data.messagePreview",
        "subject": "/#steps.1.attributes.data.messageSubject",
        "meta": {
          "meta": {
            "to": "YOUR_EMAIL_HERE",
            "from": "{{steps.1.attributes.data.customerEmail}}"
          }
        }
      },
      "appVersion": "kustomer-^1.9.2"
    }
  ],
  "trigger": {
    "transitions": [
      {
        "target": "Hgvl_Nte4",
        "condition": {
          "op": "neq",
          "values": [
            "/#steps.1.attributes.data.lastDeflection.status",
            "offered"
          ]
        },
        "meta": {
          "name": "Form Submission Created"
        }
      },
      {
        "target": "dR1mpnOzE",
        "condition": {
          "op": "eq",
          "values": [
            "true",
            "true"
          ]
        },
        "meta": {
          "name": "Update Deflection Status"
        }
      }
    ],
    "eventName": "kustomer.hooks.form.62e9385789f744eb6bb6772d.receive",
    "id": "1",
    "appVersion": "hooks-^1.0.0"
  }
}
  10. Select Step 1 of the workflow. Use the drop-down menu under Trigger Event to select the form hook that you created earlier.
  11. Select Step 7 of the workflow. Scroll down to the Meta field under Optional fields, and replace YOUR_EMAIL_HERE with the reply email of your choice. Make sure to include the quotation marks around the email address. Do the same for Step 9.
  12. When you're finished, Save the workflow and use the toggle to turn it on.

Now, the workflow will be able to ingest form data and create conversations on the customer’s timeline.

Convert to an advanced form

After the form hook and ingest workflow have been created, the next step will be to convert an existing form to an advanced form.

  1. Go to Settings > Knowledge Base > Forms, and edit the desired form.
  2. Scroll down to the bottom of the Form Settings section and under the Advanced section of the Form Settings, turn on Advanced Mode.
  3. Paste the form hook address in the field provided.
  4. Select Save Changes before exiting the settings.

After completing these steps, new form submissions will be ingested through the workflow.

Reference custom attributes

After creating the ingest workflow, you can now work with custom attributes to update data based on your organization's needs.

Here's an example of how you can use custom attributes in a form using a multi-level list custom attribute called Contact Reason.

  1. Create a multi-level list conversation attribute named Contact Reason.
  2. Navigate to your form and add the Contact Reason attribute to the form. Select Copy next to the workflow attribute name.
  3. Return to the ingest workflow and edit it. Beneath each Message Create step, select the plus icon + to create a new Action step with the following characteristics:
    • Action App: Kustomer
    • Action Event: Conversation: Update
    • Id: use the drop-down menu to select the Conversation Create step on the corresponding condition branch and then the Id option, like so:
    • Scroll down to the Contact Reason (tree) attribute, then select the <> icon and enter: /#steps.1.attributes.data.conversationContactReason.
  4. Save your workflow.

Your workflow will now save the Contact Reason selected on the form to a custom attribute on the created conversation.

Note: When referencing attributes, the format should be /#steps.1.attributes.data.workflowAttribute, where workflowAttribute should be replaced with what is shown in the form UI.