> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Freshchat as a data source

> Bring data from Freshchat to Nekt.

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.

<img height="50" src="https://mintlify.s3.us-west-1.amazonaws.com/nekt/assets/logo/logo-freshchat.png" />

## Configuring Freshchat as a Source

In the [Sources](https://app.nekt.ai/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

<Steps>
  <Step title="Log in to Freshchat">
    Sign in to your Freshchat account at `https://{your-domain}.freshchat.com`.
  </Step>

  <Step title="Navigate to API Tokens">
    Go to **Admin** > **CONFIGURE** > **API Tokens**.
  </Step>

  <Step title="Generate and copy the token">
    Click **Generate Token** and copy the value.

    <Warning>Store your API token securely. Treat it like a password and do not share it publicly.</Warning>
  </Step>
</Steps>

#### 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](https://docs.nekt.com/runs/scheduling-and-triggers), 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](https://docs.nekt.com/get-started/core-concepts/types-of-sync#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](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

# Streams and Fields

Below you'll find all available data streams from Freshchat and their corresponding fields:

<AccordionGroup>
  <Accordion title="Accounts">
    Stream containing your Freshchat account configuration details. Extracted as a full-table sync (single record).

    | Field                 | Type    | Description         |
    | :-------------------- | :------ | :------------------ |
    | `account_id`          | Integer | Unique account ID   |
    | `organisation_id`     | Integer | Organization ID     |
    | `organisation_domain` | String  | Organization domain |
    | `account_domain`      | String  | Account domain      |
    | `app_id`              | String  | Application ID      |
    | `bundle_id`           | Integer | Bundle ID           |
    | `bundle_type`         | String  | Bundle type         |
    | `plan_type`           | String  | Plan type           |
    | `datacenter`          | String  | Datacenter region   |
  </Accordion>

  <Accordion title="Users">
    Stream containing all Freshchat users (visitors and contacts). Supports **incremental sync** based on the `updated_time` field.

    | Field             | Type     | Description            |
    | :---------------- | :------- | :--------------------- |
    | `id`              | String   | Unique user ID         |
    | `first_name`      | String   | First name             |
    | `last_name`       | String   | Last name              |
    | `email`           | String   | Email address          |
    | `phone`           | String   | Phone number           |
    | `avatar`          | String   | Avatar URL             |
    | `reference_id`    | String   | External reference ID  |
    | `social_profiles` | String   | Social profiles (JSON) |
    | `properties`      | String   | User properties (JSON) |
    | `created_time`    | DateTime | Creation timestamp     |
    | `updated_time`    | DateTime | Last update timestamp  |
  </Accordion>

  <Accordion title="Conversations">
    Stream containing all conversations, fetched per user from the `/users/{user_id}/conversations` endpoint. Supports **incremental sync** based on `updated_time`.

    | Field               | Type     | Description                         |
    | :------------------ | :------- | :---------------------------------- |
    | `conversation_id`   | String   | Unique conversation ID              |
    | `user_id`           | String   | User who initiated the conversation |
    | `status`            | String   | Conversation status                 |
    | `app_id`            | String   | Application ID                      |
    | `channel_id`        | String   | Channel/topic ID                    |
    | `assigned_agent_id` | String   | Assigned agent ID                   |
    | `assigned_group_id` | String   | Assigned group ID                   |
    | `messages`          | String   | Latest messages summary (JSON)      |
    | `agents`            | String   | Participating agents (JSON)         |
    | `users`             | String   | Participating users (JSON)          |
    | `properties`        | String   | Conversation properties (JSON)      |
    | `created_time`      | DateTime | Creation timestamp                  |
    | `updated_time`      | DateTime | Last update timestamp               |
  </Accordion>

  <Accordion title="Conversation Messages">
    Stream containing individual messages within conversations, fetched from the `/conversations/{conversation_id}/messages` endpoint. Supports **incremental sync** based on `created_time`.

    | Field             | Type     | Description                       |
    | :---------------- | :------- | :-------------------------------- |
    | `id`              | String   | Unique message ID                 |
    | `conversation_id` | String   | Parent conversation ID            |
    | `actor_type`      | String   | Sender type (user, agent, system) |
    | `actor_id`        | String   | Sender ID                         |
    | `message_type`    | String   | Message type                      |
    | `message_parts`   | String   | Message content parts (JSON)      |
    | `reply_parts`     | String   | Reply content parts (JSON)        |
    | `meta_data`       | String   | Message metadata (JSON)           |
    | `created_time`    | DateTime | Creation timestamp                |
  </Accordion>

  <Accordion title="Conversation Fields">
    Stream containing conversation property definitions and custom fields. Extracted as a full-table sync.

    | Field      | Type    | Description                                  |
    | :--------- | :------ | :------------------------------------------- |
    | `id`       | String  | Unique field ID                              |
    | `name`     | String  | Field name                                   |
    | `label`    | String  | Display label                                |
    | `type`     | String  | Field type                                   |
    | `custom`   | Boolean | Whether this is a custom field               |
    | `editable` | Boolean | Whether the field is editable                |
    | `position` | Integer | Display position                             |
    | `required` | Boolean | Whether the field is required                |
    | `choices`  | String  | Available choices for dropdown fields (JSON) |
  </Accordion>

  <Accordion title="Agents">
    Stream containing all Freshchat agents (support staff). Extracted as a full-table sync.

    | Field                 | Type     | Description                        |
    | :-------------------- | :------- | :--------------------------------- |
    | `id`                  | String   | Unique agent ID                    |
    | `first_name`          | String   | First name                         |
    | `last_name`           | String   | Last name                          |
    | `email`               | String   | Email address                      |
    | `avatar`              | String   | Avatar URL                         |
    | `biography`           | String   | Agent biography                    |
    | `login_status`        | Boolean  | Whether the agent is logged in     |
    | `availability_status` | String   | Availability status                |
    | `role_id`             | String   | Assigned role ID                   |
    | `is_deactivated`      | Boolean  | Whether the agent is deactivated   |
    | `skill_id`            | String   | Skill ID                           |
    | `freshdesk_agent_id`  | String   | Corresponding Freshdesk agent ID   |
    | `social_profiles`     | String   | Social profiles (JSON)             |
    | `groups`              | String   | Groups the agent belongs to (JSON) |
    | `created_time`        | DateTime | Creation timestamp                 |
    | `updated_time`        | DateTime | Last update timestamp              |
  </Accordion>

  <Accordion title="Groups">
    Stream containing all Freshchat groups. Extracted as a full-table sync.

    | Field          | Type     | Description           |
    | :------------- | :------- | :-------------------- |
    | `id`           | String   | Unique group ID       |
    | `name`         | String   | Group name            |
    | `description`  | String   | Group description     |
    | `routing_type` | String   | Routing type          |
    | `created_time` | DateTime | Creation timestamp    |
    | `updated_time` | DateTime | Last update timestamp |
  </Accordion>

  <Accordion title="Channels">
    Stream containing all Freshchat channels (topics). Extracted as a full-table sync.

    | Field             | Type     | Description                    |
    | :---------------- | :------- | :----------------------------- |
    | `id`              | String   | Unique channel ID              |
    | `name`            | String   | Channel name                   |
    | `enabled`         | Boolean  | Whether the channel is enabled |
    | `public`          | Boolean  | Whether the channel is public  |
    | `icon`            | String   | Channel icon                   |
    | `welcome_message` | String   | Welcome message                |
    | `created_time`    | DateTime | Creation timestamp             |
    | `updated_time`    | DateTime | Last update timestamp          |
  </Accordion>

  <Accordion title="Roles">
    Stream containing all Freshchat roles. Extracted as a full-table sync.

    | Field          | Type     | Description                    |
    | :------------- | :------- | :----------------------------- |
    | `id`           | String   | Unique role ID                 |
    | `name`         | String   | Role name                      |
    | `description`  | String   | Role description               |
    | `is_default`   | Boolean  | Whether this is a default role |
    | `permissions`  | String   | Role permissions (JSON)        |
    | `created_time` | DateTime | Creation timestamp             |
    | `updated_time` | DateTime | Last update timestamp          |
  </Accordion>

  <Accordion title="Outbound Messages">
    Stream containing outbound messages sent via WhatsApp and other channels. Extracted as a full-table sync.

    | Field           | Type     | Description                  |
    | :-------------- | :------- | :--------------------------- |
    | `id`            | String   | Unique message ID            |
    | `status`        | String   | Delivery status              |
    | `channel`       | String   | Channel (e.g., whatsapp)     |
    | `message_type`  | String   | Message type                 |
    | `message_parts` | String   | Message content parts (JSON) |
    | `recipients`    | String   | Message recipients (JSON)    |
    | `metrics`       | String   | Delivery metrics (JSON)      |
    | `created_time`  | DateTime | Creation timestamp           |
    | `updated_time`  | DateTime | Last update timestamp        |
  </Accordion>
</AccordionGroup>

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

```mermaid theme={null}
erDiagram
    Users ||--o{ Conversations : "user_id"
    Conversations ||--o{ ConversationMessages : "conversation_id"
    Conversations }o--o| Agents : "assigned_agent_id"
    Conversations }o--o| Groups : "assigned_group_id"
    Conversations }o--o| Channels : "channel_id"
    Agents }o--o| Roles : "role_id"
    Users {
        string id PK
        string email
        string first_name
        datetime updated_time
    }
    Conversations {
        string conversation_id PK
        string user_id FK
        string assigned_agent_id FK
        string assigned_group_id FK
        string channel_id FK
        string status
        datetime updated_time
    }
    ConversationMessages {
        string id PK
        string conversation_id FK
        string actor_type
        string actor_id
        datetime created_time
    }
    Agents {
        string id PK
        string email
        string role_id FK
        boolean is_deactivated
    }
    Groups {
        string id PK
        string name
    }
    Channels {
        string id PK
        string name
    }
    Roles {
        string id PK
        string name
    }
```

## 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

<Snippet file="agent-skills-intro.mdx" />

<Card title="Download Freshchat skills file" icon="wand-magic-sparkles" href="/sources/freshchat.md">
  Freshchat connector documentation as plain markdown, for use in AI agent contexts.
</Card>