CSV Upload & Variables

Format CSV files and use dynamic variables in campaigns

CSV Upload & Variables

Use CSV files to upload contacts and include personalization variables for your outbound campaigns. The system automatically extracts variables from your agent's prompt and generates a matching template.

Upload contacts: Open the Campaigns page and click "New Campaign" to upload contacts during campaign creation.

How Variable Extraction Works

┌───────────────────────────────────────────────────────────────┐
│                    Variable Flow                               │
├───────────────────────────────────────────────────────────────┤
│                                                                │
│   Agent Prompt ──► Extract {{variables}} ──► Generate Template │
│                                                   │            │
│                                                   ▼            │
│   Download Template ◄────────────────────── CSV with Headers   │
│        │                                                       │
│        ▼                                                       │
│   Fill in Data ──► Upload CSV ──► Validate & Import            │
│                                        │                       │
│                                        ▼                       │
│   Campaign Call ◄───────────── Replace Variables               │
│                                                                │
└───────────────────────────────────────────────────────────────┘

When you select an agent during campaign creation, the system:

  1. Scans the agent's system prompt and greeting for {{variable_name}} patterns
  2. Generates a CSV template with those variables as columns
  3. Provides a Download Template button with pre-filled headers

CSV Format

Required Column

The only required column is phone number:

phone_number
+919876543210
+919876543211

Phone numbers must include country code (e.g., +91 for India).

With Agent Variables

If your agent prompt contains:

Hello {{customer_name}}, I'm calling about your order {{order_id}}.
Your appointment is scheduled for {{appointment_date}}.

Your CSV should include:

phone_number,customer_name,order_id,appointment_date
+919876543210,Rahul Kumar,ORD-001,2024-01-15
+919876543211,Priya Singh,ORD-002,2024-01-16

Download Template Feature

When creating a campaign:

  1. Select your agent - System extracts variables from prompt
  2. Click "Download Template" - Get CSV with correct headers
  3. Fill in your data - Add phone numbers and variable values
  4. Upload the completed file - System validates and imports

The template includes:

  • phone_number (required)
  • name (recommended for call history)
  • All variables detected in agent prompt

Contact List Integration

When uploading contacts during campaign creation:

Option Description
Select Existing Choose a previously uploaded contact list
Create New List Name and create a new list with uploaded contacts

Creating a new list:

  • Contacts are saved to the workspace
  • List can be reused in future campaigns
  • Contacts appear in call history with names

See Uploading Contacts for detailed format requirements and validation rules.

Variable Syntax

Use double curly braces: {{variable_name}}

Naming Rules

Rule Valid Invalid
Letters, numbers, underscores {{customer_name}} {{customer-name}}
Case-sensitive {{OrderID}} ≠ {{orderid}} -
No spaces {{order_id}} {{order id}}
Must match CSV header exactly {{phone}} → phone column -

In Greeting Message

Hello {{customer_name}}, this is Vani from ShopEasy.
I'm calling about your order {{order_id}}.

In System Prompt

You are calling {{customer_name}} about order {{order_id}}.

Context:
- Order was placed on: {{order_date}}
- Delivery status: {{delivery_status}}
- Product: {{product_name}}

Objective: Confirm delivery address and schedule delivery time.

Example CSV Files

Order Follow-up

phone_number,customer_name,order_id,product_name,order_date
+919876543210,Anita Verma,ORD-1001,Laptop Pro,2024-01-10
+919876543211,Sanjay Mehta,ORD-1002,Wireless Mouse,2024-01-11
+919876543212,Priya Sharma,ORD-1003,Mechanical Keyboard,2024-01-12

Appointment Reminder

phone_number,patient_name,doctor_name,appointment_time,clinic_name
+919876543210,Ravi Kumar,Dr. Sharma,10:00 AM,City Health Clinic
+919876543211,Meera Patel,Dr. Gupta,2:30 PM,Central Hospital
+919876543212,Amit Singh,Dr. Verma,4:00 PM,Care Plus Center

Lead Follow-up

phone_number,lead_name,interest,inquiry_date,agent_name
+919876543210,Vikram Singh,Home Loan,2024-01-10,Rahul
+919876543211,Pooja Reddy,Car Insurance,2024-01-08,Priya
+919876543212,Kiran Desai,Term Insurance,2024-01-12,Amit

Payment Reminder

phone_number,customer_name,invoice_number,amount_due,due_date
+919876543210,Rajesh Kumar,INV-2024-001,₹15000,2024-01-20
+919876543211,Sunita Patel,INV-2024-002,₹8500,2024-01-22
+919876543212,Mohammed Ali,INV-2024-003,₹23000,2024-01-25

CSV Validation

The system validates your file during upload:

Check Behavior
Phone number format Auto-formats Indian numbers (adds +91)
Required columns Ensures phone_number present
Variable matching Warns if agent variables missing from CSV
Duplicate numbers Counts and reports duplicates
File size Maximum 10 MB
Row count Maximum 10,000 contacts

Validation Results

After upload, you'll see:

  • Total rows - Rows in your file
  • Valid contacts - Successfully imported
  • Duplicates - Skipped (same number in file)
  • Invalid - Failed validation with reasons

Phone Number Formatting

Auto-Formatting (India)

Input Normalized Output
9876543210 +919876543210
09876543210 +919876543210
919876543210 +919876543210
+919876543210 +919876543210

International Numbers

Include country code for non-Indian numbers:

phone_number,customer_name
+14155551234,John Smith
+442071234567,James Wilson
+61412345678,Sarah Brown

Best Practices

  1. Download template first - Ensures correct column names
  2. Use UTF-8 encoding - Required for Indian names and special characters
  3. Clean data - Remove empty rows, fix formatting issues
  4. Include names - Makes call history more useful
  5. Test small batch - Upload 10-20 contacts first
  6. Match variables exactly - Case-sensitive matching
  7. Preview before import - Check sample rows

Troubleshooting

"Variable not found in CSV"

The agent prompt contains {{variable_name}} but your CSV doesn't have that column:

  • Download the template to see required columns
  • Add missing column to your CSV
  • Or remove the variable from agent prompt

"No phone column detected"

Rename your phone column to one of:

  • phone_number (recommended)
  • phone
  • mobile
  • mobile_number
  • contact
  • telephone

"Invalid phone number" errors

Check that numbers:

  • Have at least 10 digits
  • Don't contain letters or special characters (except +)
  • Include country code for non-Indian numbers

Upload stuck or slow

  • Check file size (max 10 MB)
  • Reduce rows (max 10,000)
  • Try CSV format instead of Excel
  • Check network connection

Next Steps

Ready to create a campaign? Open the Campaigns page and click "New Campaign" to get started.