Survey prompts syntax

To provide a more personalized survey experience and gather the most effective feedback, you can customize survey prompts with dynamic variables and conditional branching. Interaction variables allow you to dynamically populate data such as the agent name or any custom attribute. You can use conditional expressions to present prompts differently based on the context of the interaction. You can also add images and links directly into survey prompts. All of this can be done with the Mindful Feedback survey prompt syntax described in this guide.

Overview

This article covers the following topics:

  • Interaction Variables
  • Logical operators
  • Conditional expressions
  • Images, links, and special characters

Interaction Variables

Text and text-to-speech prompts in Mindful Feedback can change based on interaction variables. To insert the value of an interaction variable into a text prompt, use the format %variable%. For example, to insert the name of the agent associated with a survey, you could reference the agent_name attrbute as follows:

We would like to ask about your recent call with %agent_name%.

In this example, if the agent associated with the interaction is named Joe, the customer would see "We would like to ask about your recent call with Joe."

Default Interaction Variables

The interaction variables listed below are available by default.

Note:

Some of these variables are only available if the data has been synchronized from an integrated contact-center platform.

Interaction variableDescription
%phone_number%The phone number of the respondent
%email%The email address of the respondent
%agent_id%The agent id associated with the interaction
%agent_name%The name of the user associated with the agent id
%agent_location%The location of the user associated with the agent id, if available
%agent_department%The department of the user associated with the agent id, if available
%agent_manager_name%The manager name of the user associated with the agent id, if available
%agent_manager_email%The manager email of the user associated with the agent id, if available
%agent_hire_date%The hire date of the user associated with the agent id, if available
%agent_days_hired%The number of days since the user associated with the agent id was hired, if available
%agent_tenure%The tenure of the user associated with the agent id, if available
%agent_groups%Lists the names of any user groups of which the associated agent is a member
  • If the agent is a member of more than one user group, this variable contain all relevant groups separated by a comma and space (for example, Agent group 1, Agent group 2, Agent group 3).
%call_type%Usually the type of call associated with the interaction set in the interaction details window
%external_ref%Usually a unique external ID used for matching an interaction with a third-party system
%weblink%The web survey URL associated with the interaction
%weblink_short%The web survey short URL associated with the interaction
%unsubscribe_link_short%The short URL version of the unsubscribe_linkvariable generated for SMS and Web SMS surveys
  • If no unsubscribe_link_short is available, this will provide the value of unsubscribe_link.
%survey_name%The name assigned to the survey on the Surveys page
%survey_type%The method by which the survey is delivered (inbound, outbound, sms, websms, web, or email)
%last_response%The value of the last response given during this survey interaction
  • If the last response is pending transcription, this will return empty.
%last_recording_url%The URL of the last voice recording given during this survey interaction
%min_response%The lowest value of number responses given during this interaction
%max_response%The highest value of number responses given during this interaction
%avg_response%The average value of number responses given during this interaction
%avg_report_response%The average value of responses given during this interaction to questions with reporting enabled
%survey_phone_number%The phone number used to perform the survey
  • This is the number of the phone connection associated with the survey type of this interaction.
%response_[number]%The response given to the specified question
  • The [number] in the variable name should be substituted by the question number found in the header for a particular question. For example, %response_2% will return the response to the second question in the survey. If the question has not yet been answered, does not exist in the survey, or is pending transcription, this will return empty.
%details_link%The URL to access the full details of the survey interaction
  • This can be used to easily send interaction details in an email, but note that authentication to Mindful Feedback is required in order to access this link.
%details_link_uuid%An alternative URL to access the full details of the survey interaction
  • The UUID details link does not require authentication to view.
%id%The numeric ID of the interaction used for various API methods
%uuid%The unique ID of the interaction used for external access to interaction details
  • This is also used when performing web surveys
%survey_id%The numeric ID of the survey
%status%A description of the current status of the interaction
%respondent_language%The language code of the respondent
%scheduled_at%The date/time (in UTC) at which the survey was scheduled to start
%unsubscribe_link%When a respondent goes to this link it will add their email address and/or phone number to your Do Not Contact list. Customers can re-subscribe from the same link if needed.
  • This link is included by default in the footer of all email surveys, but can be useful to include manually in some cases. For example, you might include this link in an SMS survey where the respondent may be charged for replying to unsubscribe.
