Using variables in CX surveys

You can now personalize your customer experience (CX) surveys by including variables in your questions and prompts. This allows you to dynamically insert specific information—like an employee's name, a product name, or a case number—directly into the survey text. 

This feature is available for the NPS prompt, CSAT prompt, employee and product review prompts, and custom questions.

How to Format Variables in your Survey Text

To add a variable to a question, you'll use a specific syntax that includes the variable name and an optional default value.

The format is: {VARIABLE_NAME | default text}

• VARIABLE_NAME: A placeholder for the information you want to insert (e.g., EMPLOYEE_NAME).
• default text: The text that will be shown if a specific value for the variable isn't provided for a given survey.

For example, if you want to personalize a question with an employee's name, you would write: How was your experience with {EMPLOYEE_NAME | our employee} today?

Here's how it works in practice:

• If a value is provided (e.g., EMPLOYEE_NAME ="John Doe"), the customer will see: "How was your experience with John Doe today?"
• If no value is provided, the default text is used, and the customer will see: “How was your experience with our employee today?” 
• If no default text is specified (e.g., {EMPLOYEE_NAME}) and no value is provided, the customer will see the variable name itself: “How was your experience with EMPLOYEE_NAME today?”  

Pro Tip: Always include a default value to ensure your surveys look polished and professional, even when data is missing.

Important Syntax Note: Ensure there is no extra whitespace inside the curly braces.

• ✅ Correct: {EMPLOYEE_NAME | our employee}
   
• ❌ Incorrect: { EMPLOYEE_NAME | our employee }

How to Provide Substitution Values

There are three straightforward ways to provide values for your variables: through the user interface (UI), the public API, or a CSV upload. In all cases, the system can also pull substitution values from the survey's Notes field.

• Sending Surveys in the UI
  When sending surveys via the user interface, use the new substitutions text area. You can enter multiple variables, separated by a new line or a semicolon.
  • Format: 
    • {VARIABLE_NAME} ="Value"
  • Example:
    • {EMPLOYEE_NAME}="John Doe"
    • {TICKET_ID}="A52-891"
• Using the Public API
  For API integrations, you can provide substitutions in a new substitutions field. This field accepts a JSON object that maps the variable name to its corresponding value.
  • Format: “substitutions”: { “VARIABLE_NAME”: “Value”}
  • Example: "substitutions": {"EMPLOYEE_NAME": "John Doe", "TICKET_ID": "A52-891"}
• Uploading Surveys via CSV
  If you're using a CSV file, add a new optional column titled “Substitutions”. Within this single cell, you can list multiple variable assignments, separated by a semicolon.
  • Format: {VARIABLE_NAME}="Value"; {VARIABLE_2}="Value2"
     
  • Example (within a single cell in the "Substitutions" column): {EMPLOYEE_NAME}="Jane Smith"; {PRODUCT_NAME}="Deluxe Widget"