Understand form data

What form data is

Form data is a collection of extra variables that persist alongside a conversation. They can represent a variety of things such as a user's email address, the region they are located in, the serial number of the product they are troubleshooting, and so on.

Each piece of form data has two parts:

1. Key: The name of the data, such as email, region, serial-number, and so on.
2. Value: The content of the data, such as [email protected], US, EN-2721, and so on.

Both keys and values are case-sensitive.

Some special keys are reserved by Mavenoid and are usually populated automatically. These can be recognized by their leading $ characters, such as in $created-on-page-url and $language-iso. See Reserved form data for a list.

Form data can be set and used a variety of ways to improve Mavenoid conversations.

How form data gets set

There are several ways form data can be set for a given conversation.

Automatically

Several form data keys are set automatically by Mavenoid under certain conditions. These keys are reserved by Mavenoid and all have leading $ characters.

For example, the URL of the page the user has visited to access the product assistant is stored as $created-on-page-url, while the language code for the language in which they are using the assistant is stored as $language-iso. This allows the flow to tailor the experience for the user based on this information without the user ever needing to specify it explicitly or choose it from a menu.

See Reserved form data for a full list of automatically-set form data.

JavaScript

In the JavaScript snippet that adds the assistant to your website, you can specify form data to be prefilled for the conversation. You can do this by passing to the mavenoid.push call an object named initFormData which maps keys to values.

For example, your snippet should have a line like this:

mavenoid.push({ productId: 234567, orgName: "Your Company", position: "right"})

If you want to set the form data key name to value John Smith and the key serial_number to value ABCEDFGH, you would modify that line of the snippet as follows:

mavenoid.push({ productId: 234567, orgName: "Your Company", position: "right", initFormData: {"name": "John Smith", "serial_number": "ABCEDFGH"}})

This allows you to use the same flows in your assistant on multiple pages but direct users differently or prefill information based on which page they are currently visiting or any other information available to that page's JavaScript.

Entered by the user

Forms can be added to question or message nodes to prompt the user to manually enter information as appropriate.

Forms have several different types of fields with different behavior depending on the kind of information the user is providing, such as typing in an email address or uploading a screenshot. For details, see Form field types.

Form data entered by the user can be marked as PII. This will prevent the data from being stored in Mavenoid's servers or sent out in external tickets or transcripts; it will only be stored in the user client and used within the flow.

Write data node

Write data nodes can set any number of form data keys to specified values.

From a condition answer

When a condition that is connected to form data is answered, the condition's form data key is set to the selected answer's form data value.

Actions

Actions nodes can perform a variety of actions, some of which can set any number of form data keys to values based on the outcome of the action. For example, when using an action to file a ticket in a connected help desk, you can store the ID of the created ticket in form data for later use.

External API

External API nodes still work, but for new flows we recommend using the Actions node instead for greater configurability.

External API nodes can access an external API and then set any number of form data keys to values based on the API's response.

External script

External script nodes can run an external script and then store the output as the value for a given form data key.

Form data set by an external script node can be marked as PII. This will prevent the data from being stored in Mavenoid's servers or sent out in external tickets or transcripts; it will only be stored in the user client and used within the flow.

External script functionality is currently experimental. To work with external script nodes, please reach out to your Mavenoid representative.

How form data gets used

There are several ways form data can be read or used.

Markup

Markup can generate dynamic text based on form data. It can be used in node titles or descriptions and in any node settings field that indicates it accepts markup.

In forms

Forms can be added to question or message nodes to prompt the user to manually enter information as appropriate. If any of that form's fields uses a form data key that already has a value attached, the value will be pre-filled in the form. The user can leave it as-is or edit it.

This allows the flow to provide default or suggested values that users can accept or change and prevents users from having to provide the same information multiple times if they encounter multiple forms.

Read data node

A read data node can fork a flow's behavior based on the value of specified form keys.

To answer a condition

When a condition that is connected to form data is reached, if the condition's form data key has a value that matches the value for one of the condition's answers, that answer will automatically be selected.

Actions

Actions nodes can perform a variety of actions, many of which can use form data to configure the action. For example, you can send emails to an address stored in form data, or use form data to pass data to an external API.

External API

External API nodes still work, but for new flows we recommend using the Actions node instead for greater configurability.

External API nodes can use form data to dynamically generate URLs and payloads for API requests.

Conversation transcript

Form data is included in all transcripts of a conversation that are sent via email or used to create external tickets, such as in an Actions node.

To appear in the transcript, the form data must actually appear on a form at some point in the conversation. Data that is only set or read other ways and never actually displayed to the user is not included in the transcript.

Agent dashboard

Form data is included in conversation details viewed in the agent dashboard.