​
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.

​
Variable Manager Overview

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


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

TypeDescriptionRepresentation
Pre-call VariablesVariables 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.blue
Collected In-call VariablesVariables captured or updated dynamically during the conversation. These variables are collected based on user interactions, inputs, or system computations.green
Post-call VariablesVariables generated after the call ends, such as the call transcript, recording URL, and conversation summary. These variables are automatically produced and can be used for follow-up actions.orange

Note about Post-call Variables
Post-call variables are not accessible via the Variable Manager, as they cannot be created or modified by users. These variables are pre-defined by our team and become available only within End Call Notifications. They’re designed to let your agents send structured data (like summaries or recordings) to external systems after the call ends.

​
Accessing the Variable Manager

You can access the Variable Manager in two quick ways depending on your editor mode:

1

From the Header

You can access the Variable Manager directly from:

  • The top navigation bar, available in both Simple and Advanced Mode.
  • The bottom-right corner of the Tree Editor, exclusive to Advanced Mode — alongside zoom and instruction buttons.

2

From a Text Field

You can also access the Variable Manager from a text field — in both Simple and Advanced Mode — whenever the + icon is available.

Only fields that support variables will display the “+” icon.
For example, some duration or static option fields won’t offer variable insertion.

  • Go to the Flow Configuration page (Simple Mode), or open a Node (Advanced Mode).
  • Click the “+” icon inside the supported text input field.
  • At the bottom of the dropdown, click “Variable Manager”.

​
Creating and Managing Variables

Variables help you store and reuse dynamic information throughout your flows. Here’s how to create, edit, and manage them from the Variable Manager.

1

Open the Variable Manager

Click the “+” icon in a text field or use the Variable Manager button (in the header or tree editor).

2

Select the Variable Category

  • Pre-call (available before the call starts)
  • Collected In-call (captured during the conversation)

Post-call variables are predefined by our team and cannot be created manually. They are only available inside End Call Notifications.


3

Fill in the Variable Details

FieldDescription
TypeSelect the data type: Text, Whole Number, Decimal, Boolean, or Date & Time.
Display NameUse a clear, descriptive label (e.g. Customer Name).
IDAuto-generated from the Display Name — you can edit it.
Description (optional)Explain the purpose or usage of this variable.
Allow Multiple EntriesToggle this if the variable needs to hold multiple values (e.g. list of dates).

4

Define Allowed Values (Optional)

Use this section to limit inputs to specific options.

  • Add a list of accepted values.
  • Optionally assign backend codes to each value.
  • Toggle Allow Multiple Entries if more than one value can be selected.

This is ideal for dropdowns or structured inputs (e.g. Issue Type, Region, etc.).

5

Save the Variable

It will now be available anywhere in your flow where variables are supported.

6

Use your variables wherever applicable

Some fields — like the Opening Sentence — do not support the use of in-call variables.

When testing your flows via Test Calls, note that Pre-call variables are required, while In-call variables are optional.

Also, when uploading a lead file, only the variables you’ve actually used in your flows will appear in the platform’s lead mapping interface.

In other words:
If you’ve created variables in the Variable Manager but haven’t used them anywhere, they won’t show up when setting up an outbound campaign or importing leads.


Edit or Delete a Variable

To edit a variable:

  • Open the Variable Manager.
  • Click on the variable name to open its edit form.

To delete a variable:

  • Click the Trash icon next to the variable.
  • Confirm the deletion in the dialog box.

Deleting a variable will remove it from all flows where it’s used. Proceed with caution!

​
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.”


Using Variables in EndCall Notifications
  1. Add an EndCall Notification to your flow (Email, Slack, API).
  2. Write the Notification Message, using the “+” icon to insert dynamic variables
  3. Customize the content to provide a clear summary of each completed call.

Exemple Email Notification to Client

Subject: New call from customerName — Summary for companyName

Message Content: “Hello companyName, You have received a new call from customerName. Here are some details:

  • Call Duration: callDuration
  • Summary: callSummary”

​
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

Call variables can be filled dynamically from CSV files or APIs to personalize outbound calls.

Adding Variables via the Platform (Outbound Campaigns)
1

Download the Lead Template CSV

Go to the Outbound Campaigns section of the platform, then click Download Lead Template.

This CSV contains predefined columns where you can add your custom variables.


2

Fill in the CSV with your Lead Data

Open the downloaded CSV and complete it by filling in the lead information, including any custom variables in the appropriate columns.

Make sure each variable matches the column header to avoid upload issues.

Once completed, upload the CSV back into 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.

Lead Import Tip
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)

​
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.