Freshchat is a modern customer messaging platform built by Freshworks that enables businesses to engage with customers across multiple channels, including web chat, mobile apps, WhatsApp, Facebook Messenger, and more. It provides AI-powered chatbots, shared team inboxes, proactive messaging campaigns, in-depth conversation analytics, and seamless escalation to live agents — making it a comprehensive solution for customer support, sales, and marketing teams. The Freshchat REST API provides programmatic access to conversations, messages, contacts (users), agents, groups, and channels, enabling integration with external systems and automation of customer communication workflows.
Power end-to-end data operations for your Freshchat API with Nexla. Our bi-directional Freshchat connector is purpose-built for Freshchat, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Freshchat or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Freshchat workflows fast, secure, and fully governed.
Features
Type: API
SourceDestination
Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
Request optimization with intelligent batching, retry, and caching to minimize API calls and costs
Freshchat uses API token (Bearer) authentication for all API requests. Before creating a Freshchat credential in Nexla, you must generate an API token from your Freshchat account and note your account's subdomain.
Only a Freshchat account administrator can generate or regenerate API tokens. Note that Freshchat allows only one active API token at a time — generating a new token invalidates any previously issued token.
Sign in to your Freshchat account at https://{your-subdomain}.freshchat.com using administrator credentials.
Click the Admin Settings gear icon in the left sidebar to open the administration panel.
Navigate to Settings > Website Tracking and APIs (in some account versions, this appears as Configure > API Tokens).
Locate the API Token section. If a token has already been generated, it will be displayed here. To generate a new token, click Generate Token.
Important
Generating a new API token immediately invalidates any previously issued token. Existing integrations using the old token will stop working. Update all connected systems with the new token before proceeding.
Copy the token displayed in the Your API Key field. Store this value securely — it is equivalent to a password and grants full access to your Freshchat account data via the API.
The Freshchat REST API base URL is https://{account-subdomain}.freshchat.com/v2. Your account subdomain is the portion of your Freshchat URL before .freshchat.com.
For example, if your Freshchat account URL is https://acme.freshchat.com, your subdomain is acme.
After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.
Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.
Freshchat authenticates API requests using a Bearer token sent in the Authorization request header. Enter your Freshchat API token in the API Token field. This is the token generated in your Freshchat Admin Settings in Prerequisites; it will be transmitted as a Bearer token in the Authorization header of every API request Nexla makes to your Freshchat account.
Enter your Freshchat account subdomain in the Account Subdomain field (or Domain field, depending on your Nexla version). Enter only the subdomain portion — for example, acme if your Freshchat URL is https://acme.freshchat.com. Nexla uses this value to construct the API base URL https://{subdomain}.freshchat.com/v2 for all requests.
Do not include the protocol (https://) or the .freshchat.com domain suffix in the subdomain field. Enter only the subdomain identifier, such as acme or mycompany.
Important
Keep your API token secure and never share it publicly. The Freshchat API token grants access to all conversation, contact, and agent data in your account. Treat it with the same care as a password.
Click the Save button at the bottom of the overlay to save the configured credential. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.
To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Freshchat connector tile, 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.
Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Freshchat endpoints. 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.
Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.
Freshchat sources can also be manually configured to ingest data from any valid Freshchat API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.
All Freshchat v2 API endpoint URLs are rooted at https://{subdomain}.freshchat.com/v2 (for example, https://acme.freshchat.com/v2/conversations). Common endpoints include /conversations, /conversations/{'{conversation_id}'}/messages, /users, /agents, /groups, and /channels.
Freshchat responses wrap result arrays in a named property rather than returning a bare array, so the path to data must be set explicitly — for example, $.conversations[*] for the conversations endpoint, $.users[*] for contacts, $.agents[*] for agents, and $.messages[*] for conversation messages. Freshchat responses also include pagination metadata (total_pages, total_items, page, items_per_page) alongside the data array, which can be preserved with each record by setting the metadata path to the top-level response object.
Date/time macros such as {'{now-1}'} are useful for filtering conversations or users by their creation or update timestamps on each run, and lookup-based macros can be used to chain calls — for example, supplying conversation IDs retrieved from the List Conversations endpoint as a macro when fetching messages for each conversation. The Authorization header carrying the Bearer token is set automatically from your Freshchat credential and does not need to be added manually.
Once all of the relevant settings have been configured, 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.
Click the + icon on the Nexset that will be sent to the Freshchat destination, and select the Send to Destination option from the menu. Select the Freshchat connector from the list of available destination connectors, then select the credential that will be used to connect to the Freshchat organization, and click Next; or, create a new Freshchat credential for use in this flow.
Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Freshchat endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.
Create Conversation
Creates a new conversation with bulk messages in the Freshchat account. Use this endpoint to programmatically open conversations on behalf of users, such as for outbound messaging campaigns or automated support initiation.
Sends a POST request to the Freshchat conversations endpoint; the request body must include the channel ID, user details, and initial message content.
Returns the newly created conversation object in the response, including the system-assigned conversation ID. Enable the Response Webhook to capture this ID for downstream flows.
The user referenced in the request must exist in Freshchat as an end-user. Use the Create a New End-User endpoint to create the user first if needed. The channel ID must correspond to a valid Freshchat channel (inbox).
Update Conversation
Updates an existing conversation's status, assigned agent, or assigned group. Use this endpoint to automate conversation routing, resolution, or reassignment based on data from other systems.
Sends a PATCH request to the Freshchat conversation endpoint for the specified conversation; only the fields included in the request body are updated.
Supported update fields include status (e.g., resolved, assigned), assigned agent ID, and assigned group ID.
Configure the following parameter: Conversation ID — the ID of the Freshchat conversation to update.
Use the List Conversations source endpoint to obtain the conversation IDs needed for updates. Resolving a conversation changes its status to resolved and removes it from the active queue.
Send Message
Sends a reply message to an existing Freshchat conversation. Use this endpoint to deliver automated agent replies, notifications, or follow-up messages to ongoing conversations.
Sends a POST request to the Freshchat messages endpoint for the specified conversation; the request body must include the actor type (agent or user), actor ID, and message parts (text content).
Returns the created message object in the response, including the message ID and timestamp.
Configure the following parameter: Conversation ID — the ID of the Freshchat conversation to which the message should be sent.
Messages sent via this endpoint appear in the Freshchat conversation thread. The actor ID must correspond to a valid agent or user in the Freshchat account. Sending as an agent requires the agent ID; sending as a user requires the user ID.
Update Agent
Updates an agent's properties such as availability status and group assignments. Use this endpoint to synchronize agent availability or group membership changes from workforce management systems into Freshchat.
Sends a PUT request to the Freshchat agent endpoint for the specified agent; only the fields included in the request body are updated.
Supported update fields include availability status and group assignments.
Configure the following parameter: Agent ID — the ID of the Freshchat agent to update.
Use the List Agents source endpoint to obtain valid agent IDs. Availability status changes take effect immediately and affect conversation routing in Freshchat.
Create a New End-User
Creates a new end-user (contact) in the Freshchat account. Use this endpoint to synchronize customer records from CRM systems or other contact data sources into Freshchat.
Sends a POST request to the Freshchat users endpoint; the request body should include the user's name and at least one contact identifier such as email or phone.
Returns the newly created user object in the response, including the system-assigned user ID. Enable the Response Webhook to capture this ID for use when creating conversations for this user.
Freshchat will return an error if a user with the same email address already exists. Consider using a deduplication step in Nexla before sending records to this endpoint to avoid duplicate user creation.
Freshchat destinations can also be manually configured to send data to any valid Freshchat API endpoint, including configuring Nexla to automatically send the response received after each call to a new Nexla webhook data source — useful for capturing system-assigned IDs such as new conversation or contact IDs. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.
The Freshchat API accepts and returns JSON only, so select JSON as the content format for all Freshchat destinations. Common write endpoints include POST /v2/users (create a contact), PUT /v2/users/{'{user_id}'} (update a contact), POST /v2/conversations (create a conversation), POST /v2/conversations/{'{conversation_id}'}/messages (send a message), and PATCH /v2/conversations/{'{conversation_id}'} (update a conversation) — all rooted at https://{subdomain}.freshchat.com/v2.
The Authorization header carrying the Bearer token and the Content-Type: application/json header are both set automatically from your Freshchat credential and content format selection, so they do not need to be added as custom request headers.
Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Freshchat endpoint, open the destination resource menu, and select Activate.
The Nexset data will not be sent to the Freshchat endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.
