Freshchat Data Source

The Freshchat connector enables you to ingest customer messaging data — including conversations, messages, contacts, agents, groups, and channels — from your Freshchat account. Follow the instructions below to create a new data flow that ingests data from a Freshchat source in Nexla.

Freshchat

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Freshchat connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Freshchat instance, and click Next; or, create a new Freshchat credential for use in this flow.

3. In Nexla, Freshchat data sources can be created using pre-built endpoint templates, which expedite source setup for common Freshchat endpoints. Each template is designed specifically for the corresponding Freshchat endpoint, making data source setup easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Freshchat sources can also be configured manually, allowing you to ingest data from Freshchat endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Freshchat endpoints. Each template is designed specifically for the corresponding Freshchat endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

  Get Account Configuration

  Retrieves the account configuration and settings for the Freshchat instance. Use this endpoint to pull account-level settings such as timezone, language, and feature configurations for auditing or integration purposes.

  • Sends a GET request to /v2/accounts/configuration; returns the full account configuration object at $.
  • The response is a single object — not an array — containing all account-level configuration fields.

  This endpoint requires a valid Freshchat API token with account-level read permissions. The base URL is configured in your Freshchat credential and follows the pattern https://<your-domain>.freshchat.com.

  List Users

  Returns a paginated list of all end-users (contacts) in the Freshchat account. Use this endpoint to retrieve customer contact records for CRM synchronization or user analytics.

  • Sends a GET request to /v2/users; returns user records as an array at $.users[*].
  • Each record includes the user's ID, name, email, phone, and any custom properties configured on the Freshchat account.

  Results are paginated — use the pagination cursor or page parameters returned in the response to retrieve subsequent pages. User IDs from this endpoint can be used with the List User Conversations endpoint to fetch conversations for specific users.

  List User Conversations

  Returns a list of conversations for a specific user in Freshchat. Use this endpoint to retrieve all conversation history for a given customer contact.

  • Sends a GET request to /v2/users/{user_id}/conversations; returns conversation records as an array at $.conversations[*].
  • Each record includes the conversation ID, status, assigned agent and group, channel, and timestamps.
  • Configure the following parameter: User ID — the Freshchat user ID for the contact whose conversations should be retrieved.

  Use the List Users endpoint first to obtain the user IDs needed for this endpoint. Consider using a Nexla lookup macro to dynamically supply user IDs from a List Users source when ingesting conversations at scale.

  Get Conversation

  Retrieves the full details of a specific conversation by its ID. Use this endpoint to pull complete conversation metadata including status, assigned agent, group, and channel.

  • Sends a GET request to /v2/conversations/{conversation_id}; returns the conversation object at $.
  • The response is a single conversation object containing all conversation-level metadata fields.
  • Configure the following parameter: Conversation ID — the ID of the Freshchat conversation to retrieve.

  Use the List Conversations endpoint to obtain conversation IDs. For bulk retrieval, consider using a Nexla lookup macro to dynamically supply conversation IDs.

  List Conversation Messages

  Returns all messages in a specific Freshchat conversation. Use this endpoint to retrieve the full message thread for a conversation, including agent and customer messages.

  • Sends a GET request to /v2/conversations/{conversation_id}/messages; returns message records as an array at $.messages[*].
  • Each record includes the message actor type (agent or user), message parts (text, attachments), and timestamps.
  • Configure the following parameter: Conversation ID — the ID of the Freshchat conversation whose messages should be retrieved.

  Messages are returned in chronological order. For large conversation threads, results may be paginated. Use the List Conversations endpoint to obtain the conversation IDs needed for this endpoint.

  List Conversation Fields

  Returns a list of custom fields available for conversations in the Freshchat account. Use this endpoint to discover and document the custom conversation properties configured for your Freshchat instance.

  • Sends a GET request to /v2/conversations/fields; returns custom field definitions as an array at $.fields[*].
  • Each record includes the field name, label, type, and whether the field is required.

  Custom conversation fields are account-specific. Use this endpoint to map field names and types before ingesting conversation data that includes custom property values.

  List Agents

  Returns a list of all agents in the Freshchat account. Use this endpoint to retrieve agent profiles for reporting, workforce management, or synchronization with other systems.

  • Sends a GET request to /v2/agents; returns agent records as an array at $.agents[*].
  • Each record includes the agent ID, name, email, availability status, and group assignments.

  Agent IDs from this endpoint can be used to filter the List Conversations endpoint by assigned agent using the assigned_agent_id parameter.

  List Groups

  Returns a list of all agent groups in the Freshchat account. Use this endpoint to retrieve group configurations for routing analysis or synchronization with workforce management tools.

  • Sends a GET request to /v2/groups; returns group records as an array at $.groups[*].
  • Each record includes the group ID, name, description, and associated agent IDs.

  Group IDs can be used to filter the List Conversations endpoint by assigned group using the assigned_group_id parameter.

  List Channels

  Returns a list of all channels (topics/inboxes) configured in the Freshchat account. Use this endpoint to retrieve channel configuration data for routing analysis or intake reporting.

  • Sends a GET request to /v2/channels; returns channel records as an array at $.channels[*].
  • Each record includes the channel ID, name, type, and associated group.

  Channel IDs can be used to filter the List Conversations endpoint by channel using the channel_id parameter.

  List Roles

  Returns a list of all roles available in the Freshchat account. Use this endpoint to retrieve role definitions for access management auditing or agent profile enrichment.

  • Sends a GET request to /v2/roles; returns role records as an array at $.roles[*].
  • Each record includes the role ID, name, and associated permissions.

  Roles define what actions agents can perform in Freshchat. Use this endpoint alongside the List Agents endpoint to build a complete picture of agent permissions.

  List Conversations

  Returns a paginated list of all conversations in the Freshchat account, with optional filtering by agent, group, status, and channel. Use this endpoint as the primary source for conversation-level analytics and reporting.

  • Sends a GET request to /v2/conversations with optional filter query parameters; returns conversation records as an array at $.conversations[*].
  • Each record includes the conversation ID, status, assigned agent and group, channel, creation time, and last update time.
  • Configure the following optional parameters: Assigned Agent ID — filter by the ID of the assigned agent. Assigned Group ID — filter by the ID of the assigned group. Conversation Status — filter by status (e.g., assigned, resolved, new). Channel ID — filter by the channel (inbox) through which the conversation was initiated.

  Results are paginated. For large accounts, use the pagination parameters returned in the response to retrieve all pages. Combine filter parameters to narrow results — for example, retrieve only unresolved conversations assigned to a specific group.

  Get Agent

  Retrieves metadata for a specific agent by agent ID. Use this endpoint to fetch detailed profile information for a single agent, including availability and group assignments.

  • Sends a GET request to /v2/agents/{agent_id}; returns the agent object at $.
  • The response includes the agent's ID, name, email, availability status, role, and group memberships.
  • Configure the following parameter: Agent ID — the Freshchat agent ID for the agent to retrieve.

  Use the List Agents endpoint to obtain valid agent IDs. This endpoint returns data for a single agent per request.

  Get End-User Details

  Retrieves detailed information for a specific end-user (contact) by user ID. Use this endpoint to fetch a single user's full profile, including custom properties and contact information.

  • Sends a GET request to /v2/users/{user_id}; returns the user object at $.
  • The response includes the user's ID, name, email, phone, and all custom user properties configured for the account.
  • Configure the following parameter: User ID — the Freshchat user ID for the end-user to retrieve.

  Use the List Users endpoint to obtain valid user IDs. Consider using a Nexla lookup macro to dynamically supply user IDs for bulk retrieval of individual user profiles.

  Get Agent Group Details

  Retrieves detailed information for a specific agent group by group ID. Use this endpoint to fetch the full configuration of a single group, including its name, description, and member agents.

  • Sends a GET request to /v2/groups/{group_id}; returns the group object at $.
  • The response includes the group ID, name, description, and list of agent IDs belonging to the group.
  • Configure the following parameter: Group ID — the Freshchat group ID for the agent group to retrieve.

  Use the List Groups endpoint to obtain valid group IDs.

  Get Channel Details

  Retrieves detailed information for a specific channel (inbox/topic) by channel ID. Use this endpoint to fetch the full configuration of a single Freshchat channel.

  • Sends a GET request to /v2/channels/{channel_id}; returns the channel object at $.
  • The response includes the channel ID, name, type, welcome message, and associated group.
  • Configure the following parameter: Channel ID — the Freshchat channel ID for the channel to retrieve.

  Use the List Channels endpoint to obtain valid channel IDs.

  Create Raw Report

  Initiates the creation of a raw CSV export report for conversations over a specified time range. Use this endpoint as the first step in a two-step reporting workflow — after submission, poll the Get Raw Report Status endpoint to retrieve the download link when the report is ready.

  • Sends a POST request to /v2/reports/raw; returns the report job object at $, including the report ID needed for status polling.
  • The request body must include the report time range parameters specifying the start and end dates for the conversation data to be exported.

  Raw reports are generated asynchronously — the report will not be immediately available after this request. Use the Get Raw Report Status endpoint with the returned report ID to check generation status and retrieve the CSV download URL once complete. Use Nexla date/time macros in the request body to define rolling report time windows.

  Get Raw Report Status

  Retrieves the status and CSV download link for a previously created raw report job. Use this endpoint to poll the status of a report initiated via the Create Raw Report endpoint and obtain the download URL when the report has finished generating.

  • Sends a GET request to /v2/reports/raw/{report_id}; returns the report status object at $.
  • When complete, the response includes the report generation status and a URL for downloading the CSV file.
  • Configure the following parameter: Report ID — the report job ID returned by the Create Raw Report endpoint.

  Poll this endpoint after using Create Raw Report. The report status transitions from pending to completed once the CSV is ready. The download URL in the response is time-limited — retrieve the file promptly after the status shows completion.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Freshchat sources can also be configured manually, allowing you to ingest data from any valid Freshchat API endpoint. Configuration options available for Freshchat sources allow them to be fully customized to suit any use case — including using chained API calls to fetch data from multiple endpoints or sources that require custom authentication headers or request parameters.

