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, any of your custom fields, 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 column whose header is the name of one of your custom fields is matched to that field automatically. Capitals and accents don’t matter, so a CPF column finds a field named cpf. You can also pick any custom field for any column by hand.
    • A column that isn’t one of your custom fields yet can become one: pick New custom field: in its picker and the field is created when you import.
    • If a custom field has a type (Number, Checkbox, Dropdown) and some of the column’s values don’t fit it, the wizard warns you how many rows that affects before you import. Those rows are skipped whole, name and email included. Click Switch to Text on the warning to change the field’s type in one step, or fix the values, or set the column to Don’t import.
    • 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. If you open the import while the Contacts page is showing one of your lists, that list is already picked for you; clear it if you don’t want it.
    • 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, though if you picked a list the contact you already have still joins it. 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), how many contacts you already had were added to the list you picked, and, if any rows were skipped, a breakdown of why (invalid phone number, missing phone number, duplicate, contact limit reached, etc.). If Update existing contacts was off and some rows matched contacts you already have, the result screen says so and offers Update these contacts: one click re-sends just those rows with the switch on, so you don’t have to import the file again.

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).
  • Custom fields — each of your custom fields is its own target. A header that matches a field’s name is picked for you; the value is saved on the contact exactly as it is in the file (a Number, Date, Checkbox or Dropdown field converts recognisable forms like 19,99, 01/02/1990 or yes). Pick New custom field to create a field from a column. With Update existing contacts on, custom field values in the file also update contacts you already have; empty cells leave the current value alone.
  • A column that holds identifiers with dots, dashes or leading zeros (a CPF, a tax number, a postcode) belongs in a Text field. In a Number field those values don’t fit and the row is skipped.

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. Picking a list still works on those rows: the contact you already have is added to the list and counted separately on the result screen, so re-importing the same file is how you fill a list with people already in your account. To also refresh their fields (fix names or emails, add tags), 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 on its own, because the header isn’t exactly company. Pick Custom field: company in that column’s picker and it imports into the company field. Renaming the header to company before uploading makes the wizard match it for you.

Some rows were skipped with “A custom field value doesn’t fit that field’s type” — why? The column is mapped to a typed custom field (for example Number) and those rows hold something else, like 001.576.401-08 in a Number field. Click Switch to Text on the warning in the Map columns step (or change the type under Custom fields) and import the file again with Update existing contacts on.

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