​
Introduction

Variables are essential placeholders that store and manipulate data during a conversation. They hold information such as:

  • User Inputs: Data collected from user responses (e.g., names, email addresses).
  • System Data: Information retrieved from external sources like CRM systems.
  • Computed Values: Results from expressions or calculations within the conversation flow.

​
Why Are Variables Important?

  • Personalize Interactions: Tailor conversations to individual users for a more engaging experience.
  • Control Conversation Flow: Make decisions and branch dialogues based on variable values.
  • Store and Reuse Information: Keep track of data throughout the conversation for consistency.
  • Integrate with External Systems: Enrich conversations with data from other platforms.
  • Enhance Actions: Use variables in actions like sending personalized emails or SMS messages.

​
Accessing the Variable Manager

Variables can be managed using the Variable Manager, which is accessible in both Simple Mode and Advanced Mode (Tree Editor).

​
Variable Manager Overview

The Variable Manager allows you to create, edit, and organize variables used in your conversation flows. Variables are categorized into two types:

  • Pre-call Variables: Variables configured before the call starts, such as customer information. These variables are typically sourced from external systems like CRM or imported via CSV or API. They provide context and initial data that can be used throughout the conversation.
  • Collected In-call Variables: Variables captured or updated dynamically during the conversation. These variables are collected based on user interactions, inputs, or system computations, allowing the conversation to adapt in real-time and respond to user needs effectively.

​
Accessing the Variable Manager

  1. In Simple Mode:

    • Navigate to the Flow Configuration page.
    • Click on the ”+” icon to open the Variable Manager.

  2. In Advanced Mode (Tree Editor):

    • Within the nodes on the Tree Editor page, click the ”+” icon inside a node to open the Variable Manager.
    • Alternatively, you can press the document icon on the bottom right side of the editor to open the Variable Manager.

​
Variable Categories

  • Pre-call Variables: Represented with a person icon.

  • Collected In-call Variables: Represented with a phone icon.

​
Creating and Managing Variables

​
Creating a New Variable

  1. Open the Variable Manager by clicking the ”+” icon.

  2. Select the Variable Category:

    • Choose between Pre-call or Collected In-call from the dropdown menu.

  3. Click “Create Variable” to open the variable creation form.

    This will open the Create Variable panel where you can enter the details for your new variable.

  4. Enter Variable Details:

    • Type: Select the data type (Text, Whole Number, Decimal Number, Boolean, Date & Time).

    • Display Name: Use clear, descriptive names (e.g., Customer Name).

    • ID: Automatically generated based on the display name; can be edited.

    • Description (Optional): Briefly explain the variable’s purpose.

    • Allow Multiple Entries: Enable this option if the variable needs to store multiple values (e.g., a list of dates).

  5. Define Allowed Values (Optional):

    • Click on the “Allowed Values” section.

    • Allowed Values: Specify predefined options that the variable can hold.

    • Use Codes: Assign optional codes to each allowed value for backend processing or integration.

  6. Click “Save” to create the variable.

​
Editing and Deleting Variables

  • Edit a Variable: Click on the variable name in the Variable Manager panel to open the edit section.

  • Delete a Variable: Click the Delete icon next to the variable and confirm the deletion.

​
Using Variables in Conversations

​
Collecting User Input into Variables

  • In Simple Mode: Simply add a variable to the question step; this will automatically store the user’s response into that variable.
  • In Advanced Mode: In the node’s configuration, locate the “Store In Variable” field.

​
Inserting Variables into Agent Scripts

  1. Compose the Agent’s Script in any text field within your flow.
  2. Insert Variable Placeholder:
    • Click the ”+” icon next to the text field.
    • Select the desired variable from the list.

Example:

  • Script: “Thank you for calling, customerName!”

​
Using Variables in Actions

  1. Add an Action Node (e.g., Email Node, SMS Node) to your flow.
  2. Configure the Action:
    • Message Content: Include variables by clicking the ”+” icon and selecting the desired variable.
  3. Customize the Message with variable placeholders.

Example in SMS Node:

  • Message Content: “Hello customerName, your appointment on appointmentDate is confirmed.”

​
Implementing Conditional Logic with Variables

​
Conditional Branching

  1. Enable Conditional Transitions in a node’s configuration by toggling the “Conditional Branching” option.

  2. Add Conditions using variables and operators (e.g., satisfactionScore >= 4).

  3. Label Each Condition for clarity.

  4. Connect to Subsequent Nodes based on each condition.

Example:

  • Variable: satisfactionScore
  • Conditions:
    • If satisfactionScore >= 4, proceed to positive feedback node.
    • If satisfactionScore < 4, proceed to improvement inquiry node.

​
Populating Variables from External Data

​
Adding Variables via the Platform (Outbound Campaigns)

  1. Navigate to Outbound Campaigns in the platform.

  2. Download the Lead Template CSV, which includes columns for your variables.

  3. Fill in Lead Data in the CSV file, ensuring each variable corresponds to the correct column.

  4. Upload the Completed CSV back to the platform.

Example CSV Entry:

phoneNumbercustomerNamemembershipStatus
+1234567890Jane SmithGold