%agentDepartment%Department of the agent based on the associated organizational chart in Genesys Cloud
%agentLocation%First listed Location of the agent based on Genesys Cloud data
%agentManagerName%Name of the agent's manager based on the associated organizational chart in Genesys Cloud
%agentManagerEmail%Email of the agent's manager based on the associated organizational chart in Genesys Cloud
%agentHireDate%Date the agent was hired (yyyy-mm-dd)
%agentDaysHired%Number of days since the agent was hired
%agentTenure%An attribute that groups the agent into discrete groups based on the agentDaysHired variable
%rand%A random 10-digit number

Custom Interaction Variables

Custom interaction data can also be accessed the same way. For example, if you have set up a survey that assigns the customer's name to a custom interaction variable named customer_name, you could modify the earlier example to reference the custom attribute:

Hello %customer_name%. We would like to ask about your recent call with %agent_name%.

In this case, a customer named Susan would see "Hello Susan. We would like to ask about your recent call with Joe."

Variable Mutators

Mutators can be used to change the value of existing variables. For example, you could change the agent ID to uppercase using the %agent_id.toUpper% mutator.

Expand the content below for a list of all available mutators.

The following examples reference the %agent_id% variable, but you can apply these mutators to any variable you like.

MutatorDescription
%agent_id.toUpper%Changes the value to all upper case
%agent_id.toLower%Changes the value to all lower case
%agent_id.toTitle%Changes the first character of the value to uppercase
%agent_id.capitalise%Changes the first character of each word in a sentence to uppercase
%agent_id.encodeForJson%Escapes any characters that would be unsafe for JSON
  • This is useful when POSTing to a URL as a question/survey event.
%agent_id.encodeForHtml%Encodes the value for HTML
%agent_id.encodeForUrl%Encodes the value for URL
  • This is useful if your survey redirect URL includes query string parameters that include dynamic variables.
