Import data from another platform (Intercom and Freshdesk)

Overview

The Settings → Data area brings your customer history from another support tool into your ConversaLabs account. It has two tabs: Import and Export (exporting is still marked as Coming soon).

Two integration sources are supported today:

Every import runs in the background, on a low-priority queue: you can close the screen and keep working. While it is active, the page refreshes itself every 5 seconds and shows the current stage, how much was imported per type, the errors and everything that was skipped.

The Import tab lists the account's imports, newest first, with the total right above the list. It also includes the CSV contact imports started from the Contacts area: those do not come from an integration, and the row icon shows File import on hover.

Prerequisites

• Administrator role. Every action in this area (list, open, create, retry, abandon and download the log CSVs) requires it.
• The Data import capability (the data_import flag) must be enabled for the account. It ships disabled by default; without it, the Data entry does not even appear in the settings menu.
• Intercom: an access key for your workspace. The platform calls the public Intercom API (https://api.intercom.io, API version 2.15) with that key.
• Freshdesk: your account domain and an API key. The platform calls https://YOUR-DOMAIN/api/v2 authenticating with the key. The domain must end in .freshdesk.com — typing just acme completes it to acme.freshdesk.com.
• Only one active integration import per account. While one is pending or processing, the new import button stays disabled.

The credential is stored encrypted (when encryption is configured on the installation) and is never returned by the API — neither in the list nor in the import detail.

Step by step

1. Open Settings → Data and stay on the Import tab.
2. Click Import.
3. Under Source, pick Intercom or Freshdesk.
4. Adjust the Import name if you want. The default is Intercom import or Freshdesk import.
5. For Freshdesk, fill in the Freshdesk domain (example: acme.freshdesk.com).
6. Paste the Intercom access key or the Freshdesk API key. When you leave the field, validation runs automatically and the field shows Validating access key…, then Access key validated. or the error message.
7. Under Data to import, Contacts and Conversations are ticked already. Untick whatever you do not want to bring over; at least one of the two is required.
8. Click Import. The button only enables when the key is validated, at least one type is ticked and there is no other active import.
9. You are taken straight to the import tracking screen.

Settings & options

What is imported, and in which order

Contacts are imported first, then conversations (and each conversation's messages). If you tick only one of the types, only that stage runs.

Contacts

• Name, email (normalized to lowercase and validated) and phone in E.164 format — a number without + gets the prefix automatically; anything that does not end up in E.164 is discarded.
• Identifier = the source external_id (in Freshdesk, unique_external_id).
• A contact with an email or a phone is created with the Lead type.
• Custom attributes created: intercom_contact_id and intercom_external_id, or freshdesk_contact_id and freshdesk_unique_external_id.
• In Freshdesk the phone comes from mobile (or phone); other emails, custom fields and tags are kept in the contact's source metadata.
• Deduplication: the platform looks for an existing contact by identifier, then by email, then by phone. If it finds one, it updates that contact instead of creating another.

Conversations and messages

• Every imported conversation lands with the Resolved status and its own identifier (intercom:<id> or freshdesk:<id>), which prevents duplicates on a later import.
• Conversations are spread across import inboxes created automatically, of the API type, one per source channel, with names like Intercom Import - Email, Intercom Import - WhatsApp or Freshdesk Import - Phone. They are created with auto assignment turned off.
  • Intercom: Email, Instagram, Facebook, SMS, Twitter, WhatsApp, Phone, Messenger and Unknown.
  • Freshdesk: Email, Phone, Forum, Twitter, Facebook, Portal, Chat, Mobile, Ecommerce, Bot, WhatsApp, Internal task, Instagram, SMS and Unknown.
• Incoming or outgoing: a message is incoming when the source author is a contact, a user or a lead, and outgoing otherwise. An internal note from the source becomes a private note.
• Intercom events become activity messages on the timeline, in the account's language: assignment, open, close, snooze, participant added or removed, attribute change, custom action and quick reply. Freshdesk has no equivalent record.
• The body is sanitized: HTML is converted to plain text.
• Conversation custom attributes: intercom_conversation_id, or freshdesk_ticket_id, freshdesk_subject, freshdesk_status and freshdesk_priority.

Tracking

The detail screen shows five tiles — Source, Import types, Created, Duration and Started by — plus an Import progress block. The counters follow what you ticked: Contacts shows up when contacts were included; Conversations and Messages show up when conversations were included.

The percentage bar only appears when the source reports a total. Intercom returns the contact and conversation totals during validation; Freshdesk does not return totals, so there the progress only shows how many records already came in.

The stage is shown in the header: Queued, Importing contacts, Importing conversations, Finalizing import, Completed, Completed with errors, Failed or Abandoned. When it ends, the import is Completed when no error was recorded, and Completed with errors when there was at least one.

Errors and skipped records

The detail brings two sections:

• Errors — run failures and incomplete conversations.
• Skip logs — what was skipped or failed on a specific record, with a filter for All, Contacts, Conversations and Messages — each type shows its own count.

Each section shows the 5 most recent records on screen plus a Download CSV button with the complete list. The files are named data-import-<id>-error-logs.csv and data-import-<id>-skip-logs.csv, with the columns created_at, kind, source_object_type, source_object_id, error_code, message and details.

The kind field tells what happened:

Frequent skip reasons: already imported in a previous import (the existing record is reused), the body had no readable text after HTML sanitization, attachments are present but no importable text was found and no body or attachments to import.

Resume, retry and abandon

• After each processed page the platform saves a cursor, and the next page is queued as a new job. If something interrupts the run, it starts again from the saved point without redoing what already came in.
• An import with no update for 15 minutes is flagged as stalled. When that happens the Retry button appears in the detail header and puts the run back in the queue.
• The Abandon button is available while the import is pending or processing and ends the run.
• Repeating the import from the same source does not duplicate records: every source object has a unique mapping per account, provider and type.

Use cases

• Migrate the support history from Intercom or Freshdesk when switching tools, without losing customer context.
• Bring only the contacts first, validate the base, then run a second import with the conversations.
• Keep the old history searchable inside the platform, in separate inboxes, while new support happens in the real channels.
• Audit the migration with the error and skip-log CSVs before switching the old tool off.

Tips, limits & best practices

• One integration import at a time per account. Plan the order if you have several sources.
• Attachments are not downloaded. In place of the file, the message gets a marker with the source attachment count — [Intercom attachment skipped: 2] or [Freshdesk attachment skipped: 2]. Attachment metadata is kept on the record.
• Source tags and labels do not become platform labels: they are preserved in the source metadata of the contact and of the conversation.
• Source agents do not become account users. Agent messages land as outgoing, with no linked sender.
• Freshdesk: the ticket sweep is capped at 300 pages of 100 tickets, and tickets are processed in chunks of 10. Intercom paginates 50 contacts and 10 conversations at a time.
• Do not delete the Import inboxes created by the migration — the imported conversations live there.
• Run the import during a quieter period and review the log CSVs before calling the migration done.
• If the credential is rotated or removed after the import was created, the resume actions answer that the credential is unavailable — in that case, create a new import.

Troubleshooting

• I don't see “Data” in the settings menu. The capability is not enabled for the account, or your role is not Administrator.
• “We could not validate this Intercom access key. Check the key and its permissions.” (or “…this Freshdesk API key…”; when the source returns no message, the local text “Could not validate this access key.” is shown instead.) The key is wrong, expired, or missing the read permissions required on the source tool.
• “Intercom could not be reached. Please try again.” (or “Freshdesk could not be reached…”) The source answered with a non-authentication error, or did not answer in time. Try again in a few minutes.
• “Enter a valid Freshdesk domain, such as acme.freshdesk.com.” The domain you typed is not a valid Freshdesk domain. Use your account subdomain.
• “Another data import is already in progress.” There is already a pending or processing import. Wait for it to finish, or abandon it.
• The Import button stays disabled. The key is not validated yet, no data type is ticked, or there is an active import.
• “This … import is no longer stalled.” The import started progressing again before you clicked Retry — just keep watching it.
• It finished as “Completed with errors”. Open the Errors and Skip logs sections and download the CSVs to see exactly which source objects did not come in, and why.
• Freshdesk progress shows no percentage. That is expected: the source does not return totals, so only the number of imported records is shown.

See also

• Contacts: import and segments
• Integrations
• Account, agents and teams
• Audit logs
• Administration overview