Message Variables

Overview

Message Variables can be used to configure dynamic text with the rich content sent in Quiq outgoing messages. Message Variables can be used in Send a message actions in both Conversation Rules and in the Bot Designer, and in Catalog Messages used as Snippets or in Conversation Rules or Bot Send a catalog message actions.

A message variable will reference some Quiq data field. When configured in an outgoing message, the data stored in the field will be returned and merged with the message text. This allows you to personalize messages sent to your customers.

Data used in Message Variables

Almost any Field in Quiq that stores data can be used in a message variable to personalize text in outgoing messages. This includes:

• Standard Quiq conversation fields like Queue, Contact Point and Apple or Google Intent
• Standard Quiq customer fields like Last Name, First Name and Email Address
• Quiq conversation custom fields
• Quiq customer custom fields
• Bot Session Fields (Bot Designer Only)
• Customer’s Survey Question Response (Bot Designer Only - applicable to Survey Bots)
• Certain computed fields like Agents Available
• NLU Intents and Parameters (Bot Designer Only - applicable to NLU Bots)

🚧

Note

The data returned from the field for selectable items like Queue or Contact Point will return the ID of the object, not the Label.

Where Message Variables Can be Used

Message variables can be used in outgoing text in Send a message actions in in both Conversation Rules and in the Bot Designer, and in Catalog Messages used as Snippets or in Conversation Rules or Bot Send a catalog message actions.

Message Text

Card Title, Subtitle, Secondary Title, and Tertiary Title

Card Link URL

Quiq Reply Text

Adding a New Message Variable

A new message variable can be added to one of the possible rich messaging locations by referencing the field name enclosed in double curly brackets.

As soon as the text is typed (e.g. {{conversation.customerfirstName}} or {{orderNum}}), it will appear in a colored chip. That blue or yellow chip indicates a message variable is used in the message.

Don’t know the field name? No problem. The message variable can be aliased to any string of alpha-numeric characters (with hyphens, underscores and periods) - as long as you associate a field after it’s created. Using the Quiq schema name is a short-cut for associating the variable to a field.

Once you have used a message variable in some text, it’s important to ensure that it is configured correctly:

• Blue chips indicate that they have a valid Field association.

• Yellow chips indicate they do not have a valid Field association.

🚧

Note

If you fail to set a Field, a message could be sent containing the literal variable name string, ie : "Your order number is {{orderNum}}."

Whenever you have used a message variable in response text, when you open the Rich Content Editor (by clicking the + button next to the message), a floating variable usage button of { } appears in the upper right corner.

• A yellow { } button indicates that there is a validation warning and your variable may not be fully configured. Click the button to open the Message Variables dialog to finish configuring the variables.

• A white { } button means that all variables are associated with Fields and either have Fallbacks or Alternative Messages properly configured.

• A blue { } button means that at least one Dynamic Text message has been configured.

Configuring the Variables and Dynamic Text

When clicking the floating { } button in the upper right, the Dynamic Text modal is opened. This is where you need to ensure that each variable is associated to a valid Quiq Field so the correct replacement text from the field is sent in the outgoing message.

The screen is divided into two panels:

• The left side controls how different alternative messages will dynamically be used based on the variables referenced that resolve at run-time, and any round-robining options configured.

• The right side is used to set the Fields, Fallbacks and Formats of any referenced variables.

Configuring the Message Variables

When first configuring new Dynamic Text, there will be only one grouping that includes all variables present in the default text. The variables in the grouping header appear in colored chips:

• Blue chips indicate that they have a valid Field association.

• Yellow chips indicate they do not have a valid Field association.

If there are any yellow chips shown, warning text is displayed so you know that the variable is not completely configured.

The configured text that references the variables is shown in the box within the grouping. This represents the message text that would be sent when the conditions are true (all variables have values).

The variable references within the text are displayed in blue chips no matter if they are fully configured or not. These chips cannot be selected to configure the variable - only the chips in the grouping header can be clicked to edit the variable.

Clicking on one of the variable chips in the grouping header will open the configuration panel on the right so the Field, Fallback and Formats can be set.

The selected variable is shown in the left side grouping header with a darker background - and the name of the variable appears under the Variable heading on the right.

Here the variable named conversation.customer.firstName was automatically recognized as a Quiq field name so that field was automatically associated with the variable. However, orderNum was not a recognized field name in Quiq. You must pick a value Field from the drop-down selector to choose which Quiq field should be used to merge data into the message text.

Additionally a Fallback can be configured. The fallback value is what will be sent if the current conversation doesn’t have a value for the associated field - in other words, what text to send in place of the variable if the field is not set.

