How to set up Fill Form in Flow Builder

In this guide, you will learn how to use the Fill Form step in Flow Builder to automatically extract multiple pieces of structured text from incoming messages. The possibilities are endless! Customizable forms enable you to tailor them to your use case. We look forward to seeing what you end up building with this step!

We will discuss the following in this article:

Requirements to use Fill Form:

A MessageBird account
Telegram or any other channel from MessageBird's offering

What is Fill Form?

The Fill Form step tries to capture structured data from unstructured text, allowing your customers to provide free-form natural responses while your flow can still automatically extract the relevant information and automate on top of that. So what do we mean by capturing structured data from unstructured text? Let’s look at an example for an imaginary airline company:

Bot: “Where are you flying from?”

User: “I’m currently in Paris”

Bot: “Where do you want to go?”

User: “I want to fly to Amsterdam please”

After this short piece of interaction, we want to obtain a form with two fields, namely the origin and destination of the user. Internally, we should build a form that expresses the following:

Origin: “Paris”
Destination: “Amsterdam”

This means that we need to retrieve parts of the user input that are relevant to our use-case. Also, we need to be able to deal with alternative phrasings of these inputs. For example, rather than saying “I’m currently in Paris”, your customer could have said “I am now in Paris, so I’ll be flying from there!”. In both cases, we just want to focus on the actual origin: “Paris”.

We want to ensure we are extracting the names of cities in both cases. One common technique to extract such data from natural language is referred to as Named Entity Recognition (NER). We have already introduced an NER step to Flow Builder previously, but we realized that building a flow for achieving the interaction as the one described above can be tricky. This is where our new Fill Form step comes in. It does not just use NER to extract the relevant data, but it’ll make it easy to do so for an arbitrary number of fields while prompting your customer for every field in turn. Note that our NER engine not only extracts city names, but many other kinds of entities such as names, credit card numbers, phone numbers, email addresses etc. To see a complete overview, head over to the NER quickstart.

An automated conversational sign up form

Let’s think of a more complicated use case to illustrate the power of the new Fill Form step. Imagine we’re building a conversational sign-up form to onboard new users. We’ll want to extract the following:

Full name
Email address
Phone number
City
Postal code
House number

Overview of steps

So what are the steps we go through?

Set up a channel for Telegram or any other channel on our platform. If you have already done this, feel free to skip this step!
Create a Form dataset
Add custom entities to the form if needed
Create a flow with a Fill Form step

These are just the high-level descriptions. Let’s now dive into the steps one by one!

Step 1: Set up a channel

Follow these steps to get started with Telegram. Alternatively, you can look through our remaining quickstarts for other channels.

Step 2: Create a Form knowledge base

This next step is about setting up a Form knowledge base. This is a new kind of Knowledge Base that can be found under the Knowledge Bases overview, which is available in the menu on the left of the dashboard. So go ahead and click on “Knowledge Bases”. Then, we’ll create a new dataset by clicking “Create dataset” on the top right. We’ll select “Form” as the “Dataset type”. Our dataset name will be “Sign Up Form”, but of course the name is really up to you! MessageBird’s Named Entity Recognition employs machine learning models that are trained for 1 language specifically. Therefore, we’d like you to specify the language in which you want to automate your conversations so that our platform selects the right models behind the scenes. In this case, we set the “Language” to “English”.

Click on “Next: Set up parameters” to navigate to the next step. In the next window, we’re asked to enlist our fields. We’ll cover them one by one. For each field we need to give the following: Form input This is the name that you want to give to the first field of the form. Make sure the name is self-explanatory so that you quickly know what kind of data to expect in this kind of field.

Type This is the type of field you want to extract. It can be one of the entities that are predefined or you can create a custom one. If you’re not sure what type to pick, be sure to read about named entity recognition (NER) to know more about the possibilities. Prompt This is the phrase to ask the customer to provide the relevant data. Usually, it’ll look something like “Can you tell me X?” such as “Can you tell me your name?” or “Can you tell me your order ID?”, but you’re free to change this in any way that makes sense. Sign Up Form fields So let’s look at our first field from the list we defined earlier. The name we give to this field will simply be “full-name”, so we’ll put that under “Form input”. We want to extract the full name of a person. The entity type that best fits this is “person”. Finally, the “Prompt” will be “Could you give me your full name?”. After filling in these values, your window should look like the one in the image above. Our next field will be the email address. We’ll use the name “email-address”, the entity type “email” and the prompt “What is your email address?”.

We’ll do a similar thing for the phone number which is achieved through using “phone-number” as the name of the field, “phone-number” as the entity type and “What is your phone number?” as the prompt.

Step 3: Add custom entities to the form if needed

For the next field, we want to extract the postal code, according to the standard Dutch format. The Dutch postal code system uses 4 digits followed by 2 letters (first digit being non-zero). Since we know the exact specification, we can implement this kind of entity with regular expressions.

To learn more about regular expressions and test your regular expressions take a look here and select the “Python” flavor. The exact syntax used by our regular expressions can be found here. The regular expression in this case should look something like “[1-9]\d{3} ?[a-zA-Z]{2}”. Navigate to the bottom of the Entity Type dropdown and select “Create custom entity”. Then, you can specify the name of the custom entity, e.g. “nl-postal-code”, the type of custom entity “Regular expressions” and the patterns you want to search for. In this case we have exactly 1 pattern: “[1-9]\d{3} ?[a-zA-Z]{2}”. After filling in the above regular expression pattern the form should look like the image below:

Click “Create entity” to save the newly created custom entity and add it to your form dataset. We’ll finalise the form's knowledge base with the fields below:

Form Input

Type

Prompt

house-number

numeral