​
Adding Variables via API

  1. Use the Add Lead API Endpoint: PUT /v1/Outbound/{outboundId}/Lead.
  2. Include Variables in the callData field of your JSON payload.

Example Request:

PUT /v1/Outbound/{outboundId}/Lead
Content-Type: application/json
Authorization: Bearer <token>

{
  "phoneNumber": "+1234567890",
  "externalId": "lead123",
  "callData": {
    "customerName": "Jane Smith",
    "membershipStatus": "Gold"
  }
}

​
Sending Variables in Single On-Demand Calls

  1. Use the Make Call API Endpoint: POST /v1/Outbound/{outboundId}/Call.
  2. Include Variables in the callData field of your JSON payload.

Example Request:

POST /v1/Outbound/{outboundId}/Call
Content-Type: application/json
Authorization: Bearer <token>

{
  "to": "+1234567890",
  "callData": {
    "firstName": "John",
    "accountBalance": "$100"
  }
}

​
Best Practices for Using Variables

  • Use Descriptive Names: Clearly name variables for easy identification (e.g., customerEmail).
  • Define Variables Early: Plan your variables before building the conversation flow.
  • Categorize Variables: Use Pre-call and Collected In-call categories to organize your variables.
  • Avoid Unnecessary Variables: Only create variables that are essential to your conversation.
  • Test Thoroughly: Simulate conversations to ensure variables function as intended.
  • Handle Data Securely: Be cautious with personal and sensitive information.
  • Document Variables: Use the description field to note the purpose of each variable.
  • Use Allowed Values and Codes: When appropriate, define allowed values and use codes for better data management.

​
Examples

​
Example 1: Personalizing an Outbound Call

Scenario: Notifying customers about a service upgrade.

  1. Variables:
    • Pre-call Variables:
      • customerName (Text)
      • currentPlan (Text)
    • Collected In-call Variables:
      • interested (Boolean)
  2. Script: “Hello , we’re excited to inform you about an upgrade to your plan.”
  3. Collect Interest:
    • Question: “Would you like to hear more about this upgrade?”
    • Store response in interested (Boolean).
  4. Implement Conditional Logic:
    • If interested is true, proceed with details.
    • If false, thank the customer and end the call.
  5. Adding Leads via CSV: Use the platform to import leads with the customerName and currentPlan variables populated.

​
Example 2: Scheduling Multiple Dates

Scenario: Collecting multiple available dates from a customer.

  1. Variable:
    • availableDates (Date & Time)
    • Allow Multiple Entries: Enabled.
  2. Script: “Please provide the dates you are available for the meeting.”
  3. Collect Dates:
    • The system allows the customer to provide multiple dates, which are stored in the availableDates variable.
  4. Usage:
    • The collected dates can be used to schedule meetings or appointments.

​
Example 3: Dynamic Survey with Conditional Logic

Scenario: Gathering customer feedback.

  1. Ask Satisfaction Score:
    • Question: “On a scale of 1 to 5, how satisfied are you with our service?”
    • Store in satisfactionScore (Whole Number).
  2. Conditional Paths:
    • If satisfactionScore >= 4, proceed to a node thanking the customer.
    • If satisfactionScore < 4, proceed to a node asking for improvement suggestions.
  3. Follow-Up Actions: Send a personalized email using collected data, thanking them or addressing concerns.

​
Frequently Asked Questions (FAQ)

Q: Can I use variables in both Simple and Advanced modes?

A: Yes, variables function similarly in both modes and can be managed accordingly.

Q: How do I handle empty variables?

A: Implement checks using conditional logic or assign default values to handle empty variables gracefully.

Q: Are variable names case-sensitive?

A: Yes, variable names are case-sensitive. Ensure consistency when referencing them.

Q: Can I change a variable’s value during the conversation?

A: Yes, variables can be updated multiple times as the conversation progresses.

Q: How do I include variables when adding leads via the platform or API?

A: Include variables in the CSV file for platform uploads or in the callData field when using the API.

Q: What is the difference between Pre-call and Collected In-call variables?

A: Pre-call Variables are configured before the conversation starts and typically include data imported from external sources or predefined settings. Collected In-call Variables are captured or updated during the conversation based on user interactions.

Q: What happens if I delete a variable that’s in use?

A: Deleting a variable that’s in use can cause errors in your conversation flow. Remove all references before deleting.

​
Conclusion

Variables are powerful tools that enhance your conversations by making them dynamic and personalized. By effectively using variables, you can:

  • Collect and Store User Inputs: Gather essential information from users.
  • Personalize Interactions: Create tailored experiences for each user.
  • Control Conversation Flow: Direct the conversation based on user responses and data.
  • Integrate External Data: Incorporate information from other systems for enriched interactions.

Remember to:

  • Plan Carefully: Define your variables before building your conversation.
  • Organize Variables: Use categories like Pre-call and Collected In-call for better management.
  • Enhance User Experience: Use variables to make interactions meaningful.
  • Test Thoroughly: Regularly test your conversation to ensure variables work correctly.
  • Follow Best Practices: Keep your variables organized and your data secure.

For additional support, contact our support team at support@nlpearl.ai.