Bulk Call — How to Prepare Your CSV File
This guide explains how to build a spreadsheet for Engagement Hub → Bulk Call. Use it together with the sample file templates/bulk_calls_template.csv.
You can also download a sample template from the Bulk Call page in Engagement Hub (Download Sample CSV Template).
Quick start
- Open the sample template (
bulk_calls_template.csv) in Excel, Google Sheets, or any spreadsheet app. - Replace the example rows with your contacts. Keep the header row (first row) exactly as-is.
- Save as CSV (
.csv) or Excel (.xlsx/.xls), then upload in Engagement Hub → Bulk Call.
Each row = one outreach to one customer (one call, text, WhatsApp message, or email).
File requirements
| Requirement | Details |
|---|---|
| Formats | .csv, .xlsx, or .xls |
| Header row | Required — column names in the first row (see table below) |
| One contact per row | Do not combine multiple phone numbers or emails in one cell |
| Encoding | UTF-8 recommended for CSV |
What each row must include
Every row needs:
instruction— What the AI should say or do (required for all channels).- A way to reach the customer:
- Phone, SMS, or WhatsApp →
phone_number - Email →
email(whenchannelisemail)
- Phone, SMS, or WhatsApp →
All other columns are optional. Leave a cell empty if you do not need that field for that row.
Column reference
Customer (who you are contacting)
| Column | Required? | Description | Example |
|---|---|---|---|
phone_number | Yes for phone/sms/WhatsApp | Customer phone in international format | +14165551234 |
name | No | Customer name (used in greetings) | Jane Smith |
email | Yes when channel=email | Customer email address | jane@example.com |
Note:
email_addressworks the same as
Message and behavior
| Column | Required? | Description | Example |
|---|---|---|---|
instruction | Yes | What the AI should accomplish on this outreach | Confirm tomorrow's appointment at 2pm |
call_type | No | Type of interaction (default: informational) | appointment_booking |
channel | No | How to reach the customer (default: phone) | sms |
language | No | Language code (default: en) | en, fr, es |
call_type values
| Value | Typical use |
|---|---|
informational | Reminders, notices, one-way messages |
confirmational | Confirm an appointment or action |
appointment_booking | Offer and book a calendar slot |
conversational | Connect the customer with a team member by phone |
channel values
| Value | Meaning |
|---|---|
phone | Voice call (default) |
sms | Text message |
wmsg | WhatsApp message |
wvoice | WhatsApp voice call |
email | Outbound email |
Your team (routing and caller ID)
| Column | Required? | Description | Example |
|---|---|---|---|
user_email | No | Team member whose calendar to use for booking | advisor@yourcompany.com |
user_phone_number | No | Team phone shown as caller ID; bridge number for conversational calls | +14165559876 |
- Leave
user_emailempty to use any available team member's calendar. - Leave
user_phone_numberempty to use your organization's default phone (configured in Account Settings).
Note:
user_email_addressworks the same asuser_email.
Email-only options
Use these when channel is email:
| Column | Description | Example |
|---|---|---|
email_template_name | Name of a template set up in Account Settings | Welcome |
email_subject | Subject line (or value for {{SUBJECT}} in a template) | Your appointment reminder |
For email rows, leave phone_number empty and fill in email.
Scheduling and duration
| Column | Description | Example |
|---|---|---|
scheduled_time | When to send or call (leave empty for as soon as possible) | 2025-11-05T14:00:00 |
call_duration | Expected length in minutes (overrides the upload default) | 30 |
Common examples
Simple phone reminder (most common)
phone_number,name,instruction,channel
+14165551234,Jane Smith,Remind Jane about her appointment tomorrow at 2pm,phone
SMS to a list with the same instruction
phone_number,name,instruction,channel
+14165551234,Jane Smith,Your payment is due Friday. Reply if you need help.,sms
+14165555678,John Doe,Your payment is due Friday. Reply if you need help.,sms
Book with a specific team member's calendar
phone_number,name,instruction,call_type,channel,user_email
+14165551234,Jane Smith,Offer Jane the next available cleaning slot,appointment_booking,phone,dr.smith@clinic.com
Conversational call (connect customer to a team member)
phone_number,name,instruction,call_type,channel,user_phone_number
+14165551234,Jane Smith,Connect Jane with our billing team about her invoice,conversational,phone,+14165559999
Outbound email
name,email,instruction,channel,email_template_name,email_subject
Chris Lee,chris@example.com,Send appointment reminder,email,Welcome,Your upcoming visit
Tips for a clean file
- Use international phone format — Include country code with a leading
+, e.g.+1for US/Canada:+14165551234. - Do not change column names — Copy names exactly from the template header (lowercase, underscores).
- Avoid extra commas in instructions — If your instruction contains a comma, wrap the whole cell in double quotes in CSV:
"Call back about policy #123, urgent". - Test with a small file first — Upload 2–3 rows before running a large campaign.
- Set call duration on upload — The Bulk Call page has a default duration; use the
call_durationcolumn only when specific rows need a different length.
After you upload
- Engagement Hub validates your file and queues each row.
- Outreach runs automatically (about 5 contacts per minute).
- Track progress in Batch History on the Bulk Call page and in the Call Dashboard.
- Each successful outreach uses credits from your account.
If some rows fail, the upload result shows error messages by row number so you can fix and re-upload those contacts.
Troubleshooting
| Problem | What to check |
|---|---|
| "Missing required column: instruction" | First row must include an instruction column |
| "Missing phone_number or email" | File must have at least one of these columns; each non-email row needs a phone number |
| Row skipped — duplicate customer | Your account may block repeat outreach to the same number/email within a set number of days |
| Email row rejected | Set channel to email and provide a valid address in email |
| Wrong caller ID | Set user_phone_number on the row, or configure the org default in Account Settings |
Files in this package
| File | Purpose |
|---|---|
BULK_CALL_CSV_GUIDE.md | This guide |
templates/bulk_calls_template.csv | Sample file with all supported columns and example rows |
For questions about your account, templates, or default phone settings, contact your Aventora administrator.