Contacts

What it does

The contact importer creates or updates WhatsApp contacts from a CSV file, including each person's name, the customer they buy for, their authentication, and any WhatsApp marketing consent you already hold.

When to use it

• You have new phone numbers to add before building a segment or sending a campaign.
• You want to link contacts to the customers they buy for, after a customer import.
• You want to correct or fill in people's names.
• You already hold valid consent for these people and want to record it without sending an invite.

Import your customers first, on WhatsApp → Imports. Contacts are linked by customer reference, so the customers have to exist before the contact file is uploaded. See Customers.

Before using automatic opt-in, check your evidence against the consent requirements.

Steps

1. Open WhatsApp → Imports.
2. Select Import WhatsApp Contacts.
3. Read the notes in Import WhatsApp Contacts CSV. Select Download under Example CSV if you want a template to build your file from.
4. Select Pick CSV file and choose your file. It must be a .csv file, and the upload starts as soon as you choose it.
5. Wait for Upload complete. Import is processing now and will appear in Imports shortly. The dialog closes on its own; select Close to dismiss it sooner.

The dialog states: "This import is additive. Existing contacts are not deleted." Contacts missing from your file are left exactly as they are, so you can upload a small file of changes rather than your whole list.

What you'll see

Your upload appears in the list on WhatsApp → Imports with the folder contacts, first as Ongoing and then as Success, Failed or Stopped. See the imports overview for what each status means and how to open an import. ProConnect does not email you the result, so check the page.

Rows are applied one by one, so a Failed contact import can still have applied its good rows. Open the import and read Error details: it reports how many rows were processed, how many succeeded and how many failed, then lists the first failed rows with their row number and reason.

On CRM → Contacts you'll then see:

• New phone numbers added to the list, and matching numbers updated in place.
• Name showing the imported name, and Customer showing the customer the contact is now linked to.
• Authenticated reflecting the value in your file.

Open a contact to see Name and WhatsApp name separately. Opt-ins recorded by the file appear in WhatsApp → Consent Log.

If something goes wrong

• "Please select a CSV file.": the chosen file is not a .csv. Save your spreadsheet as CSV and choose it again.
• "We couldn't upload this CSV file. Please try again.": nothing was changed. Retry, and contact your onboarding manager if it keeps failing.
• The whole file is rejected with a header message: the first row must contain PHONE and AUTHENTICATED, in capitals exactly as shown, and may also contain NAME, CUSTOMER_REFERENCE and OPT_IN in any order. Any other column, a differently spelt column, or the same column twice, rejects the file before any row is read. Remove extra columns before uploading.
• "CSV file does not contain any data rows": the file has only a header row, or no rows at all. Add your contacts and upload again.
• "PHONE must be a valid E.164 number without '+'": the number cannot be read as a full international number. Use the country code followed by the number, for example 447700900123, and remove spaces, brackets and leading zeros.
• "AUTHENTICATED must be blank or one of: 1, 0, Y, N, TRUE, FALSE, YES, NO, ONE, ZERO": the cell holds something else. Use one of those values or leave it blank. A matching message, "OPT_IN must be blank or one of: 1, 0, Y, N, TRUE, FALSE, YES, NO, ONE, ZERO", appears for the OPT_IN column.
• "No customer found for CUSTOMER_REFERENCE ...": that customer has not been imported yet, or the reference is spelt differently. Import your customers first, then upload the contacts again.
• "CUSTOMER_REFERENCE is invalid": the reference does not match the format your account uses. Copy it exactly from your customer file.
• A contact still shows their WhatsApp profile name: the file had no NAME value for that number. Upload again with NAME filled in for the right phone number.
• Names disappeared after an import: the file included a NAME column with blank cells, which clears the imported name. Upload the names again, or leave the column out next time.
• Contacts are not opted in after OPT_IN=Y: consent already recorded for that contact is never overwritten, so an existing opt-out stays in place. Contacts also cannot be opted in before your channels are set up; check WhatsApp → Channels.
• Contacts were unlinked from their customers: the rows were uploaded with a blank or missing CUSTOMER_REFERENCE. Upload them again with the correct reference.
• Status shows Stopped: part of the file may have been applied. Check CRM → Contacts, then split the file and upload the parts.
• Still stuck: contact your onboarding manager with the Started time of the import.

Columns

Header names must be in capitals exactly as shown, and no header may appear twice. Column order does not matter. Unlike the eCommerce importers, headers in a different letter case are not recognised.

The older column names CONTACT_NAME and REFERENCE still work, so files you already have keep uploading. A file cannot use both names for the same column.

Yes and no cells accept 1, true, y, yes or one for yes, and 0, false, n, no or zero for no, with or without capitals.

There is no limit on the number of rows or the file size, but larger files take longer to finish. Rows are applied one by one, and the import report lists the first 25 failed rows.

The rest of the file follows the shared CSV file format rules.

Phone numbers

Numbers are stored as international digits without the plus sign, and are matched on that value. A number with a + in front is accepted and the + is dropped. A number without a country code, or one that is not a real number, fails that row.

Customer references

References are matched without regard to capitals, must be 1-36 characters, and can contain letters, numbers, hyphens, underscores and ampersands. Some accounts use a fixed nine-digit customer number instead; if yours does, copy the reference straight from your customer file. See Customers.

Authentication

Yes marks the contact as authenticated from now, but a contact who is already authenticated keeps their original authentication date. No clears the date. A blank cell leaves it alone.

Contact names

An imported name appears as Name on the contact's page and takes priority in contact lists and conversations. WhatsApp name shows the person's own WhatsApp profile name separately, and is shown in the list when no imported name is set.

Contact exports contain more columns than the importer accepts, including WHATSAPP_NAME, CUSTOMER_NAME and OPT_IN_STATUS. To upload an edited export, delete every column except PHONE, AUTHENTICATED, NAME, CUSTOMER_REFERENCE and OPT_IN.

Automatic opt-in

Use OPT_IN only when the contact has already given valid consent covering WhatsApp marketing across every one of your channels. Read the consent requirements before you do, and collect suitable consent first if you are unsure: the join page can gather it without sending an unsolicited WhatsApp message.

With OPT_IN set to yes, the import:

• Creates or updates the contact.
• Records the contact as opted in to every channel set up for your company.
• Sends no WhatsApp invite.
• Leaves any consent already recorded for that contact untouched, so an existing opt-out is preserved.

OPT_IN=N does not opt anyone out. Both no and a blank cell leave consent exactly as it is, and a file with no OPT_IN column never touches consent.

If a channel is added later, upload the contacts again with OPT_IN set to yes to opt them into the new channel. Consent already recorded on your other channels is unchanged.

Example CSV

PHONE,AUTHENTICATED,CUSTOMER_REFERENCE,OPT_IN,NAME
447700900123,Y,cust1001,Y,Alex Smith
447700900999,0,,,
447700900111,,cust1003,N,Sam Jones

In this example:

• Alex Smith is linked to cust1001, marked as authenticated and opted in to every channel.
• The second contact has its name cleared, is unlinked from any customer, has its authentication cleared, and keeps its current consent.
• Sam Jones is linked to cust1003 and keeps their current authentication and consent.

Download the sample contact CSV to use as a template.