Lumoa Feedback Forms

Lumoa feedback forms are a form that we create for you, and that you will send to your end users. Those responses will then flow directly to Lumoa.

The typical flow of the customer feedback collection is as follows:

Company sends email to target end-customers asking for customer feedback.
The end-customer clicks the link in the email.
The end-customer will be redirected to the Lumoa Feedback Form
The Feedback form reads the Feedback Form Identifier from the URL and fetches configuration from Lumoa's API.
The Feedback Form is customized using the returned configuration.
The Feedback Form is translated using the given language-parameter.
The Feedback Form preselects the given NPS Score (if desired).
Background variables (=Tags) are parsed.
The end-customer writes open-ended feedback and clicks the 'Send' button.
The given NPS score, open-ended feedback and background variables are sent to the Lumoa Feedback API.
(Optional, based on configuration) The data will be sent to the Company's own API.

Feedback Form Identifier

When redirecting the end-customers to the Lumoa Feedback Form, the URL must contain a valid form identifier. This form identifier is used for detecting which company is collecting the feedback, and customizing the Feedback Form appropriately. Each company can have multiple different form identifiers and configurations, therefore supporting multiple Feedback Forms. For example, a company might want to ask different questions based on different end-customer segments.

Here is an example of the FeedbackFrom URL:

https://feedback.lumoa.me/Example: https://feedback.lumoa.me/FQnWHICMDi1jgjIP8znBs6a5UqUaknvg

The Form identifiers are provided by Lumoa upon request.

Language Support

Lumoa Feedback Forms can be used for collecting end-customer feedback with multiple different languages. For example, the form can be displayed with English or Finnish translations, based on the customer's preferred language.

The supported languages are configured by Lumoa on a per-customer basis.

The language is defined in the URL as follows:

https://feedback.lumoa.me/?language=Example:https://feedback.lumoa.me/?language=fi

If the language parameter is missing or if the provided language is not available, the default language will be used instead.

Pre-selecting the NPS Score

The Lumoa Feedback Form supports preselecting the NPS Score when the user is redirected to the Feedback Form. For example, when the end-customer clicks a NPS Score of 8 from the email asking for customer feedback, the Feedback Form can preselect the NPS score 8.

The preselected NPS score is defined in the URL as follows

https://feedback.lumoa.me/?score=8

Width of the Form (Embeddable)

The Lumoa Feedback Form can be resized using the 'width' parameter. For example, the Lumoa Feedback Form can be embedded to chat windows and the default width (350px) might be too wide for this use case.

The width is defined in the URL as follows

https://feedback.lumoa.me/?width=Example: https://feedback.lumoa.me/?width=300

External Id

Each imported feedback can have a unique identifier that is used to identify the feedback in external systems. The external id can be used when Lumoa pushes the analytics results back to the customer's own systems or third party services.

Date of the feedback

Lumoa Feedback Form sets the date of the feedback automatically to the moment when the feedback is given.

Background variables: Tags

Tags are used for filtering the NPS Feedbacks in Lumoa's service. Each feedback can have multiple tags. For example, tag with name 'gender' and value 'female' or 'male' can be used in the service to filter answers and calculate impact based on the respondent's gender.

Tag names and values must be a String, and the maximum length is 64 characters.

The Lumoa Feedback Form supports two use-cases for the tags:

Reading tags from URL
Fetching tags from API

Reading tags from URL

Tags can be passed to the Lumoa Feedback Form in the URL when redirecting the end-customer to the Feedback Form. Consider the following example:

https://feedback.lumoa.me/?=Example:https://feedback.lumoa.me/?gender=female&city=Helsinki

The example above would add to tags to the given feedback:

gender=female
city=helsinki

There are 3 preserved variables that cannot be used as tags as those are used by the Lumoa Feedback Form itself:

score
language
width

Fetching tags from API

The Lumoa Feedback Form can also fetch the background variables (tags) from the customer's own API.

In order to use this feature:

