feat(data-imports): add Freshdesk migration (1/3) (#15261)

## Description

Adds Freshdesk as an integration import source so administrators can
validate a Freshdesk domain and API key, then import contacts, tickets,
public replies, customer replies, and private notes while tracking
progress from Data Imports.

The integration has now been validated against a live Freshdesk trial
tenant with contacts, Web Chat and phone tickets, public replies,
customer replies, a private note, pagination, requester expansion, and
attachment metadata. That validation found and fixed the current Web
Chat source mapping and prevented the ticket description from
duplicating the initial Web Chat message.

Related: #15116

## Closes

Closes
[CW-7639](https://linear.app/chatwoot/issue/CW-7639/freshdesk-freshworks-migration)

## Type of change

- [x] New feature (non-breaking change which adds functionality)

## What changed

- Added a shared source adapter, importer, job, retry, restart,
creation, and placeholder inbox contract used by Intercom and Freshdesk.
- Added Freshdesk API authentication, contact and ticket pagination,
requester expansion, conversation retrieval, normalization, channel
grouping, and error handling.
- Added current Freshdesk source identifiers through SMS, including Web
Chat source `15`, and grouped equivalent sources into placeholder
inboxes.
- Used Web Chat conversation events as the complete message history so
the generated ticket description does not duplicate the initial customer
message.
- Preserved Freshdesk ticket subjects in source metadata and added a
sanitized live-derived Web Chat fixture with structured bodies and
attachment metadata.
- Added Freshdesk selection, domain and API key validation, and
provider-neutral import status handling in the Data Imports UI.

## How to test

1. Enable the data_import feature for an account and open Settings >
Data > New import.
2. Select Freshdesk and enter a Freshdesk domain and API key.
3. Select contacts and/or conversations, validate the credentials, and
start the import.
4. Confirm progress is displayed and imported tickets appear as resolved
conversations in Freshdesk placeholder inboxes with public replies and
private notes preserved.
5. Verify Web Chat tickets appear in the Chat placeholder inbox and the
initial customer message is imported once.
6. Verify an abandoned import can be restarted and a stalled import can
be retried.

## Current scope

- **Product decision:** Attachment binaries are intentionally not
imported in the current migration scope. Attachment metadata is
preserved and messages include a skipped-attachment marker.
- Adaptive Retry-After scheduling and handling the 30,000-ticket listing
ceiling are covered by stacked follow-up PRs.

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules

app/javascript/dashboard/i18n/locale/en/settings.json

@@ -421,6 +421,10 @@
     "DESCRIPTION": "Bring your existing contacts and past conversations into this account from another support tool. Each import runs in the background, so you can keep working while it finishes, track its progress, and review anything that was skipped along the way.",
     "LOADING": "Fetching imports",
     "DEFAULT_IMPORT_NAME": "Intercom import",
+    "DEFAULT_IMPORT_NAMES": {
+      "INTERCOM": "Intercom import",
+      "FRESHDESK": "Freshdesk import"
+    },
     "TABS": {
       "IMPORT": "Import",
       "EXPORT": "Export"
@@ -434,9 +438,15 @@
       "TITLE": "New import",
       "SOURCE": "Source",
       "NAME": "Import name",
-      "NAME_PLACEHOLDER": "July Intercom migration",
+      "NAME_PLACEHOLDER": "July support migration",
       "ACCESS_KEY": "Intercom access key",
       "ACCESS_KEY_PLACEHOLDER": "Paste your Intercom access key",
+      "INTERCOM_ACCESS_KEY": "Intercom access key",
+      "INTERCOM_ACCESS_KEY_PLACEHOLDER": "Paste your Intercom access key",
+      "FRESHDESK_API_KEY": "Freshdesk API key",
+      "FRESHDESK_API_KEY_PLACEHOLDER": "Paste your Freshdesk API key",
+      "FRESHDESK_DOMAIN": "Freshdesk domain",
+      "FRESHDESK_DOMAIN_PLACEHOLDER": "acme.freshdesk.com",
       "DATA_TYPES": "Data to import",
       "VALIDATING": "Validating access key...",
       "VALID_KEY": "Access key validated.",
@@ -510,11 +520,11 @@
       }
     },
     "ALERTS": {
-      "IMPORT_STARTED": "Intercom import has started.",
-      "IMPORT_RETRIED": "Intercom import has been queued to resume.",
-      "IMPORT_RETRY_FAILED": "Could not retry the Intercom import.",
-      "IMPORT_ABANDONED": "Intercom import has been abandoned.",
-      "IMPORT_FAILED": "Could not start the Intercom import."
+      "IMPORT_STARTED": "Import has started.",
+      "IMPORT_RETRIED": "Import has been queued to resume.",
+      "IMPORT_RETRY_FAILED": "Could not retry the import.",
+      "IMPORT_ABANDONED": "Import has been abandoned.",
+      "IMPORT_FAILED": "Could not start the import."
     }
   },
   "CAPTAIN_SETTINGS": {

app/javascript/dashboard/routes/dashboard/settings/data/Index.vue

@@ -24,7 +24,7 @@ import {
   formatStatus,
   importedCount,
   isActiveImport,
-  isActiveIntercomImport,
+  isActiveIntegrationImport,
   statusDotClass,
 } from './importStatus';
 
@@ -53,8 +53,8 @@ const activeTabIndex = computed(() =>
 );
 
 const hasActiveImport = computed(() => dataImports.value.some(isActiveImport));
-const hasActiveIntercomImport = computed(() =>
-  dataImports.value.some(isActiveIntercomImport)
+const hasActiveIntegrationImport = computed(() =>
+  dataImports.value.some(isActiveIntegrationImport)
 );
 
 const dataImportRoute = dataImport => ({
@@ -137,7 +137,7 @@ const openImport = dataImport => {
 };
 
 const openImportDrawer = () => {
-  if (!hasActiveIntercomImport.value) showImportDrawer.value = true;
+  if (!hasActiveIntegrationImport.value) showImportDrawer.value = true;
 };
 
 const onImportCreated = dataImportId => {
@@ -227,9 +227,9 @@ onBeforeUnmount(() => {
           <Button
             size="sm"
             :label="$t('DATA_IMPORTS.TABLE.NEW_IMPORT')"
-            :disabled="hasActiveIntercomImport"
+            :disabled="hasActiveIntegrationImport"
             :title="
-              hasActiveIntercomImport
+              hasActiveIntegrationImport
                 ? $t('DATA_IMPORTS.DRAWER.ACTIVE_IMPORT')
                 : undefined
             "
@@ -371,7 +371,7 @@ onBeforeUnmount(() => {
 
   <NewImportDialog
     :show="showImportDrawer"
-    :has-active-import="hasActiveIntercomImport"
+    :has-active-import="hasActiveIntegrationImport"
     @close="showImportDrawer = false"
     @created="onImportCreated"
   />

app/javascript/dashboard/routes/dashboard/settings/data/NewImportDialog.vue

@@ -8,7 +8,7 @@ import Checkbox from 'dashboard/components-next/checkbox/Checkbox.vue';
 import Input from 'dashboard/components-next/input/Input.vue';
 import Select from 'dashboard/components-next/select/Select.vue';
 import DataImportsAPI from 'dashboard/api/dataImports';
-import { IMPORT_SOURCES } from './importSources';
+import { IMPORT_SOURCES, importSourceConfigFor } from './importSources';
 
 const props = defineProps({
   show: { type: Boolean, default: false },
@@ -20,8 +20,17 @@ const emit = defineEmits(['close', 'created']);
 const { t } = useI18n();
 const dialogRef = ref(null);
 const sourceProvider = ref('intercom');
-const importName = ref(t('DATA_IMPORTS.DEFAULT_IMPORT_NAME'));
+const sourceConfig = computed(
+  () => importSourceConfigFor(sourceProvider.value) || IMPORT_SOURCES[0]
+);
+const defaultImportName = computed(() =>
+  sourceProvider.value === 'freshdesk'
+    ? t('DATA_IMPORTS.DEFAULT_IMPORT_NAMES.FRESHDESK')
+    : t('DATA_IMPORTS.DEFAULT_IMPORT_NAMES.INTERCOM')
+);
+const importName = ref(defaultImportName.value);
 const accessToken = ref('');
+const domain = ref('');
 const selectedImportTypes = ref(['contacts', 'conversations']);
 const validationState = ref('idle');
 const validationMessage = ref('');
@@ -34,6 +43,17 @@ const sourceOptions = computed(() =>
   IMPORT_SOURCES.map(({ value, label }) => ({ value, label }))
 );
 
+const credentialPlaceholder = computed(() =>
+  sourceProvider.value === 'freshdesk'
+    ? t('DATA_IMPORTS.DRAWER.FRESHDESK_API_KEY_PLACEHOLDER')
+    : t('DATA_IMPORTS.DRAWER.INTERCOM_ACCESS_KEY_PLACEHOLDER')
+);
+const credentialLabel = computed(() =>
+  sourceProvider.value === 'freshdesk'
+    ? t('DATA_IMPORTS.DRAWER.FRESHDESK_API_KEY')
+    : t('DATA_IMPORTS.DRAWER.INTERCOM_ACCESS_KEY')
+);
+
 const tokenMessageType = computed(() => {
   if (validationState.value === 'valid') return 'success';
   if (validationState.value === 'invalid') return 'error';
@@ -51,9 +71,14 @@ const canCreate = computed(
 const validationPayload = () => ({
   source_provider: sourceProvider.value,
   access_token: accessToken.value.trim(),
+  ...(sourceConfig.value.requiresDomain ? { domain: domain.value.trim() } : {}),
   import_types: selectedImportTypes.value,
 });
 
+const hasRequiredCredentials = () =>
+  accessToken.value.trim() &&
+  (!sourceConfig.value.requiresDomain || domain.value.trim());
+
 const invalidateValidation = () => {
   validationRequestId += 1;
   validationState.value = 'idle';
@@ -61,7 +86,7 @@ const invalidateValidation = () => {
 };
 
 const validateSource = async () => {
-  if (!accessToken.value.trim() || !selectedImportTypes.value.length) {
+  if (!hasRequiredCredentials() || !selectedImportTypes.value.length) {
     invalidateValidation();
     return;
   }
@@ -98,7 +123,7 @@ const createImport = async () => {
   try {
     const response = await DataImportsAPI.create({
       ...validationPayload(),
-      name: importName.value.trim() || t('DATA_IMPORTS.DEFAULT_IMPORT_NAME'),
+      name: importName.value.trim() || defaultImportName.value,
     });
     useAlert(t('DATA_IMPORTS.ALERTS.IMPORT_STARTED'));
     emit('created', response.data.id);
@@ -112,10 +137,18 @@ const createImport = async () => {
 };
 
 watch(accessToken, invalidateValidation);
+watch(domain, invalidateValidation);
+
+watch(sourceProvider, () => {
+  importName.value = defaultImportName.value;
+  accessToken.value = '';
+  domain.value = '';
+  invalidateValidation();
+});
 
 watch(selectedImportTypes, () => {
   invalidateValidation();
-  if (accessToken.value.trim() && selectedImportTypes.value.length) {
+  if (hasRequiredCredentials() && selectedImportTypes.value.length) {
     validateSource();
   }
 });
@@ -130,6 +163,7 @@ watch(
 
     dialogRef.value?.close();
     accessToken.value = '';
+    domain.value = '';
     validationState.value = 'idle';
     validationMessage.value = '';
   }
@@ -164,12 +198,21 @@ watch(
         :placeholder="$t('DATA_IMPORTS.DRAWER.NAME_PLACEHOLDER')"
       />
 
+      <Input
+        v-if="sourceConfig.requiresDomain"
+        v-model="domain"
+        autocomplete="off"
+        :label="$t('DATA_IMPORTS.DRAWER.FRESHDESK_DOMAIN')"
+        :placeholder="$t('DATA_IMPORTS.DRAWER.FRESHDESK_DOMAIN_PLACEHOLDER')"
+        @blur="validateSource"
+      />
+
       <Input
         v-model="accessToken"
         type="password"
         autocomplete="off"
-        :label="$t('DATA_IMPORTS.DRAWER.ACCESS_KEY')"
-        :placeholder="$t('DATA_IMPORTS.DRAWER.ACCESS_KEY_PLACEHOLDER')"
+        :label="credentialLabel"
+        :placeholder="credentialPlaceholder"
         :message="validationMessage"
         :message-type="tokenMessageType"
         @blur="validateSource"

app/javascript/dashboard/routes/dashboard/settings/data/importSources.js

@@ -4,8 +4,17 @@ export const IMPORT_SOURCES = [
     label: 'Intercom',
     icon: '/dashboard/images/integrations/intercom.png',
   },
+  {
+    value: 'freshdesk',
+    label: 'Freshdesk',
+    iconClass: 'i-lucide-life-buoy',
+    requiresDomain: true,
+  },
 ];
 
+export const importSourceConfigFor = provider =>
+  IMPORT_SOURCES.find(source => source.value === provider);
+
 const DEFAULT_IMPORT_SOURCE = {
   value: 'file',
   label: 'File import',
@@ -13,5 +22,4 @@ const DEFAULT_IMPORT_SOURCE = {
 };
 
 export const importSourceFor = dataImport =>
-  IMPORT_SOURCES.find(source => source.value === dataImport?.source_provider) ||
-  DEFAULT_IMPORT_SOURCE;
+  importSourceConfigFor(dataImport?.source_provider) || DEFAULT_IMPORT_SOURCE;

app/javascript/dashboard/routes/dashboard/settings/data/importStatus.js

@@ -9,14 +9,21 @@ export const isIntercomImport = dataImport =>
   dataImport?.data_type === 'intercom' &&
   dataImport?.source_provider === 'intercom';
 
+export const isIntegrationImport = dataImport =>
+  ['freshdesk', 'intercom'].includes(dataImport?.data_type) &&
+  dataImport?.data_type === dataImport?.source_provider;
+
 export const isActiveIntercomImport = dataImport =>
   isIntercomImport(dataImport) && isActiveImport(dataImport);
 
+export const isActiveIntegrationImport = dataImport =>
+  isIntegrationImport(dataImport) && isActiveImport(dataImport);
+
 export const isAbandonableImport = dataImport =>
-  isActiveIntercomImport(dataImport);
+  isActiveIntegrationImport(dataImport);
 
 export const importedCount = dataImport => {
-  if (!isIntercomImport(dataImport)) {
+  if (!isIntegrationImport(dataImport)) {
     return Number(dataImport?.processed_records || 0);
   }
 

app/javascript/dashboard/routes/dashboard/settings/data/specs/NewImportDialog.spec.js

@@ -0,0 +1,104 @@
+import { flushPromises, mount } from '@vue/test-utils';
+import { nextTick } from 'vue';
+import DataImportsAPI from 'dashboard/api/dataImports';
+import NewImportDialog from '../NewImportDialog.vue';
+
+vi.mock('dashboard/api/dataImports', () => ({
+  default: {
+    validateSource: vi.fn(),
+    create: vi.fn(),
+  },
+}));
+
+vi.mock('dashboard/composables', () => ({
+  useAlert: vi.fn(),
+}));
+
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({ t: key => key }),
+}));
+
+const DialogStub = {
+  name: 'Dialog',
+  props: {
+    disableConfirmButton: { type: Boolean, default: false },
+  },
+  emits: ['close', 'confirm'],
+  methods: {
+    open() {},
+    close() {},
+  },
+  template: `
+    <section>
+      <slot />
+      <button
+        data-test="confirm"
+        :disabled="disableConfirmButton"
+        @click="$emit('confirm')"
+      />
+    </section>
+  `,
+};
+
+const mountDialog = () =>
+  mount(NewImportDialog, {
+    props: { show: true },
+    global: {
+      stubs: {
+        Dialog: DialogStub,
+        Checkbox: true,
+      },
+      mocks: {
+        $t: key => key,
+      },
+    },
+  });
+
+describe('NewImportDialog', () => {
+  beforeEach(() => {
+    DataImportsAPI.validateSource.mockResolvedValue({
+      data: { valid: true, totals: {} },
+    });
+    DataImportsAPI.create.mockResolvedValue({ data: { id: 42 } });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('validates and creates a Freshdesk import with its domain', async () => {
+    const wrapper = mountDialog();
+    await wrapper.find('select').setValue('freshdesk');
+    await nextTick();
+
+    const domainInput = wrapper.find(
+      'input[placeholder="DATA_IMPORTS.DRAWER.FRESHDESK_DOMAIN_PLACEHOLDER"]'
+    );
+    const apiKeyInput = wrapper.find(
+      'input[placeholder="DATA_IMPORTS.DRAWER.FRESHDESK_API_KEY_PLACEHOLDER"]'
+    );
+    await domainInput.setValue('acme.freshdesk.com');
+    await apiKeyInput.setValue(' freshdesk-api-key ');
+    await apiKeyInput.trigger('blur');
+    await flushPromises();
+
+    expect(DataImportsAPI.validateSource).toHaveBeenCalledWith({
+      source_provider: 'freshdesk',
+      domain: 'acme.freshdesk.com',
+      access_token: 'freshdesk-api-key',
+      import_types: ['contacts', 'conversations'],
+    });
+
+    await wrapper.find('[data-test="confirm"]').trigger('click');
+    await flushPromises();
+
+    expect(DataImportsAPI.create).toHaveBeenCalledWith({
+      source_provider: 'freshdesk',
+      domain: 'acme.freshdesk.com',
+      access_token: 'freshdesk-api-key',
+      import_types: ['contacts', 'conversations'],
+      name: 'DATA_IMPORTS.DEFAULT_IMPORT_NAMES.FRESHDESK',
+    });
+    expect(wrapper.emitted('created')).toEqual([[42]]);
+  });
+});

app/javascript/dashboard/routes/dashboard/settings/data/specs/importSources.spec.js

@@ -0,0 +1,28 @@
+import {
+  IMPORT_SOURCES,
+  importSourceConfigFor,
+  importSourceFor,
+} from '../importSources';
+
+describe('importSources', () => {
+  it('exposes Freshdesk as a domain-based integration source', () => {
+    expect(IMPORT_SOURCES.map(source => source.value)).toEqual([
+      'intercom',
+      'freshdesk',
+    ]);
+    expect(importSourceConfigFor('freshdesk')).toMatchObject({
+      label: 'Freshdesk',
+      requiresDomain: true,
+    });
+  });
+
+  it('resolves persisted integrations and falls back for file imports', () => {
+    expect(importSourceFor({ source_provider: 'freshdesk' }).label).toBe(
+      'Freshdesk'
+    );
+    expect(importSourceFor({ source_provider: null })).toMatchObject({
+      value: 'file',
+      label: 'File import',
+    });
+  });
+});

app/javascript/dashboard/routes/dashboard/settings/data/specs/importStatus.spec.js

@@ -2,6 +2,7 @@ import {
   formatDate,
   importedCount,
   isActiveIntercomImport,
+  isActiveIntegrationImport,
   statusDotClass,
 } from '../importStatus';
 
@@ -32,12 +33,38 @@ describe('importStatus', () => {
     });
   });
 
-  describe('importedCount', () => {
-    it('sums Intercom imported stats', () => {
+  describe('isActiveIntegrationImport', () => {
+    it('treats matching Freshdesk and Intercom imports as active', () => {
       expect(
-        importedCount({
+        isActiveIntegrationImport({
+          data_type: 'freshdesk',
+          source_provider: 'freshdesk',
+          status: 'pending',
+        })
+      ).toBe(true);
+      expect(
+        isActiveIntegrationImport({
           data_type: 'intercom',
           source_provider: 'intercom',
+          status: 'processing',
+        })
+      ).toBe(true);
+      expect(
+        isActiveIntegrationImport({
+          data_type: 'freshdesk',
+          source_provider: 'intercom',
+          status: 'processing',
+        })
+      ).toBe(false);
+    });
+  });
+
+  describe('importedCount', () => {
+    it('sums integration imported stats', () => {
+      expect(
+        importedCount({
+          data_type: 'freshdesk',
+          source_provider: 'freshdesk',
           processed_records: 20,
           stats: {
             contacts: { imported: 2 },