First, select the method that will be used for calls to the Freshchat API from the Method pulldown menu. The most common methods for Freshchat data retrieval are:

• GET: For retrieving conversations, messages, contacts (users), agents, groups, and channels
• POST: For triggering searches or creating resources when required by the Freshchat API

API Endpoint URL

4. Enter the URL of the Freshchat API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters.

   Common Freshchat v2 API endpoint patterns include:

   • Conversations: https://{subdomain}.freshchat.com/v2/conversations — retrieves a paginated list of conversations
   • Messages in a conversation: https://{subdomain}.freshchat.com/v2/conversations/{'{conversation_id}'}/messages — retrieves messages within a specific conversation
   • Contacts (Users): https://{subdomain}.freshchat.com/v2/users — retrieves a paginated list of contacts
   • Agents: https://{subdomain}.freshchat.com/v2/agents — retrieves all agents configured in your Freshchat account
   • Groups: https://{subdomain}.freshchat.com/v2/groups — retrieves all agent groups
   • Channels: https://{subdomain}.freshchat.com/v2/channels — retrieves all configured channels (topics)

   Replace {subdomain} with your Freshchat account subdomain (e.g., acme).

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL. For a complete list of available Freshchat API endpoints and their parameters, refer to the Freshchat API documentation.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros — all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements. This is particularly useful for Freshchat endpoints that support date filtering, such as filtering conversations by their creation or update timestamps.

