Bulk Import
Step-by-step guide to uploading contact spreadsheets, validating international phone numbers, and mapping custom attributes.
WhatsBox includes an importer (/contacts/import) capable of ingesting spreadsheets with thousands of contacts in seconds.
File Format & Requirements
WhatsBox accepts the following file types:
- Comma-Separated Values (
.csv) - Microsoft Excel Workbook (
.xlsx) - Legacy Excel Spreadsheet (
.xls)
International Phone Number Format
Every phone number must include the country dialing code. Do not include leading zeroes or local prefixes:- Correct:
16317471111,+1 (631) 747-1111,+44 7911 123456,919876543210 - Incorrect:
06317471111(missing country code),(631) 747-1111(missing country code)
Import Process & Column Mapping
Drag & Drop Your File
Navigate to Contacts > Import Contacts (/contacts/import). Drop your spreadsheet onto the upload zone or click Select file.
Interactive File Preview
Once uploaded, WhatsBox parses the spreadsheet and renders an Interactive Sheet Preview, allowing you to visually verify row alignment and column headers.
Column Mappings
WhatsBox scans your sheet headers and presents a mapping interface:
| Field | Requirement | Description |
|---|---|---|
| Phone Number | Required | Select the column containing recipient phone numbers. |
| First Name | Optional | Select the column for the recipient's first name. |
| Last Name | Optional | Select the column for the recipient's last name. |
| Custom Attributes | Optional | Map any spreadsheet column (e.g. City, Company, Plan) to a matching Custom Attribute in WhatsBox. |
Assign to a Contact List
Choose how to categorize the imported contacts:
- Existing List: Select a list from the dropdown.
- Create New List: Enter a new name (e.g. "Product Launch RSVP - March 2026").
Submit & Monitor Progress
Click Import. A progress indicator tracks validation and insertion in real time.
Handling Duplicates
If a phone number in your spreadsheet already exists in WhatsBox:
- The contact record is updated with the new name and attributes provided in the sheet.
- The contact is added to the specified contact list without creating duplicate entries.