Understand form data · Mavenoid help center

What form data is

Form data is data associated with a conversation. Each piece of data has two parts:

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

How form data gets set

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

From the URL

The special form data key $created-on-page-url is automatically populated with the URL of the page on which the assistant was embedded.

For example, if the user visits your page https://example.com/support/ where you have an embedded Mavenoid assistant and starts a conversation there, the value associated with $created-on-page-url will be set to https://example.com/support/. If they instead visit your page https://example.com/support/warranty/ and start a conversation there, the value will instead be set to https://example.com/support/warranty/.

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 parameters in its URL.

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"}})

Entered by the user

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

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.

A message step with a simple form

The special form field "Customer email" always uses the key $customer-email.

Write data node

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

A write data node setting the key "product-type" to the value "enterprise"

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.

A condition connected to form data

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.

An actions node with an action to create a Zendesk ticket and store its ID in form data

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.

An external API node calling an order status API and setting the key "order-status" to a value found in the JSON 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.

An external script node running a script called "determine-service-tier" and storing the output as the value for the key "service-tier"

How form data gets used

There are a few 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.

A node with markup in its title to display form data to the user

Read data node

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

A read data node checking for several values of the "region" form key

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.

A condition connected to form data

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.

An actions node with an action to send an email to an address based in form data

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.

An external API node calling an order status API using the key "order-number" to specify the URL

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.