Custom modules enable support teams to gather and show all the necessary customer information right where the agents need it the most. Freshchat is equipped with the basic modules required to store and retrieve customer information. However, depending on the business requirements of certain industries, support teams using Freshchat can make use of custom modules to capture and process any additional information.

Note: Admins can create a maximum of 10 new modules. This does not include the existing 4 core modules  


Creating a new custom module

  • Navigate to Admin Settings > Custom Modules

  • Click the create an object button, and you will be presented with a sidebar to fill in the details (singular name, plural name, internal name, icon, module description). The name field will become the identifier for the custom module across your account.

  • Click Save to create a new custom module, and you will be redirected to the custom module page, where you can create and modify fields related to the newly created module. You will also notice that the icon is part of your sidebar in Freshchat. You can also navigate to the custom module using this icon.

Note: You can choose to rearrange the sidebar so that you don't see this icon — or choose to move it to a more accessible location. Hover over the Settings icon > Manage Left Nav Bar

Personalizing custom modules

You can use multiple fields for each custom module to capture your business' required information. Freshchat will create these fields for each new record your team creates with this custom module. This enables your team to capture the different information for each record created using this custom module.

For example, if you set up a custom module to gather information about the type of instruments each customer buys, you'd have set up fields to capture information about the price, discounts, date of purchase, etc., which gets stored for every record that is made by your team.

Here's how you use fields in your custom modules.

  • Once you've created a custom module, click on Customize fields > Add fields to access these fields.

  • There are six default fields, and they are not editable:

    Field Name



    The default field used to identify the custom module.


    Name of the user who is currently assigned the record.

    Created by

    Name of the user who created the record.

    Created at    

    Date and time when the record was created

    Updated by

    Name of the user who made the latest edits to the record.

    Updated at

    The latest date and time when edits were made to the record.

  • Apart from these default fields, Admins can include custom fields that suit their business requirements.


  • Select the field type, click add selected, and fill in the necessary details (field label, internal name, field type, tooltip, any grouping, add a placeholder value, and configure the mapping for the field) before clicking Save.


Note: Admins can create a maximum of 310 fields per custom module.

Adding custom module records

We briefly came across records and unique custom modules in the previous section. Records are created when agents store customer information in a custom module. Agents can do this directly from the widget in the Team Inbox during a customer conversation. Admins need to set up lookup fields and inbox widgets for agents to make the most out of custom records properly.

Setting up lookup fields

Lookup fields create relationships between different modules and display related lists of a record. You can use a lookup field to associate two different modules or pull up a list of records in another module. For example, a realtor would create a Property field lookup titled ‘Property interested in’ and link it with the Contacts module to look at which properties a contact would be interested in.

Note: Lookup fields are available only for Pro and Enterprise plan customers.

Pro plan users can create 10 lookup fields.
Enterprise plan users can create 50 lookup fields.

  • To set up Lookup fields for your contacts, navigate to Admin settings > Contacts > Add field > Lookup

  • Use the Related to drop-down to choose between User, Contact, and Account or any custom modules you created – and click Save.

  • To set up Lookup fields for your conversation properties, navigate to Admin settings > Conversation properties > Lookup. Fill in the necessary details, and use the Target object like the Related to field to map it to the right custom module.

  • Creating a relationship between two modules enables users to display related records on the details page of a record. Lookup fields can be used across Freshchat. 

Setting up inbox widgets

Admins can set up the Team Inbox to showcase up to five fields as part of the widget.

  • To set this up, navigate to Admin settings > Custom modules and click on the specific custom module > Customize widget.

  • Your agents can now see the option to update these custom records from customer conversations. Once the records get updated, you can use the option to look up fields with custom modules in many scenarios, for example:
    • Related lists on the record details page

    • Filters in the list view

    • Bulk updates

    • Column customization 

    • Workflow actions

    • Filters in workflows 

    • Email placeholders

Importing custom module records

If you already have your custom records from a different system, you can import them via a CSV file or an API call instead of adding them manually.

Note: .CSV and .XLSX are the only supported formats. Please convert all your files into a .CSV/.XLSX before attempting to import.

1. Preparing your import file

  • The file should not be larger than 5MB.

  • The import file should have a header row with columns that map to the fields.

  • If you'd like to assign the records to your team in Freshchat automatically, create a column with the email addresses your agents use to sign in to Freshchat — and map that column to the field owner.

  • Create relevant custom fields before you begin the import so that the columns can be mapped with the appropriate fields. If any field is a multi-select field, the values of the field should be separated by a semicolon(;) in the .CSV file, for example:

    Name of the property


    221B Baker Street

    Balcony; High ceiling; Centralized Ventilation 

    13B Royal Crest

    Balcony; Centralized Ventilation

2. Importing the file

  • Once you've uploaded a CSV file, choose one of two options:
    • Add as new records: This turns all the data from the CSV file into new records and does not look for duplicates.

    • Find duplicate records on the CSV file: Identifies duplicates between the CSV file and the web application records by matching them based on the Freshworks CRM ID.
      • Additionally, all fields of type ‘Text field’ and ‘Number’ will be automatically detected and can be used for matching.

  • If any duplicates are found you can again choose between one of two options:
    • Skip import for all duplicate records: You can skip import for all duplicate records. This will prevent the web application from updating records that are already present. You will also receive an import summary email with a CSV file containing all the skipped records. 

    • Update all duplicate records: 
      • With Overwrite: Updates all the fields and overwrites any existing values.
      • Without Overwrite: Updates only the empty fields.

3. Mapping fields

  • The Map Columns To Freshworks CRM Fields overlay is exclusively for mapping the columns in your CSV file with the fields available in Freshchat.

Mapping the fields is critical to the success of the import, so here’s a list of know-how to help you do it right.

  • If there are columns you do not wish to import, you can skip them by not mapping them with any field.

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

  • Make sure the field type matches the type of value in the column. 

    • For example, if you’re trying to map the column Number of Rooms, you need to find a field that accepts numeric value viz the Number field. If you’ve mapped it to a field, which is a text box, then the values for the column Number of Rooms will not be imported.

  • After you’re done mapping the fields, hit Import.

    • If your CSV file is small, the import will be instantaneous, and you can see a green label that gives you the number of successful imports.

    • If the CSV file is large, you will be taken to the import progress screen, where you can see the progress of your imports.


4. Why did some of my data not get imported? (Reasons for failure of data import)

  • Unmapped Columns: Columns that aren’t mapped with any of the fields in the web application.

  • Improper Field Type: If the field type is different from the type of value in the column.

  • Values assigned to field choices: If you’re mapping a column with values for field choices (such as radio button/checkbox/dropdown menu) with a field in the web application (also a picklist), double-check the values in the column to ensure that they match with the appropriate field choices.

Processing custom module records

  • Admins can check all existing custom modules by clicking the custom module icon to open the list view of all custom module records.
  • From this screen you can select multiple records for bulk actions such as Assign, Update, and Delete. You can select a set of records and execute bulk actions on the records.

  • Clicking on a specific record will bring up the summary slider with details related to the specific custom module record. You can also add notes to the record here.
  • You can also choose to clone, delete, or forget this record.