Macros are particularly useful for APIs that require date ranges, pagination parameters, or other dynamic values that change between data ingestion runs.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime
   • {now-1} – The datetime one time unit before the current datetime
   • {now+1} – The datetime one time unit after the current datetime
   • custom – Datetime macros can reference any number of time units before or after the current datetime — for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro — i.e., the value of {now} in {now-1}.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu — for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data. For Freshchat, this is particularly useful for chaining API calls — for example, using conversation IDs fetched from the Conversations endpoint as parameters when retrieving messages for each conversation.

Lookup-based macros are useful when you need to create API endpoints that reference specific IDs, values, or parameters from other data sources in your Nexla environment.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data returned by the API endpoint is needed, you can designate the part of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

Freshchat API responses typically wrap data arrays in a named property. For example, the GET /v2/conversations endpoint returns a JSON object with a conversations array, while GET /v2/users returns an object with a users array. Without specifying the path to this array, Nexla will treat the entire response object as a single record rather than producing one record per conversation or user.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.data.items[*] to access an array of items within a data object).

  • For responses in XML format, enter the XPath that points to the object/array containing relevant data. XPath uses slash notation (e.g., /response/data/item to access item elements within a data element).

  Path to Data Examples for Freshchat:

  • For GET /v2/conversations — enter $.conversations[*] to treat each conversation as a record.
  • For GET /v2/users — enter $.users[*] to treat each contact as a record.
  • For GET /v2/agents — enter $.agents[*] to treat each agent as a record.
  • For GET /v2/conversations/{'{conversation_id}'}/messages — enter $.messages[*] to treat each message as a record.

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. Freshchat API responses typically include pagination metadata alongside the data array — for example, total_pages, total_items, page, and items_per_page fields at the top level. Specifying a metadata path allows you to preserve this pagination context with each record.

Metadata paths are particularly useful for preserving API response context like request IDs, timestamps, or summary statistics that apply to all records in the response.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata, and for responses in XML format, enter the XPath.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers may be required for API versioning, content type specifications, or custom requirements.

  You do not need to include the Authorization header here — it is automatically set by Nexla using the API token from your Freshchat credential. Common headers like Authorization, Content-Type, and Accept are typically handled automatically by Nexla based on your credential configuration.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Freshchat data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.