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

| Source | Credential | Extra field |
|---|---|---|
| **Intercom** | Intercom access key | — |
| **Freshdesk** | Freshdesk API key | Domain (`acme.freshdesk.com`) |

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:

| `kind` | Meaning |
|---|---|
| `skipped` | Record intentionally skipped (for example, already imported before) |
| `failed` | Record that errored and did not come in |
| `incomplete` | The source returned fewer conversation parts than the total it reported |
| `run_error` | The whole run failed |

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](/hc/ajuda/articles/contacts-crm-contatos-import-segmentos-en)
- [Integrations](/hc/ajuda/articles/administration-integracoes-en)
- [Account, agents and teams](/hc/ajuda/articles/administration-conta-agentes-equipes-en)
- [Audit logs](/hc/ajuda/articles/administration-auditoria-en)
- [Administration overview](/hc/ajuda/articles/administration-overview-en)