Once a field is selected, a Format can also be specified. The Default Format will be set automatically. Additional Format options are:

• Base64 encode which will return the base64 encoded string of the data in the Field. This can be helpful to encode the text in the field when building a custom URL with some parameters.

• URL encode which will return the URL encoded string of the data in the Field. This can also be helpful to encode the text in the field when building a URL with some parameters to ensure that special characters are encoded so the link works as expected when clicked.

• Public Display Name which is available if the selected Field represents a Quiq User. This will return the configured display name for the User rather than the User’s ID.

• Date and time which is available if the selected Field represents a date/time. The default format will return the unix timestamp. When 'Date and time' is selected, additional parameters are available to select how the date/time value should be formatted when it's returned. If nothing is selected, the format will be M/DD/YYYY - like 4/12/2023. Many date and time options are available for selection (e.g. 4-12-23, 12-Apr-2023, 5:21 PM, 2023-04-12T17:21:11Z)

If you had attempted to use the field name for your message variable name, but had a typo, or didn’t have the name quite right, you may get a validation message in the Variables dialog that says This is not a valid field. You are not allowed to select a field nor can you change the variable name that shows in the yellow chip. To remedy this, just delete the yellow chip and add a new variable with the name of the field corrected.

🚧

NOTE:

After making changes to Fields, Fallbacks and Formats in the Dynamic Text modal, always make sure you Save here and then also hit the Save button in the Rich content editor in order to save your changes.

When the same variable is used in various locations in an outgoing message - like in the message text and in a Card title - the same Field, Fallback and Format will apply to all locations. If you change the Field referenced in the variable used in the Card title, it will also change the field Field referenced in the same variable in the message text.

Configuring Dynamic Text

Defining Fallbacks

Rather than setting up Fallback values for a message variable, you may instead want to configure one or more alternative texts to be sent. Rather than just allowing a fallback value to be used when a message variable field is set, you can adjust the entire message text.

In this example, when there is both a customer first name and last name, the first text will be sent. Otherwise, if there is a customer first name (but no last name) available, the second text will be sent. Otherwise, the last text will be sent.

Use the +Add Text button at the bottom to add an additional Text alternative.

• If the new Text has the same set of variables used as an existing message(s), then it will be added to the existing IF grouping that has the same set of variables. The new text will appear at the end of the list in that grouping.

• If the new Text uses a new set of variables, then a new grouping will be created. Any new groupings will be added at the end of the list of those previously configured.

🚧

NOTE

In most cases, it is best practice to have a catch-all message at the end of the list that contains no message variables.

If you do not have a catch-all message configured (a Text with no variables) and at least one of the defined variables does not have a Fallback value set, a validation warning is displayed.

It is wise to heed the warning, though it is not required since if all Fields referenced in the variables will always have a value, Fallbacks and catch-all Alternative Messages would be redundant.

There are up and down arrows available in each grouping such that the order can be changed such that the dynamic messaging is processed in the order you desire.

The X on the right side of any configured Text box can be used to remove that Text. When the last Text in any Dynamic Text grouping is removed, the grouping disappears.

If message variables are added or removed in any existing Text box, the Text will be automatically moved to the correct Dynamic Text grouping based on the variables that are still present in the Text.

Unreachable Options

Sometimes when a new Text is added and a new logical grouping is created at the end of the list, it will be shown in lighter gray text. This indicates that the currently configured logic makes it such that the new grouping - and thus new Text - will never be reached:

📘

Save your work

After making changes in the Dynamic Text modal, always make sure you Save here and then also hit the Save button in the Rich content editor in order to save your changes.

Round-Robining Similar Messages

When there are multiple message Texts in the same logical Dynamic Text grouping, those different Texts will be selected randomly and sent to the customer.

In this example, one of the three configured “catch-all” messages configured in the Otherwise grouping will be randomly selected and sent any time the customer first name is not set.

Legacy Variables

A few special variables exist to replace text with data from Quiq Fields, or with data determined by Quiq. These names used within double curly braces are reserved and will be treated differently. They will continue to function in Conversation Rules message text where they previously have functioned. They will still show in the blue chips, but no Field, Fallback nor Format will be needed.

If configuring a new message variable in Quiq Bots or in place other than the Message text in Conversation Rules - like a Card Title - do not use one of these reserved names:

• companyName
• contactPoint
• conversationId
• newNumber
• estimatedWaitTime
• queuePosition
• customersAheadOfYou
• caseId (Salesforce integrated sites only)
• caseNo (Salesforce integrated sites only)
• incident (Oracle Service Cloud Integrated sites only)
• refNo (Oracle Service Cloud Integrated sites only)
• ticket (Zendesk Integrated sites only)