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).
FieldTypeDescription
account_idIntegerUnique account ID
organisation_idIntegerOrganization ID
organisation_domainStringOrganization domain
account_domainStringAccount domain
app_idStringApplication ID
bundle_idIntegerBundle ID
bundle_typeStringBundle type
plan_typeStringPlan type
datacenterStringDatacenter region
Stream containing all Freshchat users (visitors and contacts). Supports incremental sync based on the updated_time field.
FieldTypeDescription
idStringUnique user ID
first_nameStringFirst name
last_nameStringLast name
emailStringEmail address
phoneStringPhone number
avatarStringAvatar URL
reference_idStringExternal reference ID
social_profilesStringSocial profiles (JSON)
propertiesStringUser properties (JSON)
created_timeDateTimeCreation timestamp
updated_timeDateTimeLast update timestamp
Stream containing all conversations, fetched per user from the /users/{user_id}/conversations endpoint. Supports incremental sync based on updated_time.
FieldTypeDescription
conversation_idStringUnique conversation ID
user_idStringUser who initiated the conversation
statusStringConversation status
app_idStringApplication ID
channel_idStringChannel/topic ID
assigned_agent_idStringAssigned agent ID
assigned_group_idStringAssigned group ID
messagesStringLatest messages summary (JSON)
agentsStringParticipating agents (JSON)
usersStringParticipating users (JSON)
propertiesStringConversation properties (JSON)
created_timeDateTimeCreation timestamp
updated_timeDateTimeLast update timestamp
Stream containing individual messages within conversations, fetched from the /conversations/{conversation_id}/messages endpoint. Supports incremental sync based on created_time.
FieldTypeDescription
idStringUnique message ID
conversation_idStringParent conversation ID
actor_typeStringSender type (user, agent, system)
actor_idStringSender ID
message_typeStringMessage type
message_partsStringMessage content parts (JSON)
reply_partsStringReply content parts (JSON)
meta_dataStringMessage metadata (JSON)
created_timeDateTimeCreation timestamp
Stream containing conversation property definitions and custom fields. Extracted as a full-table sync.
FieldTypeDescription
idStringUnique field ID
nameStringField name
labelStringDisplay label
typeStringField type
customBooleanWhether this is a custom field
editableBooleanWhether the field is editable
positionIntegerDisplay position
requiredBooleanWhether the field is required
choicesStringAvailable choices for dropdown fields (JSON)
Stream containing all Freshchat agents (support staff). Extracted as a full-table sync.
FieldTypeDescription
idStringUnique agent ID
first_nameStringFirst name
last_nameStringLast name
emailStringEmail address
avatarStringAvatar URL
biographyStringAgent biography
login_statusBooleanWhether the agent is logged in
availability_statusStringAvailability status
role_idStringAssigned role ID
is_deactivatedBooleanWhether the agent is deactivated
skill_idStringSkill ID
freshdesk_agent_idStringCorresponding Freshdesk agent ID
social_profilesStringSocial profiles (JSON)
groupsStringGroups the agent belongs to (JSON)
created_timeDateTimeCreation timestamp
updated_timeDateTimeLast update timestamp
Stream containing all Freshchat groups. Extracted as a full-table sync.
FieldTypeDescription
idStringUnique group ID
nameStringGroup name
descriptionStringGroup description
routing_typeStringRouting type
created_timeDateTimeCreation timestamp
updated_timeDateTimeLast update timestamp
Stream containing all Freshchat channels (topics). Extracted as a full-table sync.
FieldTypeDescription
idStringUnique channel ID
nameStringChannel name
enabledBooleanWhether the channel is enabled
publicBooleanWhether the channel is public
iconStringChannel icon
welcome_messageStringWelcome message
created_timeDateTimeCreation timestamp
updated_timeDateTimeLast update timestamp
Stream containing all Freshchat roles. Extracted as a full-table sync.
FieldTypeDescription
idStringUnique role ID
nameStringRole name
descriptionStringRole description
is_defaultBooleanWhether this is a default role
permissionsStringRole permissions (JSON)
created_timeDateTimeCreation timestamp
updated_timeDateTimeLast update timestamp
Stream containing outbound messages sent via WhatsApp and other channels. Extracted as a full-table sync.
FieldTypeDescription
idStringUnique message ID
statusStringDelivery status
channelStringChannel (e.g., whatsapp)
message_typeStringMessage type
message_partsStringMessage content parts (JSON)
recipientsStringMessage recipients (JSON)
metricsStringDelivery metrics (JSON)
created_timeDateTimeCreation timestamp
updated_timeDateTimeLast update timestamp

​
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.