Skip to main content
Freshchat is a modern messaging platform from Freshworks that enables businesses to engage with customers across web, mobile, and social channels. It provides live chat, chatbots, and messaging capabilities for sales, support, and customer engagement teams. This connector extracts your Freshchat data so you can analyze conversations, agent performance, and user engagement.

​
Configuring Freshchat as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Freshchat option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

You’ll need your Freshchat subdomain and API token to authenticate. Freshchat uses Bearer Token authentication.

​
Obtaining Your API Token

1

Log in to Freshchat

Sign in to your Freshchat account at https://{your-domain}.freshchat.com.
2

Navigate to API Tokens

Go to Admin > CONFIGURE > API Tokens.
3

Generate and copy the token

Click Generate Token and copy the value.
Store your API token securely. Treat it like a password and do not share it publicly.

​
Configuration Fields

The following configurations are available:
  • Freshchat Domain: Your Freshchat subdomain. For an account hosted at https://acme.freshchat.com, this value is acme.
  • API Key: The Bearer token generated from your Freshchat admin panel.
  • Start Date: The earliest date from which records will be synced for incremental streams (users, conversations).
Once you’re done, click Next.

​
2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table, and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster.
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data, which is good if you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data, which is good if you don’t want to have deleted data in your catalog.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. Chat data typically benefits from hourly or daily refreshes depending on your message volume. Optionally, you can determine when to execute an Additional Full Sync. This complements incremental extractions and ensures your data is fully synchronized every once in a while. Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Streams and Fields

Below you’ll find all available data streams from Freshchat and their corresponding fields:
Stream containing your Freshchat account configuration details. Extracted as a full-table sync (single record).
Stream containing all Freshchat users (visitors and contacts). Supports incremental sync based on the updated_time field.
Stream containing all conversations, fetched per user from the /users/{user_id}/conversations endpoint. Supports incremental sync based on updated_time.
Stream containing individual messages within conversations, fetched from the /conversations/{conversation_id}/messages endpoint. Supports incremental sync based on created_time.
Stream containing conversation property definitions and custom fields. Extracted as a full-table sync.
Stream containing all Freshchat agents (support staff). Extracted as a full-table sync.
Stream containing all Freshchat groups. Extracted as a full-table sync.
Stream containing all Freshchat channels (topics). Extracted as a full-table sync.
Stream containing all Freshchat roles. Extracted as a full-table sync.
Stream containing outbound messages sent via WhatsApp and other channels. Extracted as a full-table sync.

​
Data Model

The following diagram illustrates the relationships between the core data streams in Freshchat. The arrows indicate the join keys that link the different entities.

​
Implementation Notes

​
Data Sync Considerations

  • Incremental sync: Users and conversations support incremental sync based on updated_time. Conversation messages support incremental sync based on created_time. All other streams are extracted as full-table syncs.
  • Parent-child hierarchy: Conversations are nested under users, and messages are nested under conversations. This means syncing conversations will first iterate through all users, and syncing messages will iterate through all conversations.
  • Freshdesk integration: Agents have a freshdesk_agent_id field that maps to the corresponding agent in Freshdesk, enabling cross-product analysis.

​
API Limits and Performance

  • Rate limits: Freshchat enforces rate limits tracked via X-RateLimit-Limit and X-RateLimit-Remaining headers. The connector respects 429 responses automatically.
  • Pagination: List endpoints return up to 50 records per page by default.
  • Timestamps: All timestamps are returned in UTC (ISO 8601).

​
Skills for agents

Download Freshchat skills file

Freshchat connector documentation as plain markdown, for use in AI agent contexts.