.csv or .xlsx file, through a guided import flow on your AI agent’s Contacts page. This page also covers adding a single contact, deleting contacts, and defining custom attributes. Contacts are available on the Basic plan or higher. See Contacts overview for how contacts are used.
You can use this to:
- Quickly add new contacts
- Update existing contacts by External ID
- Import custom attributes in bulk
Import contacts
Click Import on the Contacts page. The import flow consists of four steps.Upload file
Upload a.csv or .xlsx file by dragging it into the upload area or clicking to select a file.
Limits
- Maximum file size: 5 MB
- Maximum rows per upload: 1,000
File format
- CSV: columns must be separated by commas. Semicolon-separated files won’t split into columns. Fields in quotes are allowed. Save the file as UTF-8 so accented and non-Latin characters import correctly.
- Excel (.xlsx): only the first sheet is read.
- Headers: the first row must hold the column headers.
CSV template
Click Download CSV template to getcontacts-template.csv with the correct headers. The template’s columns are:
- External ID, Name, Email, and Phone Number
- One column per custom attribute defined for the AI agent, headed with the attribute’s Label (or its Name if it has no Label)
Map columns
After uploading your file, Chatbase automatically matches your file headers to contact fields. Headers are matched to a field’s key or label, ignoring upper and lower case. Supported fields include:- External ID
- Name
- Phone
- Custom attributes
Important External ID is required. You must map a column to External ID before continuing.
Mapping rules
- Each CSV header can only be mapped to one field
- Custom attributes appear automatically during mapping
- Unmapped columns are ignored during import
Value formats
Review and confirm
Before importing, Chatbase displays a paginated preview table with all mapped rows. Each row is validated against existing contacts and duplicate values.Duplicate handling
Rows marked as Update will update the existing contact with the same External ID.
You can hover over warning icons or the Update badge to see more details, including which fields will change.
Note Phone numbers are normalized to E.164 format before duplicate checks are performed. The number itself is saved as you typed it.
Row selection
You can:- Select individual rows
- Deselect rows you do not want to import
- Use the Select all checkbox
Completing the Import
After the import completes, Chatbase displays the import results: how many contacts were imported and how many failed, for example “98 imported, 2 failed”. Failed rows are listed in a table with the Row, External ID, and Error for each one. Example error:- Click Download failed rows to save
failed-contacts.csv. It lists the row number, External ID, and error for each failed row, but no contact data. - Correct those rows in your original file.
- Import a file with just the corrected rows.
Import errors
“Will update existing contact” in the review step isn’t an error. It means the row’s External ID matches an existing contact.
Add a single contact
Contacts can also be added individually. Go to Contacts and click Add contact. The form includes:- External ID
- Name
- Phone
- Any Custom attributes
Important External ID is required when creating a contact manually.
Delete contacts
Contacts are deleted from the Contacts page in the dashboard. There is no cap on how many you can remove at once.1
Select the contacts
Tick individual rows, or use the checkbox in the table header to select every contact on the current page. A banner then confirms what you have, such as All 20 contacts on this page are selected, next to a Select all N contacts button that widens the selection to every contact across every page.
2
Delete them
A toolbar appears at the bottom of the page with the number of contacts selected and a Delete button. The × beside it clears the selection without deleting anything.
Custom attributes
Custom attributes allow you to store additional information about contacts. Manage them from Contacts > Manage attributes.Supported attribute types
- Text
- Number
- Boolean
- Date
Naming rules
Each attribute has a Name and an optional Label:- Name is the identifier for the attribute. It must start with a letter or underscore and can only contain letters, numbers, underscores, and hyphens. Spaces are turned into underscores as you type.
- Label is the name shown in the contacts table and used as the attribute’s column header in the CSV template.
loyalty_tier with the label Loyalty tier.
Behavior
- Custom attributes appear during import mapping
- Custom attributes appear in the contacts table
- Archived attributes are hidden from forms
- Archived attribute data is preserved
Frequently asked questions
How many contacts can I import at once?
How many contacts can I import at once?
Up to 1,000 rows and 5 MB per file. For more, split your list into several files. There’s no limit on the total number of contacts per AI agent.
Can I export contacts to a CSV?
Can I export contacts to a CSV?
Not from the dashboard. Use the list contacts API, which returns up to 1,000 contacts per page.
How do I retry rows that failed to import?
How do I retry rows that failed to import?
Click Download failed rows on the results screen to see each failed row and its error. Fix those rows in your original file and import them again.
Do phone numbers need a country code?
Do phone numbers need a country code?
The import accepts numbers without one and saves them as typed. Including the country code, such as
+15555555555, is recommended so WhatsApp messages can be matched to the contact.Why are my columns not splitting correctly?
Why are my columns not splitting correctly?
The CSV must be comma-separated. Files that use semicolons, which some spreadsheet apps export by default, are read as one column. Re-export as a comma-separated CSV in UTF-8.
What format should dates be in?
What format should dates be in?
Use
YYYY-MM-DD, such as 2025-01-01, the format the CSV template uses. Other formats may not be read as dates.