Importing contacts
Instead of adding contacts one at a time, you can import a whole list from a spreadsheet file. Upload a .csv or .xlsx file (up to 50 MB) and the app walks you through matching its columns to your contact fields, checking for duplicates, and previewing what will happen before anything is actually saved.
Steps
- Open the composer (the message box you use to chat or start a campaign) and click the + menu.
- Choose Import contacts file.
- Select a
.csvor.xlsxfile from your computer. The app rejects files of the wrong type or larger than 50 MB before uploading, so you'll know right away if something needs fixing. - An import card appears where you can review and adjust the plan:
- Column mapping — each column from your file is matched to a contact field (built-in or custom). Accept the suggested matches, point a column at a different field, or create a brand-new custom field on the spot for a column that doesn't have a home yet.
- Match key — choose how the app recognizes a contact you already have: by email, by phone, or by a custom field. This is what determines whether a row is "new" or a "duplicate" of someone already in your account.
- Duplicate handling — choose what happens when a row matches an existing contact:
- Update empty fields only — fill in blanks on the existing contact without overwriting anything they already have.
- Overwrite — replace the existing contact's values with the ones from the file.
- Most recent wins — whichever record was updated more recently keeps its data.
- Skip existing — only add brand-new contacts, and leave existing ones untouched.
- Subscription consent — optional, and off unless you choose otherwise. If these contacts opted in to email somewhere else — a sign-up sheet, a trade-show booth, a system you're moving off — you can subscribe them to one of your lists as part of the import and record where that consent came from. Note that only lists with double opt-in switched on are offered here, and double opt-in isn't generally available yet — so this option isn't usable today. See Double opt-in for exactly what it does and doesn't do.
- Silent import — on by default, and worth understanding before you turn it off. A silent import quietly adds and updates records and nothing else. Turn it off and the import runs live: every contact it adds or changes can start a journey that's listening for new or updated contacts, which for a large file can mean enrolling thousands of people at once. The summary line on the import card always tells you which mode you're in.
- Once you're happy with the mapping and settings, the app shows a preview with counts of rows that are ready to import, flagged as errors, matched as duplicates, or skipped.
- Start the import. You'll see it move through in progress to done, with a final report of what happened.
- If any rows had problems, download the error rows to see exactly which ones and why, fix them in your file, and re-import just those.
Importing from a session
You can also hand the file to the assistant instead of walking the wizard. Attach the file in any session and say what you want:
- "import contacts @[Uploaded file name]"
- "Import the contacts from the file I just uploaded. Show me a preview before writing anything."
@[Name] stands for an @-mention of the uploaded file — see
Pointing at your own data.
The assistant runs the same preview-then-commit sequence the wizard does:
nothing is written until you've seen the preview and confirmed it.
Tips
- Give your columns clear, simple headers (like "Email" or "Phone") before uploading — it makes automatic column matching more accurate, so you have less to fix by hand.
- Double-check your match key choice before importing a large file: it decides whether returning contacts get updated in place or accidentally duplicated.
- You can add tags or a segment to every contact from a given import as part of the same flow, which is a fast way to group a freshly imported list for a welcome campaign.
- Large files take a little time to process — you can leave the import running and come back to check its progress.
FAQ
Q: What file formats are supported?
A: .csv and .xlsx, up to 50 MB per file.
Q: What if a column in my file doesn't match any existing field? A: You can create a new custom field right from the mapping step — see Custom fields for what that means for the rest of your account.
Q: Will importing send anything to the contacts I'm adding? A: No. Importing only adds or updates contact records — it never sends an email, SMS, or notification on its own. That holds even when you use Subscription consent to subscribe them to a list: no confirmation emails are sent, however big the file.
Q: What is the Subscription consent option for? A: For contacts who already opted in to your email somewhere outside the app. You pick the list, write down where the consent came from, and the import subscribes them and stores your note as the record of it. Both parts are required together — a list without a note won't save. Leave it alone and the import touches no subscriptions at all. Full detail in Double opt-in.
Note: the list picker only offers subscription lists that have double opt-in switched on, and double opt-in isn't generally available yet — so in practice this option can't be used today. See Double opt-in.
Q: Can an import trigger an automation that sends something? A: Not on its own — an import never composes or sends an email or SMS by itself. With Silent import left on (the default), that's the whole story: records are added and updated, and nothing else happens. If you turn Silent import off, the import runs live and the contacts it adds or changes can be picked up by journeys that trigger on new or updated contacts — and those journeys can send. So the sending, if any, comes from your journeys, not from the import. See Triggers.
Q: What happens to rows that fail? A: They're excluded from the import and counted separately in the preview and final report. You can download just the failed rows, correct the issue, and re-import them.