Note: If you're unable to view this feature in your account, please note that we are rolling it out in batches to all our customers.

To offer a standard customer conversation experience, agents in Freshchat are equipped with the fundamental elements of a conversational engagement system, such as chat, contacts, and companies. These default objects form the core of any business and contain the basic information related to the issue (conversation) a particular customer (contact) mapped to an organization (company) is facing. This basic information often falls short of helping agents get the full context behind the ticket. And at scale, it becomes absolutely necessary to provide contextual support proactively.

With Freshchat, you can go the extra mile in customer engagement by gathering customer information specific to your business needs. This niche data can be saved using custom objects in Freshchat, enabling your agents with customer context. You can even link or associate custom objects with existing default objects to provide agents with a comprehensive and complete view of the issue raised by your customers.

Here are a few use cases where custom objects are useful, as compared to the default objects:

  1. "Contracts" for a property management business
    A property management company that leases homes and apartments must support tenants and landlords. One such custom object that will offer relevant information to agents is the latest rental contract information.

    With Custom Objects, the property management business can create a new data entity in Freshchat named "Contract". The "Contract" custom object can have defined attributes such as Contract ID, Renewal date, Property Type, and Name of Signee. Each tenant would be "associated" with a Contract in Freshchat. The contract details are available in Freshchat for the agent to process when a tenant raises a ticket, say, asking for their lease renewal date. Custom objects enable agents to access and update the contract information if necessary easily.

  1. "Stores" for a retail business
    Consider a high-tech security company that provides CCTV cameras and support to hundreds of grocery stores nationwide. When a store owner calls in to complain about a damaged camera, it would be useful for a support agent to know details about the store (Store code, location, or size) and the type of camera (Make, model, and type). This information helps the support agent dispatch the right technician for the job and avoids accessing different tools to capture all the missing pieces.

  1. "Cars" for a car rental company
    A car rental company keeps track of all cars rented by their customers. This includes details about the vehicle, such as the make, model, rental date, body type, and status. When a customer reaches out with a payment issue, the agent would have all the details handy to diagnose and resolve the customer’s payment related to the rental car.

Let us consider an example to understand how to use custom objects better. 

Let’s say you are an eCommerce company that sells furniture online. Customers can report problems with their orders/check their order status by raising a ticket, calling, or starting a chat with your support team. When a ticket (native object) is created, you can associate it with the corresponding order through its Order ID (custom object), so that agents can better understand which order the customer requires assistance with, without any back and forth.

Here’s a high-level overview of how this will work:

  • Create a custom object in Freshchat as Orders.

  • Create multiple fields within this object to hold order information, like Order ID, Furniture category, Payment status, etc.

  • Create/import object records that hold the actual order information.

  • Establish a relationship between the custom object "Orders" and the native object "Conversation". This will help agents associate tickets with the corresponding order.

  • Create and view reports to improve overall operations.

Let us now see how you can perform each action in detail.

Creating a Custom Object

Note: Only Admins have access to creating custom objects

In our example - the furniture business- we create the Custom Object "Orders"; each order will be represented as a custom object record. Every time a customer orders any furniture, you can add them as individual object records in your system. To simplify identifying the orders, you can define each order with attributes like Order ID, Category, Order status, Price, etc. 

  • Navigate to Admin >  Custom Objects > Create a custom object

  • Enter the Custom Object name (Orders, in this example) and a description

  • Choose a relevant icon from those displayed and click "Create"

  • Once you create the custom object, the relevant icon will appear on the sidebar for quick and easy access

Defining custom object fields

On the next page, you can start defining the object fields. These fields can represent the relevant order details, such as, Order ID, Delivery status, Furniture category, etc. 

