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).
New administrators: complete the first-login wizard first — see Engagement Hub Onboarding Guide.
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).
Mapped Upload (shared defaults + column mapping)
If your spreadsheet only has contact columns (for example phone and name), use Mapped Upload on the Bulk Call page instead of rewriting the file:
- Click Mapped Upload and choose your CSV or Excel file.
- The Bulk Call page switches to a full Mapped Upload screen with Back and Upload and Queue.
- Fill shared defaults the same way as Single Call — instruction, call type, channel, language, user/broker phone, call duration, and email options when channel is email.
- For each Hub field, either keep Use form value or map it to a column in your file. Phone number must be mapped for non-email channels.
- If the file has more than 100 data rows, choose a segment size (100, 200, 300, 400, or 500) and a row segment. Upload one segment at a time; mapping and defaults stay for the next segment.
- Review the preview rows, then Upload and Queue (enabled only when required values are set).
After a successful upload, Mapped Upload remembers your last-run defaults, column mapping, and segment progress on the server for your account (not in the browser). When you open Mapped Upload again under the same account:
- Shared defaults (instruction, call type, channel, and related fields) are restored automatically.
- If you reopen the same file (same name, columns, and row count), column mapping and segment size are restored and the next segment is selected so you can continue where you left off.
- If you open a different file, defaults still restore; remapping columns for the new headers if needed.
- Switching accounts in the same browser does not mix Mapped Upload settings — each account has its own last-run.
Mapped cells override the form default for that row; empty mapped cells fall back to the form value. Team calendar routing still uses user_email (empty = any team member), same as a standard bulk file.
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. With Mapped Upload, set duration once in the shared defaults (or map a duration column). - Prefer Mapped Upload for partial files — When you already have a list of phones/names and the campaign message is the same for everyone, map those columns and enter instruction and other fields on screen.
After you upload
- Engagement Hub validates your file and accepts the upload immediately (large files no longer block the browser).
- Batch History shows Ingesting with a progress bar while rows are written to the outbound queue, then Processing while calls and messages start.
- When every row has finished (success or error), the batch moves to Completed — or Failed if every row failed. Partial errors still count as Completed with non-zero Failed.
- Track execution 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 during ingest, check the batch detail API or re-upload corrected rows. Row-level errors from validation still appear on the upload response when applicable.
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 | 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.
Changelog
| Date | Change |
|---|---|
| 2026-07-16 | Batch History marks a batch Completed (or Failed) when no rows remain queued or in progress, including batches with Incomplete / Blocked / Cancelled row outcomes — it no longer stays stuck on Processing. |
| 2026-07-16 | Mapped Upload last-run is stored per Hub account on the server (no longer browser localStorage), so multi-account browser sessions do not mix settings. |
| 2026-07-14 | Mapped Upload restores last-run defaults and column mapping on open; same file resumes at the next segment when segmentation was used. |
| 2026-07-13 | Mapped Upload segment size is selectable (100 / 200 / 300 / 400 / 500 rows). |
| 2026-07-13 | Mapped Upload supports row segments of 100 for files larger than 100 rows so campaigns can be queued in chunks. |
| 2026-07-13 | Mapped Upload is a full-page flow (Back / Upload and Queue); email-only fields show only for email channel; upload stays disabled until required values are set. |
| 2026-07-13 | Added Mapped Upload: shared Single Call–style defaults plus CSV/Excel column mapping so files only need contact columns (e.g. phone and name). |
| 2026-07-04 | Bulk Call admin UI shows Ingesting status and row progress while large uploads queue in the background. |
| 2026-07-03 | Linked to Engagement Hub onboarding guide for first-time Admin setup. |