Importing contacts can be a valuable tool for seamlessly transferring your contacts from another system and promptly initiating your Freshchat experience. Here is a quick guide to importing contacts from a CSV/XLSX file into Freshchat:

Note: Supported file format: CSV or XLSX. Please convert all your files into .CSV or .XLSX format before attempting to import data.

1. Preparing your CSV/XLSX file

  • Ensure that your CSV/XLSX file's header row has columns mapped to the respective fields. The file should not be larger than 5MB. If you'd like to automatically assign contacts to users, create a column with the email addresses of the users, and map that column to the field Owner.

  • If a field allows for multiple selections (a multi-select field), each value in the CSV or XLSX file must be separated by a semicolon (;). 

Note: The email address must be the same one used to sign in to Freshchat.  

2. Importing the file

  • Once your CSV file is ready, navigate to Contacts on the left navigation bar

  • Locate the import button and select the Import from CSV/XLSX option

  • You can either import only your Contacts or import Accounts along with your Contacts.

  • Next, upload your CSV file

  • Once the file is uploaded, you will see an upload progress screen. During this time, rotating messages will be displayed on the screen, keeping you informed of the progress.

  • Next, review your mapping. After the upload is complete, you will be taken to a review screen where the following scenarios can occur:

    Scenario 1: Fields are mapped
    If you wish to change the field type, click on the drop-down menu next to the respective field and select the appropriate type. You can also change the (already mapped) field mapping based on your business preferences.
    Scenario 2: Unmapped Fields
    Fields with headers in the CSV will be automatically mapped. Ensure all the required fields are correctly mapped before proceeding. If you have columns with empty headers that aren’t mapped to any fields, you can create custom fields right from here.
If there are columns that you do not wish to import, you can skip those columns by unselecting the Import checkbox.

As fields get mapped, they become unavailable for mapping with another column (Fields are distinct).

  • Next, specify the date format used in your file:

    Choose if you want to:
    1. Create new records only: This captures all the data from the CSV/XLSX file as new records and does not look for duplicates.
    2. Create new records and update existing ones: This not only imports data from the CSV/XLSX file as new records but also updates any matching existing records based on your unique field identifiers.
    3. Update only your existing records: This strictly updates data in the system by using the CSV/XLSX file information and does not add any new records, ensuring only existing entries are modified.

  • Choose if you want to skip creating/updating duplicate contacts based on a unique field match.

Using identifiers:

  • When Email is used as an Identifier: The email field in the CSV/XLSX will be matched only with the primary email of Contact for finding duplicates. Secondary email addresses, if any, will not be considered.
  • The CSV/XLSX file will be matched with both Contacts to identify duplicates.
  • If you are importing multiple emails for a Contact through the CSV/XLSX file, the first email of the record will be matched as the identifier.
  • When a Phone number is used as an Identifier: Only if there is an exact match between the field value on the CSV/XLSX file and the stored record will the record be considered a duplicate.
  • Example: if a record contains 9003241245 and the CSV/XLSX file has a record containing the phone number +1-9003241245, then the two records will not be considered duplicates

  • Allocate a Sales Owner to contacts that are currently unassigned. Unassigned contacts are contacts that haven't been given a specific salesperson in the uploaded file.

  • Select More Settings > refine the details and preferences for importing your records.

  • For the records (contacts) you are importing, establish Tags, assign appropriate Marketing Lists, define Lifecycle Stages, and input Subscription Statuses, provided you have this information available beforehand, and click on the Import Now button.

  • You will be redirected to the Import History page, where you can monitor the status of your import. Here you’ll be able to find the details of your records created/updated, skipped, and errored.
  • To view the error logs, simply click on the Download button, and the file will be automatically downloaded.

Importing Accounts along with Contacts

  1. To Create or import new accounts while importing contacts, choose the below option and follow the same steps as mentioned above:
  2. Verify the mapping of the mandatory account fields. All mandatory account fields need to be mapped to corresponding fields. If you have missed any, you will encounter the system-generated error message.


If there are multiple (account) field values associated with a contact, the suite updates the contact with the latest value.

For example: If contact A with Account Name X already exists on the suite, and your import file contains Contact A with Account Name Y, then the suite updates Contact A with Account Name Y

Reasons for failure of data import

  • When importing records, these are the possible reasons for the failure of data import:
    • Invalid email address - If the email addresses in your CSV/XLSX file aren’t of the proper format (e.g: jamesampleton@sales, 
    • Unmapped Columns - Columns that aren’t mapped with any of the fields.
    • Improper Field Type - If the field type is different from the type of value in the column.
    • Picklist Values - If you’re mapping a column with values for a picklist (such as Radio button/Checkbox/Dropdown menu) with a field (also a picklist), double-check the values in the column to ensure that they match with the appropriate field choices.

      For example: If you’ve got a column that has the values 1, 2, 3 for the Number of Rooms and want to map it to a dropdown (field), make sure that that dropdown list has 1, 2, 3 as the field’s choices.
    • Admins can also set limits for users on how many records they can import and update for the day. 

Note: Import limit can be set only for Contact/Account/Deal modules and not custom modules.

To configure this,

  • Go to Admin Settings > Team Management > Roles > Choose a role (say Sales User)
  • Under Permissions > Actions, set the limit for creating and updating records during the import