How Do I Import Subscribers Using a CSV File with ChatSyncs?
Step-by-step guide to bulk-importing subscribers into ChatSyncs from a CSV file — required columns, the Excel scientific-notation bug, and column mapping.
On this page
When to use CSV import#
Use CSV import when you already have a spreadsheet of contacts — exported from another tool, a sales list, an event sign-up sheet — and want to bring them all into ChatSyncs at once, instead of adding them one at a time or waiting for each person to message the bot first. It's the fastest way to seed Subscriber Manager with an existing contact list.
Only have a handful of contacts, or contacts already living in a Google Sheet or your Google account? See How Do I Add a Subscriber Manually?, How Do I Import Subscribers from Google Sheets?, or How to Import Contacts from Google Contacts instead.
Import a CSV file#
Open Export/Import → Import from CSV
From the Subscriber Manager list, open Export/Import, then Import from CSV.
Select a Label, List, and Bot
Select Label and Select List are both optional — tag or group every imported subscriber right away (e.g. label
batch1, or a dedicated import list). Select Bot is required — pick which bot the imported subscribers belong to.Prepare your file to match the required format
At minimum, your CSV needs a phone number column and a name column — see the table below. A Sample CSV link in the modal shows the exact expected format.
Upload the file
Select your prepared CSV file to upload it.
Map each column
Match each column in your file to a ChatSyncs field — see "Map the columns" below.
Confirm the import
Click Confirm — the imported contacts appear in the Subscriber Manager list.
The CSV format#
A CSV needs at minimum a phone number and name column, e.g.:
| phone_number | name |
|---|---|
| 919876543210 | User 1 |
| 919876543211 | User 2 |
Example with extra columns: A gym exporting its members list adds city and
membership_type columns alongside the required two:
| phone_number | name | city | membership_type |
|---|---|---|---|
| 919876543210 | Priya Sharma | Bangalore | Gold |
| 919876543211 | Raj Verma | Mumbai | Silver |
After import, every subscriber has city and membership_type filled in automatically as
custom fields — no extra setup needed as long as those fields already exist (or ChatSyncs creates
them from the column header the first time you map them).
Map the columns#
After uploading, map each column from your file to a ChatSyncs field:
- Map
phone_number→ Phone Number. - Map
name→ Subscriber Name. - Verify every mapping carefully before confirming — a wrong mapping imports the wrong data into the wrong field for every row.
Expected result: Every row in your file becomes a subscriber in Subscriber Manager, with extra columns populated as custom fields — ready to label, message, or enroll in a sequence immediately.
Troubleshooting#
| Problem | Likely cause | Fix |
|---|---|---|
| Import fails immediately | Missing phone_number or name column | Check your header row matches the Sample CSV exactly. |
Numbers show as 8.8E+12 | Excel scientific notation | Format the column as Number (0 decimals) or Text before saving — see above. |
| A row didn't import | Blank phone number, or a duplicate header row mid-file | Remove blank rows and check for a second accidental header row. |
Names show as ????? or garbled characters | File saved with the wrong encoding | Save the CSV as UTF-8 so non-English names (e.g. Hindi, Arabic script) survive the export. |
| Some rows updated existing subscribers instead of creating new ones | Their phone number already existed in ChatSyncs | Expected behavior — see the FAQ below on importing an existing phone number. |
Frequently asked#
What columns does my CSV file need at minimum?
A phone_number column and a name column. Any other column is imported automatically as
a custom field.
Can I import custom fields along with my subscribers?
Yes — any column beyond phone_number and name is imported automatically as a
custom field, matched by
its column header.
Why do my imported phone numbers look wrong or truncated?
Excel often displays long phone numbers in scientific notation (8.8E+12). Format the
phone number column as Number (0 decimal places) or Text — right-click → Format
Cells — before saving the file as CSV, or the import will bring in the garbled value.
What happens if I import a phone number that's already a subscriber?
The existing subscriber record is matched by phone number and updated — any new custom field columns are added or overwritten, rather than creating a duplicate.
Do I need the country code in the phone number column?
Yes — the country code is mandatory and the number should be plain digits with no + or
spaces, e.g. 919876543210.
Can I preview the expected file format before uploading?
Yes — the Import Subscribers modal has a Sample CSV link showing the exact expected column layout.
My subscribers' names show as question marks or broken characters after import.
The file was likely saved in the wrong text encoding. Re-save the CSV as UTF-8 — most spreadsheet tools offer this as a save/export option — before uploading again.
Is there a limit to how many rows I can import in one CSV?
Very large files may take longer to process, but there's no need to split a normal business-sized contact list — if a single import seems to stall, try splitting it into a few smaller files as a workaround.
Can I import the same CSV file twice without creating duplicates?
Yes — every row is matched by phone number. Re-importing the same file updates the existing subscribers (and any changed custom field values) instead of duplicating them.
Related Documentation#
- Subscriber Manager — the subscriber list, Options menu, and Download(all) as CSV.
- How Do I Manage Custom Fields and Labels? — how imported columns become custom fields.
- How Do I Add a Subscriber Manually? — for adding one contact at a time instead.
- How Do I Import Subscribers from Google Sheets? — for importing without exporting a CSV file first.
- How to Import Contacts from Google Contacts — for importing straight from your Google account's saved contacts.
Watch the video lesson
Was this page helpful?
Still stuck? Open a support ticket and our team will help.