Home Contacts | Records, import and export Bulk Contact Import via CSV

Bulk Contact Import via CSV

Last updated on Sep 22, 2026

When to use

  • You need to upload a new contact database to Cloud Chat

  • You want to update custom attributes of many contacts at once

  • You need to add tags or block contacts in bulk

Prerequisites

  • Be logged in as an administrator or supervisor

  • Have the CSV file encoded in UTF-8 with at least one identifier (email, phone number, or identifier) per contact

  • Keep the file size at a maximum of 10 MB

It's also possible to perform this import via API. Details at: How to bulk import contacts via API.

Access the import template

Step 1 — Download the template

Importing contacts is simple. First, download a CSV template.

  1. Go to the Contacts section in the sidebar menu

  2. Click on Import

  1. Download the CSV template (comes with examples)

Example of the CSV:

Each screen has its own template

Reusing a CSV for a different purpose is the most common cause of import or trigger failures. Always download the template from the current screen:

Purpose Template Columns
Import contacts (this screen) name, email, phone_number, company_name, city, tags
Campaign audience by email email, name
Campaign audience by phone phone_number, name
Import tags name, description, color

Important CSV details

These are standard columns — you can add more columns (tags, custom fields). Columns that Cloud Chat does not recognize will no longer automatically become custom fields: you decide what to do with each in the Review columns step below. To create custom fields beforehand, see: How to create custom contact and conversation fields.

The fields that determine a unique contact are phone, email, and identifier (identifier). At least one must always be present.

Columns that should not be changed should be deleted, except for key fields (email, phone, or identifier).

Behavior of blank fields

Field Behavior if blank
Name and standard fields Existing value is deleted
Custom fields Blank fields are ignored — existing value is preserved
Tags They do not substitute — they add (see below)
Email/phone/identifier (when not a key) Existing value is preserved

Tags — 3 formats

  • tags (recommended) — comma-separated list. Adds to the existing set (does not remove present tags)

  • tags_add — equivalent to tags. Adds without removing

  • tags_remove — comma-separated list. Removes specific tags

If the same contact appears in tags_add and tags_remove in the same import, removal wins (order: first add, then remove).

For mass removal through another method, use the Tag removal API.

Brazilian phone numbers

Always include the country code (+55) and the 9 at the start of the cell.

  • Without +55 → duplicate

  • Without the 9 → duplicate + impact on WhatsApp campaigns

Correct example: +5511960832431 (+55 is country code; the 9 was added by Anatel a few years ago).

Automatic normalization

Technical note: the system has automatic normalization — if you send +551160832431 (without the 9), the system adds it automatically. But we strongly recommend including the 9 in the CSV to avoid ambiguity.

Variant lookup (BR mobile-9)

When identifying existing contacts, the system searches for variants of the sent phone. If the CSV sends +5511933334444 and the contact exists as +551133334444 (without the 9), the match occurs and the contact is updated instead of duplicated.

Non-printable characters

Null-byte characters (\x00) in any cell are silently removed during import.

Blocking contacts via CSV

The blocked column is accepted and blocks the contact at the moment of import.

Operation Accepted values (case-insensitive)
Block true, 1, yes, t, on
Unblock (if already blocked) false, 0, no, f, off
Empty New contacts: unblocked by default. Existing contacts: current state preserved

Change from 04/30/2026: accounts that sent CSVs with blocked before this date had this column silently ignored. Now, the value is respected. To retroactively apply historical values, re-import the CSV.

Deleting data via CSV

To delete a field from an existing contact, use the special value __DELETE__ in the cell:

  • In phone_number, email, identifier, name → the field is cleared (NULL)

  • In custom attribute columns → the key is removed from the contact's JSON

  • Does not work in blocked — to unblock, use false (or 0/no/f/off)

If you explicitly use the string "__DELETE__" as a legitimate value in any field, contact support beforehand to avoid data loss.

Attention: dual-write in company, company_name, and city

Values in company, company_name, and city columns are simultaneously written into additional_attributes and custom_attributes of the contact. This ensures dashboards, filters, and segmentation find the value.

Change from 04/30/2026: Previously, only additional_attributes was populated, which caused inconsistency in filters based on custom attributes.

What happens in practice

When importing:

  1. System checks if the contact already exists — by email, identifier, and phone, in that priority order

  2. If not found → creates a new contact

  3. If found → updates information according to blank field rules

ID ambiguity (AMBIGUOUS_MATCH) — if the CSV contains a contact with two or more key fields (email, phone, identifier) pointing to different existing contacts, the row is rejected with error AMBIGUOUS_MATCH.

Example: if email [email protected] belongs to contact A, but phone +5511960832431 belongs to contact B, the system cannot know which to update and rejects the row.

Change from 04/30/2026: Previously, the system used the first match found and silently overwritten data. Now, the row is explicitly rejected. Fix manually before re-importing.

Duplicate rows in CSV

If the CSV has two or more rows with the same email, phone, or identifier, only the first is processed — the others are rejected as duplicates. This applies even if other details differ.

Tip: review your CSV before importing.

Adding more information (tags and custom fields)

You can add any information by creating a new column with the key as the header.

Add tags

Create a column tags and fill each cell with the desired tag.

The tag must already exist. If it does not, your import will fail.

Create tags in Settings → Tags or directly in the contacts tab:

Add custom attributes

Use the key of the custom attribute from Settings → Custom Attributes as the column header in the CSV.

Upload the import to Cloud Chat

Save the spreadsheet as CSV (UTF-8), go back to the import section, select the file, and click Import.

Review columns

If the file has at least one unrecognized column, a review step appears before importing. If all columns are recognized, import proceeds directly.

At this step, you decide, column by column:

Action What happens
Ignore The column is not imported. Nothing is created from it.
Create a new custom field Creates a new contact custom field (text type) with the column name. If one with the same key exists, it is reused.
Map to an existing column Sends the content to a standard field (name, email, phone_number, company_name, city, tags) or a custom field already in the account.

Suggestions are pre-filled: unknown columns are set to Create new custom field; deprecated columns are set to Ignore, with a warning on screen. Two columns cannot be mapped to the same destination.

Deprecated fields: id, ip_address, and identifier appear marked as deprecated and are suggested to be ignored. Do not use your old tool's id column as a contact identifier — identifier remains accepted as a key, but is no longer recommended for new bases.

Before this step, any unrecognized columns automatically became custom fields without warning. That's how fields like id or ip_address ended up in old account contact records — you can delete them in Settings → Custom Attributes.

Once the system finishes (it can take up to 30 minutes), you'll receive an email with the count of successes and failures.

IMPORTANT: ensure your CSV is in UTF-8 encoding. Other encodings may produce invalid characters or prevent tag matching.

Notes