Import Contacts and Organize Them
What it is
Contact import is the process of loading contact records into BotBat from an external file, typically a CSV (comma-separated values) spreadsheet. Each row in the file represents a single contact, and each column maps to a contact property such as first name, last name, phone number, email address, or any custom field you have defined. The import process validates your data, maps columns to the correct properties, handles duplicates, and creates or updates contact records in bulk.
Importing contacts is the fastest way to populate your audience when you are migrating from another platform, onboarding a new client account, or adding a batch of contacts collected from an event, signup form, or partner list. BotBat supports imports of any size, from a handful of records to hundreds of thousands of rows. Large imports run asynchronously in the background so you can continue working while the system processes your file.
Once imported, contacts are immediately available for segmentation, campaign targeting, and workflow enrollment. The import wizard also generates detailed error reports for any rows that fail validation, allowing you to fix and re-import only the problematic records without duplicating the successful ones.
When to use
Initial migration from another platform. You are moving your customer database from a legacy CRM, marketing tool, or spreadsheet into BotBat. Export your contacts as a CSV from the old system, align the columns with BotBat's property schema, and use the import wizard to bring everything in. This is typically a one-time operation performed during onboarding, though you can repeat it as needed for incremental migrations.
Bulk addition of new contacts. You collected a batch of new contacts at a trade show, through a partner referral program, or via a manual signup sheet. Rather than creating each contact individually, prepare a CSV with all the records and import them in a single operation. This saves time and ensures consistent data formatting across all new records.
Data enrichment and property updates. You have additional data for existing contacts, such as updated phone numbers, purchase history flags, or preference tags, and you want to merge it into your existing records. The import wizard's duplicate handling settings let you choose whether to update existing contacts with the new data or skip duplicates entirely, giving you full control over how the merge behaves.
Steps
1. Navigate to Customers and People
Open the sidebar, click Customers, and select People. The People page displays a searchable, filterable table of all contacts currently in your account. Each row shows the contact's name, phone number, email, tags, and the date they were added.
If this is your first time visiting the People page and you have not yet added any contacts, you will see an empty state with a prompt to import or create your first contact. The Import button is accessible from both the empty state prompt and the top-right action bar.
2. Open the import wizard
Click the Import button in the top-right corner of the People page. This opens the import wizard, a multi-step guided flow that handles file upload, column mapping, preview, and execution. The wizard validates your file at each step, catching errors early before any data is written to your account.
The first screen of the wizard provides a file drop zone where you can drag and drop your CSV file or click to browse your filesystem. Below the drop zone you will find the Download Template link, which gives you a pre-formatted CSV with the correct column headers.
3. Download and fill in the CSV template
Click Download Template to get a CSV file with BotBat's standard column headers already in place. The template includes columns for all default contact properties as well as any custom properties you have defined in your account.
Open the template in your preferred spreadsheet application (Excel, Google Sheets, LibreOffice Calc, or similar). Add one contact per row and fill in the appropriate columns. Pay special attention to the following formatting requirements:
| Field | Required Format | Example | Notes |
|---|---|---|---|
| Phone number | International format with + prefix | +14155551234 | Include country code; no spaces or dashes |
| Valid email address | jane@example.com | Must contain @ and a valid domain | |
| First name | Plain text | Jane | No special formatting required |
| Last name | Plain text | Doe | No special formatting required |
| Tags | Comma-separated within the cell | vip,newsletter | Used for quick filtering and grouping |
| Custom date fields | ISO 8601 format | 2025-06-15 | Year-month-day ordering |
Phone numbers are especially important because BotBat uses them as a primary identifier for WhatsApp and SMS channels. A phone number without a country code will either be rejected during validation or routed incorrectly. Always use the full international format.
4. Upload your completed file
Return to the import wizard and upload your completed CSV file by dragging it into the drop zone or clicking Upload File to browse. The wizard immediately validates the file structure, checking for proper CSV formatting, the presence of at least one data row, and column header detection. If the file cannot be parsed, the wizard displays a specific error message indicating what went wrong.
After a successful upload, the wizard displays a summary showing the total number of rows detected, the number of columns found, and the file size. Review these numbers to confirm they match your expectations before proceeding to column mapping.
5. Map columns to contact properties
The column mapping screen displays each column header from your CSV alongside a dropdown selector for the target BotBat property. The wizard auto-maps columns with names that match existing properties (for example, a column named first_name automatically maps to the First Name property).
Review every mapping carefully. For columns that were not auto-detected, select the correct property from the dropdown or choose Create New Property to define a custom property on the fly. You can also choose Skip This Column if the CSV contains data you do not want to import. Accurate mapping is critical; an incorrectly mapped column can overwrite existing data with wrong values.
6. Review the data preview
Before committing the import, the wizard displays a preview table showing the first several rows of your file with the applied column mappings. Each column header shows the target BotBat property name, and the cells below show the actual data that will be imported.
Scan the preview for obvious issues: phone numbers in the wrong column, names appearing where email should be, or special characters rendered incorrectly. If you spot a problem, go back to the mapping step and adjust. This preview step is your last chance to catch errors before the data is written to your account.
7. Configure duplicate handling
Before starting the import, choose how the system should handle contacts that already exist in your account. BotBat identifies duplicates by matching on phone number or email address. The available options are:
| Option | Behavior | Best For |
|---|---|---|
| Update existing | Merges new data into the existing contact record, overwriting matched properties | Data enrichment, correcting outdated information |
| Skip duplicates | Leaves existing contacts untouched and only creates new records | Adding net-new contacts without risking overwrites |
| Always create new | Creates a new contact record regardless of matches | Special scenarios where duplicate records are intentional |
The default setting is Update existing, which works well for most use cases. If you are unsure, choose Skip duplicates to take the safer approach, then review and update individually as needed.
8. Start the import
Click Start Import to begin processing. For small files (under a few thousand rows), the import completes within seconds and you will see a success summary on screen. For larger files containing tens of thousands of records or more, the import runs in the background. A progress indicator shows the current status, and BotBat sends you a notification when the import finishes.
Do not close the browser tab during a foreground import. Background imports, however, continue processing even if you navigate away or close the tab entirely.
9. Verify imported contacts
After the import completes, return to the People page and verify the results. Use the date filter to find contacts added today, or search for specific names or phone numbers from your CSV to spot-check individual records.
Open a few contact profiles and confirm that properties were mapped correctly, phone numbers include the country code, and custom fields contain the expected values. If the import produced any errors, download the error report CSV from the import summary screen. The error report lists each failed row along with the specific reason for failure, such as an invalid phone format or a missing required field.
Common pitfalls
Incorrect phone number format. Phone numbers that lack a country code are the single most common cause of import errors. Numbers like 5551234567 are ambiguous and cannot be routed to the correct country. Always prefix numbers with the international dialing code, such as +1 for the United States, +44 for the United Kingdom, or +91 for India.
Unexpected duplicate behavior. If you do not configure the duplicate handling setting before starting the import, the default behavior (update existing) may overwrite contact data you intended to keep. Review and explicitly select the duplicate handling option that matches your intent for every import.
File encoding issues. CSV files saved with encodings other than UTF-8 can corrupt special characters, accents, and non-Latin scripts during import. Before uploading, confirm that your spreadsheet editor is set to export as UTF-8. In Google Sheets, this is the default. In Excel, choose "CSV UTF-8" from the Save As format dropdown.
Exceeding column limits. If your CSV contains more columns than BotBat properties, the unmapped columns are silently ignored unless you explicitly skip them. This is not harmful, but it can cause confusion if you expected certain data to be imported. Always verify the mapping screen accounts for every column you care about.
If your import produces errors, do not re-import the entire file. Instead, download the error report CSV that BotBat generates automatically. This report contains only the failed rows along with detailed error reasons for each one. Fix the issues in the error report file and re-import just that file. This approach avoids creating duplicate records from the rows that succeeded in the original import and saves processing time for large datasets.
- People List
- Import Button
- File Upload
- Download CSV Template
- Column Mapping
- Data Preview
- Duplicate Handling
- Import Progress
- Post-Import Verification