Bulk Contact Import via CSV
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
:::info 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
3. 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.
:::warning The fields that determine a unique contact are phone, email, and identifier (identifier). At least one must
always be present.
:::
:::info 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
:::info 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
:::warning 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
:::info 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 |
:::warning 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)
:::warning 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
:::warning 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
:::error 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
:::warning 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.
:::warning 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.
:::warning 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.
:::
:::info 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.
:::
:::success Once the system finishes (it can take up to 30 minutes), you'll receive an email with the count of successes
and failures.
:::
:::error IMPORTANT: ensure your CSV is in UTF-8 encoding. Other encodings may produce invalid characters or prevent tag
matching.
:::
Notes
- For volume uploads via API: How to bulk import contacts via API
- For importing via HubSpot: How to import contacts via HubSpot
- To create custom attributes before using in CSV: How to create custom contact and conversation fields
- To remove tags in bulk via API: How to bulk delete tags from contacts
