Skip to main content

Documentation Index

Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt

Use this file to discover all available pages before exploring further.

Bulk contact import lets you upload multiple contacts at once through a guided import flow in your agent’s Contacts page. You can use this to:
  • Quickly add new contacts
  • Update existing contacts by External ID
  • Import custom attributes in bulk

​
Import contacts

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
You can also download a CSV template with the correct headers. The template includes:
  • Standard contact fields
  • Any custom attributes defined for the AI agent

​
Map columns

After uploading your file, Chatbase automatically matches your file headers to contact fields. 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

​
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

ConditionResult
Duplicate External ID in the fileRow is blocked
Duplicate email or phone in the fileRow is blocked
Email or phone already exists in another contactRow is blocked
External ID already existsRow is marked as Update to update the existing contact
Missing External IDRow is automatically excluded
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.

​
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. This includes:
  • Number of successful imports
  • Number of failed rows
  • Detailed error messages for failed rows
Example error: 
A contact with this email already exists
You can retry failed rows or close the dialog.

​
Add a single contact

Contacts can also be added individually. Go to: 
Dashboard → AI Agent → Contacts → Add Contact
The form includes:
  • External ID
  • Name
  • Email
  • Phone
  • Any Custom attributes
Important External ID is required when creating a contact manually.

​
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

​
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