Use form hooks to ingest a web form
Last Update: Oct 2024 • Est. Read Time: 4 MINIf you have a Contact Us web form on your website, you can pass those submissions along to Kustomer where your team can answer them like any other conversation. To do this, you'll use a form hook to create new conversations from those submissions.
In this article, we'll walk through setting up a workflow with a form hook to ingest web form submissions.
Who can access this feature? | |
User types | Admins can access the Workflows page. |
In this article
- What is a form hook?
- Create a workflow to ingest web form submissions
- Create a form hook to use in your workflow
- Configure your form to post to the form hook
- Build out the workflow to create a conversation in Kustomer
What is a form hook?
A form hook is one of 3 types of hooks available in Kustomer as a workflow trigger. A form hook is a unique URL that lets 3rd-party applications send real-time information into Kustomer. For Kustomer to capture this information, the external system must post to the form hook URL. Posting to a Kustomer form hook does not require an API.
Learn more about Kustomer's different hook options in Inbound webhooks.
Create a workflow to ingest web form submissions
The first step in this process will be to create the workflow.
To create a workflow:
- Go to Settings and select Platform > Workflows.
- Select Add Workflow.
- Select Custom Workflow.
- Fill in the name and description of the workflow. We always recommend as a best practice that you use clear and illustrative names and descriptions, so that it's easy to know what function this workflow performs if another member of your team reviews this rule at a later date. For this example, you might pick a name like Contact Form.
- Leave the callable workflow option turned off.
- Select Create.
The workflow editor automatically opens after creating a new workflow.
Create a form hook to use in your workflow
Next, we'll start filling in the new workflow. The workflow will run whenever its defined trigger event is activated. In this example, we'll be using a form hook as the trigger event.
To create a new form hook in the workflow editor:
- Select the first step in the workflow.
- From the panel, under Trigger App select Hooks.
- Under Trigger Event select Add New Hook.
- Fill in the new hook's name and description, and select form hook as the type. Then, Save the hook.
- After the hook is created, use the Trigger Event menu to select the new hook.
- Use the toolbar at the top of the workflow editor to Save your work so far.
Configure your form to post to the form hook
Now that you have your form hook set up, you'll need to send data to this form hook URL. With your first workflow step still selected, you'll see a section called Hook Information in the panel where you can copy the address. Use a new browser tab to configure your web form to send an HTTP POST request to the form hook URL whenever a new form is submitted.
Build out the workflow to create a conversation in Kustomer
Once the web form is sending data to the Kustomer form hook, it's time to build out the rest of your workflow to manage how the submission is represented in Kustomer. This can be customized however best suits your team's needs, but might look something like this:
In the above example, the workflow runs whenever the web hook form is triggered, meaning it's received a new submission. After receiving data from the form hook, the workflow checks if the customer exists in Kustomer by looking up the customer by email address. To do this, it uses the email included in the form hook submission.
The data sent to the web hook can be accessed by the workflow with the syntax:
/#steps.1.attributes.data
We can drill down to the customer email we sent over to the form hook with the following syntax:
/#steps.1.attributes.data.email
The action step Customer: Lookup (By Email) will then either return a customer in your Kustomer org or not find that customer by their email.
Note: Sometimes you may have a customer in Kustomer without an email. To handle these cases, workflows can also have action steps, Customer: Lookup (By Phone) and Customer: Lookup (By External ID). We then use condition steps, Customer exists and Customer doesn't exist to handle each case.
If the customer exists, the workflow uses action step Conversation: Create to create a conversation in the customer's timeline with the web form information sent over to the form hook.
If the customer doesn't exist in your Kustomer organization already, the workflow uses action step Customer: Create to create the customer record first. Then, it uses Conversation: Create to create the conversation in the newly-created customer's timeline.
Once the conversation is created, the workflow uses the action step Message: Create to create a message in the newly-created conversation. In this action step, the web form content can be added. Fill out the Message: Create step with the following information:
- Customer (string): the ID of the customer.
- App (string): identifies where the message came from, using the web form created earlier as the app for this message.
- Size (number): identifies the size of the message.
- Channel (string): use the Channel Values options to select the new conversation's channel, which would be
email
in most cases. - Conversation (string): the ID of the conversation.
That's all you need to import a web form into Kustomer. Kustomer can handle your important data in a variety of ways, and workflows can be customized to create and update customers, orders, or anything else you'd like to see in Kustomer. Learn more about creating and customizing workflows in Workflows overview.