Your AI Connector Docs

Importing Contacts from a File

If you have a list of contacts in a spreadsheet, you can upload them all at once instead of adding them one by one. The app uses a 3-step wizard — Upload → Map columns → Review — that works with the CSV file you already have, without needing to download a template first.

How to Import Contacts

  1. Click Contacts in the left sidebar, then click Import at the top of the page.
  2. Upload. Drag your CSV file onto the dropzone, or click it to browse. There’s no template to download first — bring the file you already have.
  1. Map columns. The wizard reads your file’s header row and tries to auto-match each column to a target field: First name, Last name, Phone, Email, Tags, Notes, or Don’t import. Check each column’s guess and correct any that are wrong using the picker next to it. A preview table shows the first few rows exactly as they’ll be imported.
    • A phone number column is required — you can’t continue without mapping one.
    • A column mapped to Tags becomes real tags on each contact. Several tags in one cell are fine — separate them with a comma or semicolon (vip; newsletter; hotmart). Tags that don’t exist yet are created for you; tags that already exist are reused, ignoring capitalisation.
  1. Review. Choose:
    • Default channel — WhatsApp Business, WhatsApp Web, or SMS. This applies to any imported contact that doesn’t already specify a channel.
    • List — pick an existing list from the dropdown, or type a name to create a new one on the spot. You can only do one or the other, not both.
    • Update existing contacts — off by default. Off, rows that match a contact you already have (same phone number) are skipped as duplicates: nothing on that contact changes and it is not added to the list. On, those rows update the contact instead: the name, email and notes in your file overwrite what’s there (empty cells leave the current value alone), any tags in the row are added, and the contact is added to the list you picked. This is how you re-import a file to fix or enrich contacts you already have.
  1. Click Import [count]. You’ll land on a result screen showing how many contacts were created, how many existing contacts were updated (when that option is on), and, if any rows were skipped, a breakdown of why (invalid phone number, missing phone number, duplicate, contact limit reached, etc.).

Column Mapping Details

  • Phone is the only required column. Rows with no phone number at all are dropped before import and counted separately in the result screen.
  • First name / Last name / Email map directly onto the contact’s basic fields.
  • Notes maps onto the contact’s Notes / Lead Profile field.
  • Tags creates (or reuses) real tags and applies them to the contact — the same tags you filter by, target broadcasts with, and fire webhooks from. Put several in one cell separated by commas or semicolons. Before 19 August 2026 this column was saved as a custom field named tags instead; if you imported before then, re-import the same file with Update existing contacts on and the tags are applied properly (the leftover tags custom field does no harm; message support if you’d like it cleared from every contact).
  • There’s currently no column mapping for arbitrary custom fields (like classic’s custom_<fieldname> columns) — see Bulk-Loading Custom Fields for the current workaround.

Tips

  • Double-check that phone numbers include the country code. Without it, messages will not deliver — and rows without a usable phone number are skipped entirely.
  • You don’t need to strip spaces, dashes, or parentheses from phone numbers — the importer tolerates common formatting, but it does still need the country code.
  • Files are parsed entirely in your browser, so there’s no fixed upload size limit from the wizard itself — but your total contact count is still capped by your plan. If an import would push you over your plan’s limit, those rows are rejected and show up in the result screen as contact_limit_reached.
  • If a contact with the same phone number already exists, that row is skipped by default — it shows up as duplicate on the result screen. The import never creates a second copy of someone. To bulk-edit contacts you already have (fix names or emails, add tags, put them on a list), turn on Update existing contacts on the Review step and re-import the file.

Frequently Asked Questions

My CSV has a custom_company column from an old export — will it map correctly? Not automatically. The wizard’s auto-matcher only recognises name/phone/email/tags/notes headers; anything else defaults to Don’t import, so a custom_company column won’t populate the company custom field on its own. Add the values afterwards via Custom Fields, or through the API.

Where did the “Download Template” button go? It’s gone — the wizard works directly with whatever CSV you already have and lets you fix any mismatched columns in the Map step instead.

I already imported my contacts — how do I add tags or fix fields for all of them at once? Re-import the same file (or an updated one) with Update existing contacts switched on in the Review step. Rows that match an existing phone number update that contact — name, email, notes, tags and list — instead of being skipped. Only phone numbers are used to match, so keep that column exactly as it was.

Can I import Instagram or Messenger contacts from a file? No. Import only supports WhatsApp Business, WhatsApp Web, and SMS, because those channels reach people by phone number. Instagram and Messenger identify people by their social account instead, so those contacts are created automatically when someone messages you on that channel.

Can I import contacts as bot-inactive? There’s no per-row column for it. Import the batch first, then use the bulk Bot off action on the imported contacts — see Excluding Contacts from the AI Bot.

Next Steps