%agent_id.length%Shows the length of the value in characters
%agent_id.addSlashes%Escapes single quotes ('), double quotes (") and backslashes (\)
%agent_id.stripSlashes%Removes backslashes () in value
%agent_id.shuffle%Shuffles the value
%agent_id.reverse%Reverses the value
%agent_id.newLineCarrage%Adds HTML <br> tags for every new line character in a value

Mutators can also be combined

Mutator CombinationDescription
%customer_name.toLower.toTitle%First changes the value to all lower case, then makes the first letter uppercase
%loyalty_type.toUpper.encodeForJson%First changes the value to all upper case, then escapes any characters that would not be safe for JSON

Variable Mutators With Parameters

Some mutators accept parameters that can change the output value.

MutatorsDescription
%agent_id.trimEnd,5%Removes the specified [number] (e.g. 5) of characters from the end of the value
%agent_id.trimStart,3%Removes the specified [number] (e.g. 3) of characters from the start of the value
%agent_id.wordWrap,75%Wraps a value to a given [number] (e.g. 75) of characters
%agent_id.stripWhitespace,\t\n%Strips whitespace or other characters (e.g. "\t\n" would remove tabs and new line characters) from the beginning and end of a string
%agent_id.stripLeftWhitespace,\t\n%Strips whitespace or other characters from the beginning of a string
  • For example, "\t\n" would remove tabs and new line characters from the beginning.
%agent_id.stripRightWhitespace,\t\n%Strips whitespace or other characters from the end of a string
  • For example, "\t\n" would remove tabs and new line characters from the end.
%agent_id.repeat, 2%Repeats the value X number of times
%agent_id.replace, cat, dog[, 2, true]%Replaces the first value with the second value and optionally accepts number of times to make the replacement (2) and case sensitivity. (true/false)
%agent_id.wordCount, angry%Returns the number of times a given word (e.g angry) is found in the value
%rand.between, 1, 10%Returns a random number between 1 and 10
  • Note: The between mutator only applies to the %rand% variable.

Logical Operators

Survey syntax supports basic logical operators such equals (==) and greater than (>), in addition to more advanced operators such as contained in (=~). You can also use the pipe operator ( | ) to build complex if/then/else logic in conditional statements. The following section details the available operators.

The following comparison operators can be used:

OperatorDescription
==the "equals" operator and will be true only if both sides are equal
<>the "not equals" operator and will be true only if both sides are different
<the "less than" operator and will be true only if the left side is smaller than the right side
>the "greater than" operator and will be true only if the left side is larger than the right side
<=the "less than or equal to" operator and will be true if the left side is smaller than or equal to the right side
>=the "greater than or equal to" operator and will be true only if the left side is larger than or equal to the right side
~=the "contains" operator and will be true only if the text of the right side appears in full in the left side
=~the "contained in" operator and will be true only if the text of the left side appears in full in the right side

The Pipe Operator ( | ) - Set Default / Else / Else if / Or

The pipe operator can be used for several purposes in survey syntax:

  • to define a default value when a referenced interaction variable does not contain a value
  • for ELSE and ELSE IF statements in conditional expressions
  • to achieve the same purpose as an OR statement in conditional expressions

Defining a Default Value

When you are not sure if your custom variables will have a value for all interactions, you can use the pipe operator to define a default value for the variable. In the example below, the value valued customer would be provided if the custom respondent_name variable is empty:

Hello [%respondent_name%|valued customer].

In this example, the square braces ([ ]) contain an expression. The pipe operator returns the value on the left side of an expression if possible and the value on the right side if not. In this case, if the respondent_name variable is empty, the customer will see "Hello valued customer."

Pipes can also be chained together as in the following example:

We would like to ask you about your call with [%agent_name%|%agent_id%|our customer service representative].

In this example, the agent will be referred to by name if they have a Mindful Feedback account, otherwise they will be referred to by their agent ID only. If the agent ID is also not defined for an interaction, it will generically refer to them as "our customer service representative."

Conditional Expressions

If/Then Expressions

For a more customized survey experience, you may wish to prompt or ask different things based on the value of an interaction variable. You can do this via conditional expressions using the if/then operator (??).

Note:

In Mindful Feedback survey syntax, the "if" portion of a conditional statement does not begin the statement but instead comes after the full condition. See the examples below for the correct placement of the if/then operator.

The following example uses the if/then operator (??) and the equals comparison operator (==) to show different messages depending on the value of the %call_type% variable:

We would like to ask you about your recent [%call_type%==SERVICE?? customer service experience][%call_type%==SUPPORT?? technical support request].

The expression can be understood as "if call_type is SERVICE, display customer service experience. If call_type is SUPPORT, display technical support request."

Assuming that the value of call_type is SERVICE, the customer would see "We would like to ask you about your recent customer service experience."

If/Then/Else Expressions

You can use the if/then operator in conjunction with the pipe operator to create if/then/else expressions. When placed within an if/then expression, the pipe operator acts as an else:

[%custom_var%==value??A|B]

This expression will show A if the variable custom_var is set to "value" and B in all other situations.

If/Or Conditions

There is no or operator to build complex conditions. However, you can perform the same logical operation by using several if/then/else statements together, as in the following example:

[%Department%==Support??Department is Support|%Department%==Helpdesk??Department is Support]

This statement would evaluate to TRUE if either "Support" or "Helpdesk" are found in the Department variable, and would assign the same output if either value is found. This achieves the same purpose as using an or statement to combine both conditions into one.

AND Conditions

Custom Triggers can be used to evaluate multiple conditions at once. There is no native syntax for AND conditions, but you can achieve the same result as an AND condition by stringing multiple expressions together using If/Then operators.

Example

Consider the following example:

%call_type%==Customer Service??%survey_type%==websms??%Customervalue%==GOLD??%last_response%==1

When using this approach to replicate an AND condition, you can evaluate the expression by using the equality operator (=) and the value "true" as shown in the screenshot below:

example of a custom trigger

This example trigger would only be invoked when all parts of the condition are true:

  • %call_type% == Customer Service

  • %survey_type% == websms

  • %Customervalue% == GOLD

  • %last_response%==1

Images, Links, and Special Characters

The remainder of this article discusses additional dynamic elements you can add via survey syntax.

You can include images in email and web survey prompts using the syntax ![Image Alt Text](Image URL). For example:

![Mindful Feedback Logo](https://demo.surveydynamix.com/img/logos/sd_logo_large.png)

You can include clickable links in email and web survey prompts using the syntax [Link text](URL). For example:

[Mindful Feedback](https://demo.surveydynamix.com)
Note:

Since SMS does not support HTML links or embedded images, Mindful will not convert links or images it into HTML in SMS messages. Instead, customers will see the survey syntax itself in plain text.

Special Characters can be escaped by preceding them with a single backslash. For example, if you want to print the opening bracket character ( [ ) instead of using it as a prompt expression, you could escape the opening bracket with \[.