What’s your house number?

city

geopolitical

What is the name of your city?

If everything has worked out so far, your screen should look like the image below. When ready, move to the final stage of the flow creation by clicking on “Next Review & save”.

Click on “Save Dataset” to save this form dataset and to make it available for use in your flows!

Step 4: Create a flow with a Fill Form step

Now that we’ve made the fill form dataset, we can create a flow in Flow Builder to automate the sign-up for your leads. Click on “Flow Builder” in the menu on the left side of the dashboard to navigate to the overview of your flows. Click on “Create new Flow” and select “Create Custom Flow”. In the window that pops up select the Omnichannel trigger or a trigger that corresponds to the channel that you created in step 1. Click on “Next” to start building your flow. Once you see the flow, click on the trigger step at the top of the flow and select the channel you’ve just created from the options on the right.

Then click on the ‘+’ icon below the trigger step and search for “Fill Form”. Click on the step to insert it in the flow. Once the step is in the flow, you should see the step’s configuration on the right. There should be a dropdown for the “Knowledge Base” you want to select. Go ahead and select “Sign Up Form”. If it doesn’t appear here, make sure you have successfully completed step 1 to 3, all the way to saving the form dataset at the end. You can then specify how long you want to wait for incoming messages before giving up and how often you allow the user to specify a form value in case our platform fails to extract it from the given user response. Failures can happen because of spelling mistakes, ambiguity or simply due to a misunderstanding. In the case of a detection failure, our Fill Form step repeats the question to let the end user know we want them to rephrase their response. In our case, we want to wait for at most 10 minutes and repeat each prompt at most 3 times.

The final field in the step configuration allows you to specify the name of the variable that will contain the data that was extracted using your Fill Form step. This variable can be used in the remainder of your flow to e.g. send out HTTP API requests to your service or to ask for confirmation from your customer about the detected fields. For now, we’ll use the default name that’s given to this variable: “form”.

After we set up the step we can decide what to do in case of a successful sign-up. For example, we can follow up with a message that asks to confirm the data we just extracted. To do this, we’ll add a “Reply to channel message” step as displayed below. Note that we can access individual fields with {{form.full-name}}, {{form.email-address}} etc. In general, the format is {{<name of variable from Fill Form step>.<field in form knowledge base>}}

Alternatively, you can find a JSON representation of the form in the root variable, in this quickstart that would be the “form” variable. This can be useful when calling an HTTP endpoint with all of the detected fields in the payload. Let’s wait for the user’s response to this confirmation by adding a “Wait for a response” step. We’ll put the response in a variable named “confirmation”.

A user might reply with many different ways of saying ‘yes’ or ‘no’, for example: “Sure!”, “Yes, looks good!”, “Affirmative!” or “Nope!”, “Not OK”, “No that’s incorrect”. If you want to robustly deal with such cases, you can use our public “Yes / No” intent model. Setting it up is easy: add another step “Recognize Intent” and select the “Yes - No [Multlingual]” dataset. The “Content to recognize'' in this case is “confirmation” which should be visible in the dropdown. If the user is trying to express confirmation or rejection, the ML-powered intent recognition will pick it up whilst dealing with any reasonable variations to saying ‘yes’ or ‘no’. If the user replies with something that’s neither a “yes” or a “no” to the question, the “Fallback intent” is assigned to the “Output variable”. In the end, the intent recognition step will look as follows:

Depending on whether the user confirmed or rejected the detected fields we want to do different things: - Confirmed: perform an outbound HTTP call with the fields as a payload - Rejected: create an inbox ticket to allow a human agent to step in - Fallback: try to confirm again. For each of these cases we can branch off using the “Branch” step. If the “confirmed” variable (see last figure) equals “yes” we want to reply to express our gratitude and promise the customer to follow up via email. Let’s first look at the ‘happy path’. For this we add a branch that compares the “confirmed” variable with “yes”.

Within the branch we add a “Reply to channel message”:

Then we’ll add a step to send out an HTTP request to an API on your platform:

Make sure to enable the “Body” and put the “form” variable there. The “Content-Type header” should be set to “application/json”. If you can, we strongly recommend setting up an OAuth integration to ensure proper authentication. Next we’ll think about the case where the user rejects our interpretation of the form we just gave them. In that case we’ll connect them to an agent in Inbox and inform them accordingly.

After sending this message, we’ll create an Inbox ticket for them so that the remainder can be taken over by an agent. Finally, we want to make sure we ask again for confirmation if our entity recognition didn’t detect a ‘yes’ or ‘no’ response. This we’ll do with a brief message saying we didn’t yet understand their response after which we use a Jump To step to go back to the step where we awaited the confirmation.

When all of this is put in place, you should obtain something like:

The final scenario we need to take care of is an unsuccessful attempt at filling the form, which is on the right branch of a Fill Form step. In that case, we want to do a similar thing as done in the ‘no’ step after the confirmation detection: we’ll just inform about the handover and create an inbox ticket.

And that’s it! Congratulations on building your first Fill Form flow! It’s always a good idea to try out the flow through the simulator. Next to “Publish” and “Save draft” you should see a “Simulate” button on top:

When clicking on “Simulate” you should see a phone screen popping up on the right side of your screen. We’ll write our first message here to get the conversation started.

You should see the first prompt you entered as the first outgoing message. Now go ahead and give a realistic name.

So far, so good! You can now continue to fill all the questions in the form to eventually get to the confirmation message:

As a last step, we confirm the information:

If you’re confident enough with the flow and want to start using it on your first batch of users, you can now stop the Simulator to return to the edit view. There you can click “Publish” on the top of the flow edit screen. Your channel should now send incoming messages through this flow!