The "Primary field" holds values that will uniquely identify each custom object record. It is an identifier that will only be associated with that particular order, similar to how a Ticket ID is only associated with one particular conversation. The primary field has the following characteristics:

  • It is similar to the concept of a primary key for a table in a database

  • It is of text field type

  • It cannot be deleted

  • It is marked as a unique identifier by default in Freshchat. This means

    •  No two records can have the same value in the primary field

    • It can be used as a record identifier in Search and Lookup functions

  • You can uncheck the ‘Accept unique value’ setting if you want to have more than one record with the same value in this field

  • The primary field can also be referred to as the unique identifier or Lookup field

Things to keep in mind when creating fields:

  • A maximum of only 100 fields can be created within an object.

    • Here are the limits for each field type within the custom object:

      • Number - 30

      • Checkbox - 30

      • Decimal - 20

      • Multi-select - 20

      • Date - 30

      • Text - 80

      • Dropdown - 30

      • Lookup relationship - 10

    • For example, you can create 80 text fields and 20 multi-select fields in an object, or 60 text fields, 30 number fields, and 10 check box fields in an object

  • A maximum of only 25 fields can be marked as filterable, excluding the Lookup field

  • A maximum of 5 Lookup fields can be created, and they are filterable by default

  • You can update the setting to filter records only when you create the field, it cannot be modified/edited later

This is how you can create the custom object fields for our use case:

  • Enter Label as Order ID, and click Add field. The primary field will get created. 

  • Create more fields based on your requirement. The following are the field types available to use:

    • Text 

    • Paragraph

    • Number

    • Decimal

    • Date

    • Dropdown

    • Checkbox

    • Multiselect 

    • Lookup relationship 

  • The fields above will have certain behavior associated with them, like

    • Required when submitting the form - check this box if you want to make this field mandatory

    • Accept unique values - Check this box if you want this field to only accept unique values. This setting will only be available for the Primary field

    • Use this field to filter records - Check this box if you want to filter records using this field

  • You can search for fields based on Field Labels using the Search box on the top right corner of the page

  • You can use the Customize widget button to decide what is displayed to agents in the custom widget on the Tickets page and any other related objects

Here’s how this will work for our considered use case:

Record name




Order ID



Primary field, unique identifier. Assigned by you to each order

Order status



Delivered/Not delivered

Furniture category



Living room furniture, Patio furniture, etc.

Furniture price




Furniture type 




The Order ID field is "Required" here because that is the field we’ll use to associate the orders with the relevant tickets that customers raise. You can also search for records using this field.

Translating custom object fields

Sometimes, your agents may be located in different countries and require the Custom Object names and field labels to be translated into their language. To do so, you can upload the custom object names, their descriptions, field labels, and the field names (including the lookup field label names) in the language chosen in your helpdesk settings. This way, you can provide more personalized support to your agents and customers worldwide. 

As an admin, you can:

  • Download or delete an existing language file 

  • Upload a new translations file

To enable translations:

  • Click on Settings > Account > Helpdesk Settings

  • Click on Manage Languages and add all the languages that you'd like the custom object fields to be displayed in

  • Now, click Manage translations in the Custom Objects edit page

  • A slider will be displayed with an option to download the YML file in the primary language 

  • Upload translations for the list of supported languages 

  • Export the current version of the .yml file in the selected language 

  • The .yml file will have the below fields (This is a sample .yml of Freshchat ticket fields)

    • Custom Object name

    • Custom Object Description

    • Field labels

    • Picklist values of the respective fields (for dropdown/multi-select field types) 

  • Add the labels and upload the .yml file (other formats are not allowed)

  • Click Confirm Upload, and agents with their profile set to this language can view the respective translated labels. 

If you have fields without a translation label in the .yml file, you should remove the tag <include translated label> for those fields. This will display the fields inthe default language.
For example: if "Country" is a field in a custom object, and you want to show "Country" as a label in all languages, then you should remove the tag <include translated label> against the Country field in the .yml file.

Create custom objects with APIs

You can get custom object schemas, create/update/delete/view records, and associate objects using Freshchat APIs. You can use Freshchat's marketplace platform to create custom apps to display the custom objects and associated entities in Freshchat. You can also create custom objects using an API. Learn more here.