> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables
***
## 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:
| **Type** | **Description** | **Representation** |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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. | `blue` |
| **Collected In-call Variables** | Variables captured or updated dynamically during the conversation. These variables are collected based on user interactions, inputs, or system computations. | `green` |
| **Post-call Variables** | Variables 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:
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.
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**.
Click the **“+”** icon in a text field or use the **Variable Manager** button (in the header or tree editor).
* **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.
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| **Type** | Select the data type: `Text`, `Whole Number`, `Decimal`, `Boolean`, or `Date & Time`. |
| **Display Name** | Use a clear, descriptive label (e.g. `Customer Name`). |
| **ID** | Auto-generated from the Display Name — you can edit it. |
| **Description** *(optional)* | Explain the purpose or usage of this variable. |
| **Allow Multiple Entries** | Toggle this if the variable needs to hold multiple values (e.g. list of dates). |
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.).
It will now be available anywhere in your flow where variables are supported.
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.
Search, Edit or Delete a Variable
**To search a variable:**
* Open the **Variable Manager**.
* Click on the search bar.
**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.
**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.
**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.
**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.
* **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)
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.
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**.
| phoneNumber | customerName | membershipStatus |
| ----------- | ------------ | ---------------- |
| +1234567890 | Jane Smith | Gold |
***
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.
```http theme={null}
PUT /v1/Outbound/{outboundId}/Lead
Content-Type: application/json
Authorization: Bearer
{
"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.
```http theme={null}
POST /v1/Outbound/{outboundId}/Call
Content-Type: application/json
Authorization: Bearer
{
"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
**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 **{customerName}**, we're excited to inform you about an upgrade to your **{currentPlan}** 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.
**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.
**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)
Yes, variables function similarly in both modes and can be managed accordingly.
Implement checks using conditional logic or assign default values to handle empty variables gracefully.
Yes, variable names are case-sensitive. Ensure consistency when referencing them.
Yes, variables can be updated multiple times as the conversation progresses.
Include variables in the CSV file for platform uploads or in the `callData` field when using the API.
**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.
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](support@nlpearl.ai).
***
