Skip to main content
Bulk contact import lets you upload up to 1,000 contacts at once from a .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 get contacts-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)
The template includes a sample row. For example:

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
  • Email
  • Phone
  • Custom attributes
You can manually adjust mappings using the dropdown menus.
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

Phone numbers in +15555555555 form also help Chatbase match people who message your AI agent on WhatsApp to their contact.

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:
To fix failed rows:
  1. 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.
  2. Correct those rows in your original file.
  3. 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
  • Email
  • 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.
Rows per page, at the bottom left of the table, sets how many contacts are shown at a time, which is also how many the header checkbox covers. Raise it to select more per page, or use Select all N contacts to ignore paging entirely.
Deleting a contact is permanent: “They are removed from this agent immediately and cannot be restored.” Contacts can’t be exported from the dashboard, so if you need a copy, fetch them first with the list contacts API (up to 1,000 per page).

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.
For example, an attribute named 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

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.
Not from the dashboard. Use the list contacts API, which returns up to 1,000 contacts per page.
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.
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.
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.
Use YYYY-MM-DD, such as 2025-01-01, the format the CSV template uses. Other formats may not be read as dates.