CSV Upload & Variables

Format CSV files and use dynamic variables in campaigns

4 min read

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.

Was this page helpful?