the URL must contain the external id parameter
the target API must not require any authentication
the target API must read the externalId from the URL
the returned data format must match the one specified later in this document

Example of the returned datamodel/Example of returned values form the API

{  "consumed": false,   "tags":     {      "name": "gender",       "value": "female"    },     {      "name": "country",       "value": "finland"    }

The example above would add the following tags to the feedback

gender=female
country=finland

Consumed-parameter

The API response from the customer's API must contain the 'consumed'-parameter. The consumed-parameter is used for detecting if the user has already given feedback and if a 'thank you'-page should be displayed instead of the Feedback Form.

So if

consumed=false -> display Feedback Form
consumed=true -> display 'thank you'-page

The consumed-parameter is used together with 'Notifications to Company's own API' feature described later in this documentation.

Typical use case for the consumed-parameter:

The end-customer receives an email asking for customer feedback.
The end-customer clicks the link in the email and is forwarded to the Lumoa Feedback Form.
The feedback form fetches the background variables from the Company's own API.
The consumed-parameter is false, so the Feedback Form will be displayed to the end-customer.
The customer fills the form and submits the feedback.
The Feedback Form will send the data to Lumoa's API and to the Company's own API ('Notifications to Company's own API').
The Company API sets the feedback as consumed.
The end-customer clicks the link in the email again and will be redirected to the Lumoa Feedback Form.
The Feedback Form will fetch the background variables from the Company's API.
The consumed-parameter is now true, so a 'thank you'page is displayed instead of the Feedback Form.

Example of fetching background variables from API

The API for fetching the tags is located at: https://api.customer.fi/api/v1/{externalId}
The end-user is redirected to the Feedback Form with the following URL: https://feedback.lumoa.me/lumoademo/asdf1234
The Feedback Form will then fetch the tags from: https://api.customer.fi/api/v1/asdf1234

NOTE: As the API from where the Lumoa Feedback Form fetches the tags cannot be secured by authentication, the externalId parameter should be either encrypted or so complex that guessing it is impossible.

Good externalIds:

UUIDs
Encrypted unique identifier

DO NOT USE Auto-increment numbers as externalIds if you want to fetch the background variables form your own API as the Auto-increment numbers are easy to guess.

You must contact Lumoa and give the locations of the APIs (fetching background variables, notifying about given feedbacks) in order to use this feature.

Masking the tag names and values

If tag names and/or values are sensitive, the name and/or value can be masked. For example tag with name 'a' and value of '1' or '2' could be used as a masked version of the 'gender' tag.
Even though the tag name and/or value is masked, Lumoa's service can display 'user friendly' names of the tags in the User Interface of the service. For example, the tag 'a' can be displayed as 'gender' in the User Interface.

Example:

https://feedback.lumoa.me/?=Example:https://feedback.lumoa.me/?a=1&b=2

Notifications to the Company's own API

The Lumoa Feedback Form can be configured to send notifications of given feedbacks to external APIs. This feature allows companies to track the customers who have given feedback and, for example, to re-send the customer feedback survey email to the customers who haven't responded yet.

The notification is a HTTP POST request without any authentication. The data payload of the notification request is as follows:

{"score": "Mandatory: the NPS Score. Value must be between 0 and 10.",
"comment": "Optional: The freetext comment.",
"translatedComment": "Optional: Translated comment. If missing, '\''comment'\'' will be translated to english and the translated version will be set here.",
"date": "date feedback was created",
"externalId": "Optional: Identifier that can be used in external systems to identify the feedback.",
"tags:"     {"name": "gender", "value":"female"},    {"name": "age", "value":"20-30"}


Feedback Form Configuration

The Lumoa Feedback Form can be configured per form identifier basis.

Configurable components in the Feedback Form:

Default language
Available languages
All translations
Background color
Logo + size
Contact Request availability

The Feedback Form Configuration is done by Lumoa upon request.

If you still require assistance, please email help@lumoa.me
Was this article helpful?
Cancel
Thank you!