How to Import Contacts from a CSV

Rather than adding contacts one by one, you can bulk-import them from a spreadsheet — together with their tags, lists and custom fields. HitlChat matches on the WhatsApp number, so the same file can add new contacts and update existing ones. Here’s how to prepare the file, import it, read the results, and export.

Before you start

  • You need a connected WhatsApp Business profile (or WebChat channel).
  • Create your Tags, Lists and custom fields first if you want to reference them in the file — the import matches them by name, it won’t create new ones. (See Manage Contacts, Lists, Tags & Custom Fields.)
  • Have your data in a CSV file (most spreadsheet apps export to CSV).
1
Import / Export

Open Import / Export

In the left menu, under Contacts, click Import / Export (or the Import/Export button on the Contacts page). The top panel is Import Contacts, with a link: “Click here for an example on how to format your contacts CSV file.” — download that example to use as your starting template.

2
Prepare CSV

Prepare your CSV

Your file needs a header row. Two columns are required:

  • first_name — the contact’s first name.
  • mobile_no — the WhatsApp number, always with the country code (e.g. +27821234567).

These columns are optional:

  • last_name
  • subscription_status — Subscribed / Unsubscribed.
  • tags — one or more existing tag names.
  • lists — one or more existing list names.
  • any of your custom field columns (matched by field name).
Only first_name and mobile_no are required — everything else can be omitted or left blank. The example file shows both the required and optional columns laid out correctly.
3
Import Contacts

Upload and check the preview

Under Select CSV File, choose your file. HitlChat reads it and validates it before anything is imported:

  • If columns are missing you’ll see, e.g., “Your CSV file is missing the required column/columns…”; an empty or header-only file is flagged too.
  • If it’s valid, you get a ready message: “{N} contacts to be imported. Click ‘Import CSV’ to import your contacts now.”
Plan limit check: if the file would push you past your plan’s contact limit, HitlChat blocks the import and explains it — reduce the file size or upgrade your plan before continuing.
4
Import CSV

Import and read the results

Click Import CSV. While it runs you’ll see “Busy importing your contacts. Larger files will take longer to complete..” When it finishes, HitlChat reports exactly what happened:

  • {N} new contacts imported — brand-new contacts added.
  • {N} existing contacts updated — rows whose mobile_no already existed; the existing contact was updated rather than duplicated.

If any rows were skipped, you’ll see “Some contacts were not processed:” with the reasons:

  • Duplicate within the file — the same number appears more than once in your CSV.
  • Missing a first_name value.
  • Invalid mobile number — remember to always include the country code.
Because matching is by WhatsApp number, you can safely re-run an import to update contacts — existing people are updated, not duplicated.
5
Export

Export your contacts

The same page has an Export section:

  • Export Contacts (CSV) — downloads all your contacts. Handy as a backup, or to edit in a spreadsheet and re-import.
  • Export Conversations (CSV) — downloads your conversation listings instead.
An exported contacts file is already in the right format to edit and import back in.

Contact import FAQs

How do I bulk-import contacts into HitlChat?

Go to Contacts → Import / Export, prepare a CSV with at least first_name and mobile_no columns, choose it under Select CSV File, then click Import CSV.

Which CSV columns are required?

Only first_name and mobile_no. Optional columns are last_name, subscription_status, tags, lists, and any of your custom-field columns.

Can I assign tags and lists during import?

Yes — include tags and/or lists columns with the names. Create those tags, lists and any custom fields before importing, because the import matches them by name and won’t create new ones.

What happens if a contact already exists?

HitlChat matches on the WhatsApp number — “if a contact number already exists in your contacts, the existing contact will be updated” rather than duplicated. So you can re-import to update people in bulk.

Why were some of my contacts not imported?

Rows are skipped if they duplicate a number already in the file, are missing a first_name, or have an invalid mobile number. The most common cause is a missing country code — always include it (e.g. +27…).

Is there a template or example file?

Yes. The Import Contacts panel links to an example CSV (“Click here for an example on how to format your contacts CSV file”) showing the required and optional columns — use it as your starting template.

Is there a limit to how many contacts I can import?

Your plan sets a total contact limit. If an import would exceed it, HitlChat blocks the import and explains the limit — reduce the file size or upgrade your plan.

Can I export my contacts?

Yes. Use Export Contacts (CSV) to download all contacts (or Export Conversations (CSV) for conversation listings). The exported contacts file is ready to edit and re-import.

Related guides

Contacts

How to Manage Contacts, Lists, Tags & Custom Fields

Organize the contacts you import — lists, tags, custom fields and bulk actions.

Read guide →
Broadcasts

How to Send Bulk WhatsApp Broadcast Campaigns

Once your contacts are in, send a bulk WhatsApp campaign to your lists or tags.

Read guide →

← Back to all guides·See pricing

Stories from real businesses

Daniel Ortega

eCommerce Ops Manager

"WhatsApp is where most of our online customer conversations happen. Our Voiceflow assistant handles the basic questions really well, but when questions get more complicated hitlchat allows our team to jump in instantly without having to move the customer to another channel. It feels like true live chat inside WhatsApp and we’ve seen higher conversions because of it"

Sanjay Mehta

Conversational AI Agency

"The hitlchat setup is super simple, and its easy to use! Most of our clients run small teams handling WhatsApp conversations powered by a Voiceflow bot. hitlchat gives them one shared workspace to manage all their conversations. Being able to step into bot conversations directly inside WhatsApp has transformed their support workflows."

Lucas Bennett

Voiceflow Developer

"We've been building Voiceflow WhatsApp assistants for our clients across various industries (healthcare, ecommerce, restaurants etc) for a few years now. We had been looking for a way to route conversations from the Voiceflow assistant to live human agent for some time. Eventually we found out about hitlchat and honestly its been a gamechanger for us ever since. Our clients love it, and as a result we love it!"

Ready to try hitlchat ?

Create Your Free Account Now

No credit card required