Formatting your CSV

How to prepare your contacts CSV for a smooth import: required columns, phone number format, custom variable columns, and common pitfalls.

Required column: phone

Every CSV must have a column named phone (lowercase). Each value must be a phone number in international E.164 format — that means starting with a + sign followed by the country code and the subscriber number, with no spaces, dashes, brackets, or other separators.

Country	Correct format	Common mistakes to avoid
Nigeria	+2348012345678	08012345678, +234 80 1234 5678
South Africa	+27831234567	0831234567, +27-83-123-4567
Kenya	+254712345678	0712345678, 254712345678 (no +)
Ghana	+233241234567	0241234567, +233 24 123 4567

Numbers that do not start with + or contain non-numeric characters after the + will be skipped during import and reported as invalid.

Optional column: name

Adding a name column (lowercase) lets you personalise messages with the recipient's name and makes contacts easier to search and manage in the dashboard. Values can be a first name, full name, or a company name — whatever you intend to display in messages.

Custom variable columns for templates

If your WhatsApp template uses variable placeholders ({{1}}, {{2}}, etc.), you can map each placeholder to a column in your CSV. You do this during the campaign creation step, not at import time — so you can include as many extra columns as you need and map them later.

For example, a template like:

Hello {{1}}, your order {{2}} has been dispatched and will arrive by {{3}}.

would pair with a CSV like this:

phone	name	order_ref	delivery_date
+2348012345678	Chidi	ORD-10042	Thursday 12 June
+27831234567	Thabo	ORD-10043	Friday 13 June

During campaign setup you would map {{1}} → name, {{2}} → order_ref, and {{3}} → delivery_date.

How duplicates and invalid rows are handled

Duplicate phone numbers within the same import are de-duplicated: only the first occurrence is imported. If the number already exists in your workspace, the existing contact record is updated with any new column values from the CSV.
Invalid phone numbers (missing +, letters, too short, too long) are skipped. After import, the results screen shows a count of skipped rows and lets you download them as a separate CSV to fix and re-import.
Blank phone cells cause the entire row to be skipped. All other columns in a row are ignored if the phone number is invalid or blank.

File and encoding tips

Save your file as CSV UTF-8 (not CSV Windows-1252 or Excel default) to avoid garbled characters in names with accents or non-Latin scripts.
Column names in the first row are case-sensitive. Use phone and name in lowercase.
Do not include thousands separators in phone numbers (some spreadsheet apps format large numbers with commas).
Maximum file size per import is 10 MB, which comfortably covers around 100,000 contacts.

Next steps

Getting Started — full walkthrough from signup to first campaign
WhatsApp Templates — how to write and submit templates for approval
← All guides