---
title: "Migrate to Intercom: Helpdesk Migration Guide & Service"
description: "Migrating to Intercom? Import limits, the full migration checklist and every source FlitStack AI moves into Intercom, with history and rollback."
url: "https://flitstack.ai/migrations/helpdesk/intercom"
---

# Migrate to Intercom

Intercom is a Messenger-first customer service platform whose migration model rewards teams that load Contacts before Conversations, pre-create Custom Data Attributes, and respect the platform's tight bulk-load budgets.

Short answer

FlitStack AI migrates tickets, threads, and customer histories into Intercom from 250+ helpdesks, including Zendesk, Freshdesk, Gorgias, Salesforce Service Cloud. Every field is mapped to Intercom's objects, history and associations come across, the Intercom setup is configured alongside, and the whole migration stays reversible in one click.

![](https://flitstack.ai/images/authors/aditya-kumar.webp)By [Aditya Kumar](https://flitstack.ai/about/aditya-kumar) Updated November 5, 2026

[Get a quote ](https://flitstack.ai/contact) [See every source →](https://flitstack.ai/migrations/helpdesk/intercom#sources-list)

![](https://flitstack.ai/images/illustrations/pair-stage.webp)

From Any source ![](https://flitstack.ai/platforms-trim/zendesk.webp) ![](https://flitstack.ai/platforms-trim/freshdesk.webp) ![](https://flitstack.ai/platforms-trim/gorgias.webp)

Destination Intercom ![](https://flitstack.ai/platforms-trim/intercom.webp)

Zendesk Freshdesk Gorgias Salesforce Service Cloud Jira Service Management

250+ sources mapped into Intercom

## Systems we move into Intercom

The helpdesks teams most often move from. Each page shows what moves, the field mapping and what to watch for.

[Zendesk to Intercom](https://flitstack.ai/migrations/helpdesk/zendesk/to/intercom) [Freshdesk to Intercom](https://flitstack.ai/migrations/helpdesk/freshdesk/to/intercom) [Gorgias to Intercom](https://flitstack.ai/migrations/helpdesk/gorgias/to/intercom) [Salesforce Service Cloud to Intercom](https://flitstack.ai/migrations/helpdesk/salesforce-service-cloud/to/intercom) [Jira Service Management to Intercom](https://flitstack.ai/migrations/helpdesk/jira-service-management/to/intercom) [![](https://flitstack.ai/platforms-trim/freshservice.webp) Freshservice to Intercom](https://flitstack.ai/migrations/helpdesk/freshservice/to/intercom) [Kustomer to Intercom](https://flitstack.ai/migrations/helpdesk/kustomer/to/intercom)

## What Intercom supports, and where its import tools stop

- Instant chat and message threading on websites and apps gives support teams a single inbox without context-switching, according to reviewers on Capterra and G2 who highlight fast response times as a primary benefit.
- Fin AI handles repetitive inbound queries automatically, reducing agent workload measurably — G2 reviewers report fewer escalations and faster first-response times once Fin is configured.
- Automation workflows (Outbound, Operator, and custom bots) allow teams to qualify leads and route tickets without manual intervention, appealing to growth-stage SaaS companies managing high ticket volumes.
- Help center articles and self-service deflection are natively integrated, so knowledge base content and chat conversations live in the same workspace, simplifying reporting.

**REST only** OAuth 2.0 (preferred) or Personal Access Token

**Rate limits** 10,000 req/min per private app; 25,000 req/min per workspace (private apps share workspace quota)

| Object            | Support | Note                                                                                                                                                                                                                                                                           |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Contacts          | full    | Contacts (Users and Leads) are first-class API objects with a stable schema including email, name, custom attributes, and owner assignment. We migrate contacts 1:1 and preserve all standard and custom properties during import and export.                                  |
| Companies         | full    | Companies are linked to Contacts and expose a standard set of attributes (name, plan, monthly\_spend, custom attributes). We preserve the company-contact association during migration to maintain context in conversation history.                                            |
| Conversations     | mapped  | Conversations are the core Intercom object, containing nested Parts (messages, notes, assignments). We map conversation threads and part types, but note that S3 JSON exports exclude transcripts — we use the REST API to retrieve full conversation content where available. |
| Messages          | mapped  | Messages are nested inside Conversation Parts and include body text, attachments, and delivery metadata. We sequence messages in chronological order and flag any that are redacted or inaccessible via API as part of the migration audit.                                    |
| Admins            | full    | Admins are agent accounts with roles, Avatars, and away/available states. We migrate admin identity mapping so conversation assignments, activity logs, and ownership reflect the correct agents in the destination platform.                                                  |
| Teams             | full    | Teams group Admins for routing and inbox assignment. We preserve team membership and routing rules during migration to maintain the same escalation paths in the target system.                                                                                                |
| Tags              | full    | Tags are labels applied to Contacts and Conversations for segmentation. We migrate all tags and reapply them to the corresponding objects in the destination workspace.                                                                                                        |
| Segments          | mapped  | Segments are dynamic audience definitions based on Contact attributes and behavior. We map the membership snapshot at migration time, as dynamic recomputation of segment membership is destination-platform-dependent.                                                        |
| Articles          | mapped  | Help center Articles have titles, bodies, authors, collections, and publication states. We migrate Article content and metadata, but public visibility settings and article-specific URLs may need manual verification after cutover.                                          |
| Tickets           | mapped  | Tickets are a structured support object introduced more recently in Intercom's model, distinct from the Conversation-first workflow. We map ticket fields, statuses, and custom ticket attributes, noting that not all destination platforms have a parallel Ticket object.    |
| Custom Attributes | mapped  | Custom Attributes extend Contacts, Companies, and Conversations with workspace-specific fields. We identify all custom attribute definitions and their types during scoping, then apply field-level mapping to the destination's equivalent custom field mechanism.            |
| Custom Objects    | mapped  | Custom Objects are user-defined data structures with their own schema and relationships. We migrate Custom Object Instances via the REST API using the custom\_object\_instances endpoints, mapping to the destination's equivalent custom object type.                        |
| Data Attributes   | mapped  | Data Attributes expose the full workspace schema including both standard and custom fields across all object types. We audit the attribute list via the API to generate the complete field inventory before mapping to the destination schema.                                 |
| Activity Logs     | mapped  | Activity Logs record admin actions (assignment changes, status updates, notes added). We migrate the log entries where API access is available, noting that log retention may be limited and that high-volume log exports require pagination handling.                         |

## The Intercom migration guide

## Why teams migrate to Intercom

*The four shapes an Intercom migration takes, and what makes the platform easier — or harder — than the category average.*

Intercom, Inc. — which rebranded as Fin in May 2026 but still ships product under the Intercom brand — is a software company that provides an AI-driven customer service and messaging platform[1](https://flitstack.ai/migrations/helpdesk/intercom#source-1). It is headquartered in San Francisco with offices in Chicago, Dublin, Sydney and London. The product centres on a real-time Messenger, a unified Inbox, a Help Center, and the Fin AI Agent for generative resolution.

The typical Intercom customer is a B2B SaaS or product-led growth team — anywhere from 2 to 200 support agents — that runs live chat and email inside the same product context, and that wants AI deflection wired into the conversation layer rather than bolted on. Compared with Zendesk, Intercom positions itself on Messenger-first UX and per-outcome AI pricing; compared with Freshdesk or Gorgias, it positions on a deeper product-context model where users, companies and conversation data live in one schema.

The shapes of migration that actually land on Intercom tend to fall into four patterns. First, Zendesk exits, where teams want Messenger-native chat and Fin AI Agent on top of historical tickets — Intercom now ships a dedicated Zendesk import tool that pulls users, organizations and tickets through a guided sign-in flow[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). Second, Freshdesk and Help Scout replacements, usually driven by product-team adoption of the Messenger.

Third, consolidation projects — companies replacing a stack of Crisp plus Mailchimp plus a separate KB with Intercom's combined Inbox, Help Center, Outbound and Series. Fourth, email-only-to-omnichannel upgrades, where a support inbox running on Google Workspace or Front graduates to a multi-channel surface that includes Messenger, WhatsApp, SMS, Instagram, Facebook and phone via Twilio[22](https://flitstack.ai/migrations/helpdesk/intercom#source-22).

Each shape has a different difficulty profile: a Zendesk migration usually has clean ticket parity but messy macro and trigger logic, while a Crisp or Help Scout move has fewer automations but rougher conversation threading.

What makes migrating to Intercom easier than the category average is the data model: Contacts (Users + Leads), Companies and Conversations share a single schema with Custom Data Attributes that work consistently across all three[8](https://flitstack.ai/migrations/helpdesk/intercom#source-8). Regional Intercom workspaces exist for US, EU and Australia[12](https://flitstack.ai/migrations/helpdesk/intercom#source-12), and the native Zendesk importer plus Help Desk Migration's marketplace app cover most automated paths[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11).

What makes it harder than the average is the usage-based pricing — Fin AI Agent bills $0.99 per outcome on top of Essential, Advanced or Expert seat costs, and stale-contact loads compound the per-outcome math in unpredictable ways[25](https://flitstack.ai/migrations/helpdesk/intercom#source-25). The bulk-load budget is genuinely tight for any sizeable backfill[9](https://flitstack.ai/migrations/helpdesk/intercom#source-9), and bulk updates on Contacts cap at 10 records per call rather than the 100 most platforms accept[10](https://flitstack.ai/migrations/helpdesk/intercom#source-10).

Macros, Workflows, Series, Outbound messages and Fin Procedures do not import — they are rebuilt from documentation. Teams that scope for that work up front finish on time; teams that assume parity do not.

> Teams that scope for the rebuild work up front finish on time; teams that assume parity do not.

## The Intercom data model you need to map into

*Contacts, Companies, Conversations, Tickets, Custom Data Attributes — and the upsert keys you'll wire on every field.*

Intercom's schema is built around three primary models — Contacts, Companies and Conversations — plus Tickets (added in 2023 as a separate type for back-office and customer-facing work), Help Center articles, and Custom Objects on higher tiers. Everything else (Notes, Tags, Segments, Teams) layers onto those primaries.

Before you can map a field on the source side, you need to know exactly which destination model the row belongs on, what its required fields are, and which value will serve as its upsert key. The table below summarises the objects you will touch in a typical migration.

| Object                             | What it stores                                                  | Required                                            | Tier                                                                                          |
| ---------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Contacts (Users + Leads)           | End-users of your product, plus pre-signup leads                | email or external\_id (for Users)                   | All plans                                                                                     |
| Companies                          | Organisations associated with Users                             | company\_id and name                                | All plans                                                                                     |
| Conversations                      | Two-sided message threads (chat or email)                       | Contact reference + initial message body            | All plans                                                                                     |
| Tickets                            | Structured customer-facing or back-office work items            | Ticket type, contact, attributes per type           | All plans (Tickets product, 2023+)                                                            |
| Help Center Articles + Collections | KB articles, sub-collections, translations                      | Title, body, collection                             | All paid plans                                                                                |
| Custom Data Attributes (CDAs)      | User/Company/Conversation custom fields                         | Name, type; soft cap 250 active CDAs                | All plans[8](https://flitstack.ai/migrations/helpdesk/intercom#source-8)                      |
| Custom Objects                     | Non-standard external entities (orders, assets, etc.)           | Schema defined first; associated to Contact/Company | Higher tiers / per-workspace[13](https://flitstack.ai/migrations/helpdesk/intercom#source-13) |
| Notes                              | Internal teammate-only annotations on conversations or contacts | Body + contact/conversation reference               | All plans                                                                                     |
| Tags & Segments                    | Categorisation and saved-filter audiences                       | Name (Tag) or filter rules (Segment)                | All plans                                                                                     |

Contacts have two upsert paths. Users (logged-in customers of your product) are matched on `external_id` when present, else `email`. Leads (anonymous Messenger visitors) are matched on the internal Intercom `id`. Companies upsert on `company_id`, which is a string you control — set it from the source system's organisation primary key, never from a display name[8](https://flitstack.ai/migrations/helpdesk/intercom#source-8).

Conversations and Tickets do not have a customer-supplied unique key, so each one gets an Intercom-assigned `id` on create. If you need round-trippable references back to the source system, stamp the source ticket ID into a Conversation custom attribute (CDA on the Conversation model) at create time — there is no retrofit path[14](https://flitstack.ai/migrations/helpdesk/intercom#source-14).

Custom Data Attributes are typed at creation and the catalogue below covers what you can model and the limits you need to plan around. CDAs are scoped to one of three models — Contact, Company, or Conversation — and you cannot share a CDA across models[16](https://flitstack.ai/migrations/helpdesk/intercom#source-16).

| Field type                   | Limit                                       | Notes                                                                                                                                |
| ---------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| String                       | 255 characters                              | Most common type; values over 255 chars are silently truncated[8](https://flitstack.ai/migrations/helpdesk/intercom#source-8)        |
| Number (integer)             | Whole numbers only                          | Leading zeros stripped — store zip codes as strings                                                                                  |
| Boolean                      | true / false                                | JSON booleans on programmatic loads; checkbox in the UI                                                                              |
| Date / Timestamp             | Unix timestamp (seconds)                    | Custom attribute names ending in `_at` are auto-typed as date[21](https://flitstack.ai/migrations/helpdesk/intercom#source-21)       |
| List (single-select)         | Workspace-defined options                   | User picks one option only — not a checkbox/multi-select[4](https://flitstack.ai/migrations/helpdesk/intercom#source-4)              |
| Custom Data Attributes total | Soft cap 250 active CDAs                    | Soft limit across all custom attributes per workspace[8](https://flitstack.ai/migrations/helpdesk/intercom#source-8)                 |
| Active Events                | 120 active events at a time                 | Archive unused events to make room[9](https://flitstack.ai/migrations/helpdesk/intercom#source-9)                                    |
| Conversation attributes      | Same CDA mechanism, scoped to conversations | Must exist BEFORE conversations are imported, or values are dropped[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11) |
| Custom Object schemas        | Per-workspace limit (higher tiers)          | Define schema and associations before importing records[13](https://flitstack.ai/migrations/helpdesk/intercom#source-13)             |

Relationships in Intercom are sparse compared with a CRM. A User belongs to zero or one Company by default (via `company_id`); a Conversation belongs to one Contact (the conversation `source.author`) but can list participants; Tickets attach to one or more Contacts. There is no native cascade-delete and no master-detail concept — when a Contact is deleted, the Conversations it authored are anonymised, not removed, which is a behaviour you must reproduce in audit reports if your source platform cascaded.

**$0.99** Per Fin AI Agent outcome Billed on top of Essential / Advanced / Expert seat costs. An outcome counts when Fin resolves, the customer doesn't ask again, or Fin completes a workflow — so stale contact loads can push the meter in unpredictable ways. Minimum monthly commitment applies[25](https://flitstack.ai/migrations/helpdesk/intercom#source-25).

Custom Objects (higher tiers) participate as side records — you define the schema in Settings → Data → Custom Objects, then associate instances to Contacts or Companies. Once configured, they show up on the contact profile and are usable by Fin AI as context[13](https://flitstack.ai/migrations/helpdesk/intercom#source-13).

## Pre-migration prep — the work before you touch Intercom

*What must be true on the source, the destination, and across the team before the first row hits the import tool.*

The single best predictor of a clean Intercom migration is how much work you do on the source side before the first load runs. Intercom's own migration documentation lays down a strict order of operations — Contacts first, then Custom Data Attributes, then Conversations or Tickets — and an import that skips that order will fail mid-load or, worse, silently drop attribute values[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11).

> An import that skips the Contacts → CDA → Conversations order will fail mid-load or, worse, silently drop attribute values.

Treat the source export as raw material that needs to be shaped to Intercom's expected formats — email lowercased, phone normalised, picklist values mapped to existing List options, dates rewritten to Unix-seconds timestamps, `_at` suffix added to date attribute names so they get auto-typed as date[21](https://flitstack.ai/migrations/helpdesk/intercom#source-21).

### Source-side prep

- Audit and dedup the source database before export. Email-case-only duplicates collapse silently on Intercom's import, and fuzzy name+company matching produces 10–25 percent false positives on B2B contact lists — review fuzzy matches manually, never auto-merge.
- Normalise emails to lowercase and trim whitespace; map your source primary key into a column named `external_id` so future re-imports and reconciliation match on a stable identifier rather than mutable email.
- Reconcile `user_id` / `external_id` between source and destination before the first import — Intercom's own migration runbook warns that changes to `user_id` via CSV after migration are not supported[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11).
- Map source picklist labels to Intercom List options for every enumeration attribute. List CDAs only accept previously defined option values; sending a new label silently drops the attribute on that row.
- Decide what is in scope for historical conversations and tickets. A typical Zendesk → Intercom move treats Closed tickets as the first batch (the 'Initial Run') and Open + Pending as the delta during cutover[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). Document the Delta Date in your run book.

### Destination-side prep

- Create a Test Workspace under Settings → Workspace → Test Workspaces (available on Advanced and Expert plans) and dry-run the full import there before touching production[7](https://flitstack.ai/migrations/helpdesk/intercom#source-7). A Test Workspace is a separate Intercom account that mirrors production settings without affecting billing or live customers.
- Provision teammates and Teams before importing — owner assignment fails silently if the referenced teammate email does not exist in the workspace. Decide which teammates need Lite seats versus full seats; Lite seats cost less but cannot reply.
- Pre-create every Custom Data Attribute on the right model (Contact, Company, or Conversation) with the right type. CDAs cannot be retyped after creation, and conversation attributes that do not exist when a conversation is imported will have their values dropped[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11) [16](https://flitstack.ai/migrations/helpdesk/intercom#source-16).
- Build Help Center collections before importing articles. Articles target a collection on create, and Intercom rejects article rows whose target collection does not yet exist.
- Define Custom Objects, their associations, and their attributes before importing instances. Custom Object schemas have to exist before records of that type can be created[13](https://flitstack.ai/migrations/helpdesk/intercom#source-13).

### People prep

Cutover only works if humans cooperate. Lock down a source-system freeze window — typically 24 to 72 hours — and communicate it to every team that touches the inbox. Train agents on Intercom's Inbox views, macros and Fin AI handoff behaviour before go-live, not after.

A small-team migration with under 5,000 contacts runs one to two weeks from planning to go-live; a mid-market move with multiple Teams, complex SLAs and brand inboxes runs four to eight weeks of elapsed time even when the technical work is faster. Build the human runway accordingly.

## Import mechanisms: UI wizard, CSV, and Zendesk import

*Three paths in, each with different limits and shapes. Picking the wrong one is how mid-migrations stall at scale.*

Intercom exposes three load paths and the right one depends on dataset size, object mix, and whether you are coming from a specific source platform. The native CSV importer covers Contact loads under a few hundred thousand rows. The Zendesk Import tool covers users, organizations and tickets through a guided sign-in flow. A third-party marketplace tool handles programmatic, repeatable, very large loads, and anything that involves Conversations or Tickets — neither of which is supported by the CSV path[3](https://flitstack.ai/migrations/helpdesk/intercom#source-3) [11](https://flitstack.ai/migrations/helpdesk/intercom#source-11).

### UI Import Tool (CSV)

The native CSV importer lives at Settings → Data → Imports & Exports[2](https://flitstack.ai/migrations/helpdesk/intercom#source-2). It supports CSV files only — no XLS or XLSX — and the maximum file size is 20 MB[2](https://flitstack.ai/migrations/helpdesk/intercom#source-2). Larger files have to be split. Quick Import handles a single object (Users or Leads only); CSV cannot import Conversations, Tickets, or Help Center articles natively[3](https://flitstack.ai/migrations/helpdesk/intercom#source-3). The `user_id` column must be lowercase with underscores; mismatched casing creates duplicate Lead records instead of updating the existing User[2](https://flitstack.ai/migrations/helpdesk/intercom#source-2).

The right call: the CSV importer for one-shot Contact loads under 100k rows, or any time you want a UI mapping review before commit. For anything else, use a third-party migration tool.

### Zendesk Import tool (native)

Intercom ships a dedicated Zendesk migration path at Inbox → Tickets → Getting started → Import from Zendesk that pulls users, organizations and tickets through a guided sign-in flow[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). This is available on a per-workspace basis — if you do not see it in your workspace, reach out to Intercom Support. It handles conversation history with timestamps, attachments, and ticket-to-conversation conversion, and is the fastest path for teams whose only source is Zendesk.

### Third-party migration tools

Tools like Help Desk Migration (the Intercom Marketplace app), Skyvia and User.com's Intercom importer sit between the source and Intercom. They are commonly used in two ways: (a) automated end-to-end migration where the tool reads the source and writes to Intercom with a visual mapping UI; and (b) staging-and-validate, where the tool handles CSV generation, type coercion and dedup before the result is fed into Intercom through its supported load paths[30](https://flitstack.ai/migrations/helpdesk/intercom#source-30).

Under 10,000 Contacts only → native CSV importer. Coming from Zendesk → the native Zendesk Import tool. Anything else (Conversations, Tickets, Custom Objects, Articles, or 100k+ records) → a marketplace migration tool.

## Mapping your data into Intercom

*The longest section — because helpdesk migrations live or die on conversation threading, KB import order, and macro/workflow rebuild scope.*

Mapping is where every helpdesk migration earns its scars. The decisions you make in your mapping spreadsheet determine whether old conversations are findable on day two, whether Fin AI has the article context to deflect on day five, and whether your agents trust the inbox on day thirty.

Work in Intercom's documented order: Contacts → Companies → Custom Data Attributes → Conversations / Tickets → Help Center articles → Custom Objects[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). Skipping ahead drops attribute values silently and forces re-runs.

### Contacts and Companies

| Source                             | Destination              | Note                                                                                                                    |
| ---------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| user\_id / customer\_id (source)   | external\_id             | Upsert key for Users; map from source primary key, never from email                                                     |
| email                              | email                    | Lowercased; secondary upsert key when external\_id is absent                                                            |
| name / first\_name + last\_name    | name                     | Single field on Intercom — concatenate first + last on source                                                           |
| phone                              | phone                    | Disable phone validation in workspace settings before import if source has invalid formats                              |
| signed\_up\_at                     | signed\_up\_at           | Unix timestamp; auto-typed as date due to `_at` suffix[21](https://flitstack.ai/migrations/helpdesk/intercom#source-21) |
| company / organisation             | companies\[].company\_id | Set company\_id from source org primary key, not display name                                                           |
| language / locale                  | language\_override       | ISO 639-1 code; drives Help Center article matching for Fin                                                             |
| anonymous visitor / pre-signup row | Lead (role=lead)         | Leads use Intercom-internal id only; cannot have external\_id until converted to User                                   |

| Source                        | Destination                      | Note                                                                  |
| ----------------------------- | -------------------------------- | --------------------------------------------------------------------- |
| org\_id / account\_id         | company\_id                      | Upsert key — set from stable source primary key                       |
| company\_name / account\_name | name                             | Display field; not used for matching                                  |
| plan\_tier / mrr              | Custom Data Attribute on Company | Drives segmentation and Fin context                                   |
| industry                      | industry                         | Free-text string on Intercom — no enum constraint                     |
| user → org membership         | Contact.companies\[].company\_id | Attach companies on the Contact payload, not via a separate join call |

### Conversation history (chat + email threads)

Conversation history is the heart of a helpdesk migration. Intercom's documented approach is to import each historical conversation as a Conversation (chat-like temporal thread) or a Ticket (structured work item) depending on its shape — and the choice of model is irreversible per record[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). Pure two-sided message threads should land as Conversations; structured work with state machines (bug reports, refund requests, back-office investigations) should land as Tickets.

Each Conversation requires a Contact to exist first, then is created with `source.author` referencing the Contact and `source.body` as the initial message. Subsequent replies are appended with `message_type=comment` for the customer or `message_type=note` for internal teammate notes[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). The `created_at` field on the conversation accepts a Unix timestamp, so backdated history shows up correctly in chronological order on the contact timeline.

Threading is preserved by ordering reply writes in the source-system timestamp sequence and using the same Conversation `id` returned by the create call. Skip the order and replies attach but the timeline reads upside-down. Notes (teammate-only annotations) round-trip via the same reply path with `message_type=note`; rich-text formatting accepts a limited HTML subset (bold, italic, lists, links) — code blocks and tables do not render and need to be flattened to plain text before send[19](https://flitstack.ai/migrations/helpdesk/intercom#source-19).

### Tickets

Tickets were added to Intercom in 2023 as a separate model from Conversations[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). Each ticket has a ticket type (e.g. Bug Report, Refund Request, Back-Office Investigation) defined under Settings → Ticket types, with per-type attributes you must pre-create before importing. The Tickets payload expects a `ticket_type_id`, a `contacts[]` array, and a `ticket_attributes` object whose keys match the per-type attribute names exactly[14](https://flitstack.ai/migrations/helpdesk/intercom#source-14).

Ticket state (`open`, `pending`, `resolved`) maps from your source status field via a transform table. Build that table before the first import — submitting a ticket whose state value does not match the type's allowed states returns an `Invalid attribute value` error and the whole batch backs out.

### Help Center articles and Collections (KB import)

Help Center content imports as Articles after their parent Collections have been created. Articles carry a title, body (HTML), author ID, parent collection, and language fields. Cross-links between articles need to be rewritten to the new Intercom article URLs; tools like Help Desk Migration rewrite cross-links automatically on the way in, which saves hours of manual cleanup.

Multilingual help centres carry translations under a single article with per-locale bodies — preserve the language-version structure by importing the default language first and then attaching translations to the same article. Inline images embedded in article bodies need to be uploaded as Intercom-hosted assets first, then referenced in the HTML via the returned URLs, or they appear broken when the source CDN gets decommissioned.

### Macros, Workflows, Series, Outbound — what does NOT import

Macros (canned-response shortcuts in the Inbox), Workflows (the custom automation builder), Series (multi-step outbound nurture flows), Outbound messages (Tours, Posts, Surveys), and Fin Procedures (the new generative resolution flow) do not import from any source platform. They are rebuilt from documentation[18](https://flitstack.ai/migrations/helpdesk/intercom#source-18).

The pragmatic approach is to export your source Zendesk triggers or Freshdesk automations as a CSV of rule names, conditions and actions, then redesign each one as an Intercom Workflow rather than trying to replicate one-to-one — the abstractions are different enough that direct translation loses fidelity.

Saved replies in Intercom (the modern equivalent of Macros) are created manually under Inbox → Macros. Bulk creation is possible but limited to teammates that already exist; plan for a half-day workshop to redesign and rebuild the most-used 20 macros rather than migrating the long tail[18](https://flitstack.ai/migrations/helpdesk/intercom#source-18).

### SLA and CSAT history

SLA support in Intercom is tier-dependent — first-response and resolution SLAs live on the Advanced and Expert plans and are configured per Team Inbox under Settings → Workflows → Office hours and SLAs. Historical SLA breach data does not move across; the new SLAs accrue from go-live. If you need historical SLA reports for compliance, export them from the source platform as PDFs and archive separately.

CSAT is collected via post-conversation rating in Intercom. Historical CSAT scores from the source platform can be loaded onto Conversations as Custom Data Attributes (e.g. `source_csat_score`, `source_csat_comment`), but they will not feed Intercom's native CSAT reports — those reports key off Intercom-collected ratings only. Build a separate report or BI dashboard for combined historical + new CSAT if continuity matters.

### Multi-channel inbox setup

Intercom's Inbox handles Messenger (web/mobile), email, WhatsApp Business, SMS (via Twilio), Instagram DM, Facebook Messenger, and phone (via Twilio). Channel setup is post-migration work — configure each channel under Settings → Channels after the historical data is loaded, so the inbox is not getting flooded with both backfill conversations and live channel traffic simultaneously[22](https://flitstack.ai/migrations/helpdesk/intercom#source-22).

Identity verification (HMAC) for the Messenger is critical to enable before launch. Without HMAC, anyone with a user's `external_id` can impersonate them in the Messenger; with HMAC, the Messenger computes a server-side hash on `external_id` + workspace secret and rejects mismatches. Roll out HMAC alongside the cutover, not in a later phase.

### Files and attachments

Conversation attachments uploaded via Messenger have a per-file cap of 100 MB; incoming email attachments cap at 20 MB total per email including all attachments[20](https://flitstack.ai/migrations/helpdesk/intercom#source-20) [26](https://flitstack.ai/migrations/helpdesk/intercom#source-26). End-user attachments now expire after 30 minutes at their public URL — teammate URLs can be regenerated by reloading the page[26](https://flitstack.ai/migrations/helpdesk/intercom#source-26).

The expiry matters at migration time: if you deep-link to source storage, those links may break when the source platform is decommissioned. The durable pattern is to re-upload attachments to Intercom as part of the Conversation create.

For attachment estates larger than a few hundred GB, the pattern most teams adopt is: keep originals in S3 or Google Drive, store a deep link in a Custom Data Attribute on the Conversation, and only inline-upload the most recent or most-referenced subset.

### Audit trail, ownership and original timestamps

Conversation `created_at` accepts a Unix timestamp on create, so backdated history sorts correctly on the contact timeline. Contact `signed_up_at` and `last_seen_at` similarly accept timestamps and are recommended fields for any User import[21](https://flitstack.ai/migrations/helpdesk/intercom#source-21). Custom date attributes named with the `_at` suffix are auto-typed as date — `last_order_at`, `trial_started_at`, `churned_at` all parse correctly without a separate type declaration[21](https://flitstack.ai/migrations/helpdesk/intercom#source-21).

Teammate ownership on conversations is assigned via `assignee_id` (a teammate Intercom ID), not by email. Pre-resolve the teammate email → Intercom ID mapping in your migration script, and fall back to assigning the conversation to a Team rather than an individual if the original owner is no longer with the company. Account-level audit logs live under Settings → Workspace → Teammates → Activity logs for the last 12 months[17](https://flitstack.ai/migrations/helpdesk/intercom#source-17).

## The pitfalls that derail Intercom migrations

*Eight specific failure modes — ranked by impact, each tied to the exact Intercom mechanism that breaks.*

**high Importing Conversations before Custom Data Attributes exist**

Intercom's documented order of operations is Contacts → CDAs → Conversations/Tickets. If you import a conversation whose payload references a conversation attribute that does not yet exist in the workspace, the conversation itself creates but the attribute value is silently dropped — no error, no field-level warning[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11). Half-loaded migrations discover this on day two when reports key off attributes that are mostly null. Always create CDAs first, then verify each one exists before firing any conversation create operations[16](https://flitstack.ai/migrations/helpdesk/intercom#source-16).

**high Fin AI per-outcome billing surprise from stale-contact loads**

Fin AI Agent bills $0.99 per outcome on top of seat costs[25](https://flitstack.ai/migrations/helpdesk/intercom#source-25). If you import a stale Contact list during migration — say, 50,000 inactive users from a Zendesk export that never used your product — and Fin is live, every spam re-engagement triggers an outcome charge. Teams report month-end Fin bills 5–10× their forecast. Mitigation: import contacts with a `migration_status` CDA flag, scope Fin's audience to active users only via a Segment, and turn Fin off during the import window itself[25](https://flitstack.ai/migrations/helpdesk/intercom#source-25).

**high 10-record cap on bulk Contact create/update**

There is no high-throughput bulk-upsert path on Contacts that accepts more than 10 records per call[10](https://flitstack.ai/migrations/helpdesk/intercom#source-10). A migration loop sized off any larger number returns 400 errors. Updates also require you to either know the Intercom internal ID, or look it up first via Contact search, which is itself throttled tighter than the basic load paths[10](https://flitstack.ai/migrations/helpdesk/intercom#source-10).

**high user\_id / external\_id casing creates duplicate Leads instead of updating Users**

Intercom matches contacts on `external_id` (or `email` if external\_id is absent), and the `user_id` column on CSV imports must be lowercase with underscores[2](https://flitstack.ai/migrations/helpdesk/intercom#source-2). Send `User_ID` or `userId` instead, and the importer treats every row as a brand-new Lead rather than updating the existing User. The duplicates do not cleanly merge — they sit in your workspace as separate Lead records consuming Fin per-outcome billing. Lowercase the column header and verify the first 100-row test import created Users, not Leads, before running the full file[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11).

**high Pricing-plan shock at renewal — 7-8x price increases reported**

Reddit practitioner reports describe Intercom moving customers onto new plans at renewal with 7-8× price increases tied to message volume and seat counts[33](https://flitstack.ai/migrations/helpdesk/intercom#source-33). The pricing model has changed multiple times since 2023, and contracts that were $119/month have become $854/month after a tier change. Migration teams that score Intercom on current list price get blindsided at renewal year two. Get a multi-year price-lock in writing during initial procurement, and model Fin per-outcome cost against realistic conversation volume, not best-case deflection.

**medium Phone-number validation rejects historical contacts mid-import**

Intercom's workspace settings include a phone-number validation flag that defaults to on. Migrating contacts from a source where phone numbers are stored in non-E.164 formats (or with extensions, or as free-text notes) causes the importer to reject those rows mid-batch with no auto-fix path. The documented mitigation is to disable phone-number validation in workspace settings before the import, then re-enable it post-cutover — or to normalise phone formats to E.164 in the transform layer.

**medium EU/Australia data residency cannot be flipped after workspace creation**

Intercom hosts workspaces in three distinct regions: US, EU, and Australia[12](https://flitstack.ai/migrations/helpdesk/intercom#source-12). Region is chosen at workspace signup and cannot be flipped retroactively — if you create a US workspace and need to move to EU for GDPR data-residency compliance, you migrate the data again into a new EU workspace. Confirm the region at signup matches your customer base before loading a single row, or you will move the data twice.

**medium End-user attachment URLs expire 30 minutes after upload**

Intercom changed end-user attachment URL behaviour: links now expire after 30 minutes, where they were previously accessible for 30 days[26](https://flitstack.ai/migrations/helpdesk/intercom#source-26). For migrations that reference attachments via deep-link to source storage (e.g. linking back to Zendesk's CDN), this is fine while the source is live but breaks after decommission. The durable pattern is to re-upload attachments to Intercom as part of the Conversation create so they persist as Intercom-hosted assets. Plan storage volume against the 100 MB per-file Messenger cap[20](https://flitstack.ai/migrations/helpdesk/intercom#source-20).

**low 120 active Events cap forces archiving during long migrations**

Intercom limits a workspace to 120 active Events at a time — additional events have to be archived to make room[9](https://flitstack.ai/migrations/helpdesk/intercom#source-9). Migrations that send historical product-usage events alongside conversation history can blow through this cap and start seeing console errors in the browser with no workspace-side error. Audit existing active events under Settings → Data → Events before loading historical telemetry, and archive anything unused.

## Validation and cutover

*What to verify after the import job, in what order — and how to fail safely when something is wrong.*

Validation is the bridge between the import finishing and agents being allowed in. Intercom's own migration runbook recommends a three-stage validation: a batch test (UAT) on a 5-10 percent subset, the Initial Run of all Closed tickets up to a fixed Delta Date, and the Cutover + Delta Migration Run that catches everything that moved between the Initial Run and go-live[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11).

The most reliable signal is having agents verify their own conversations — they know what right looks like better than any reconciliation script.

Build a reconciliation queries spreadsheet that compares source and destination on each of these counts. Anything outside a 0.5 percent variance gets investigated before agents get login access.

- Total Contacts imported vs source — split by User role (logged-in) and Lead role (anonymous), minus deliberately excluded rows (test accounts, bounced lists).
- Total Companies imported vs source — checking that `company_id`-based collapse did not over-merge organisations.
- Total Conversations and Tickets per status (open / pending / resolved) vs source — a non-trivial variance usually signals a status-mapping error or a mid-batch failure that was never retried.
- Conversations per Contact — sample 30 high-volume customers and verify the conversation count matches the source. This catches partial-load failures the totals miss.
- Help Center article counts per Collection — verify titles, bodies and cross-links resolve.
- CDA values populated rate — for each conversation attribute, the percent of conversations that have a non-null value. Sudden drops indicate the CDA did not exist at import time and values were dropped silently[11](https://flitstack.ai/migrations/helpdesk/intercom#source-11).
- Teammate assignment distribution — group by `assignee_id` and confirm no conversation landed unassigned that should not have.

On top of reconciliation, run a manual spot-check protocol: pick 30 random Contacts across active and stale ranges and verify each conversation timeline against the source UI. Pick five high-value Companies and trace the full Contact → Conversation → Note graph. If a non-trivial discrepancy shows up in three or more of the 30, halt the load, fix the root cause, and re-import the affected rows by `external_id`.

There is no native bulk-undo for Intercom imports. The community-documented rollback path is to create a Segment that matches the imported cohort (e.g. all Contacts where `migration_batch_id = 'batch-2026-05-27'`) and then delete via that segment as the source list[23](https://flitstack.ai/migrations/helpdesk/intercom#source-23). Plan this segment and the matching CDA before the import starts — adding `migration_batch_id` as a CDA after the fact and trying to populate it during a recovery is its own multi-hour exercise.

Cutover sequencing: (1) source platform goes read-only and the team is notified; (2) final delta export captures everything that changed since the Initial Run's Delta Date; (3) delta is imported; (4) reconciliation runs against source totals.

Then (5) Messenger is enabled on production with HMAC verification active; (6) email forwarding is repointed from the source inbox to the new Intercom inbox address; (7) agents get login access and a 48-hour hyper-care window with the migration lead on call; (8) source platform decommission is scheduled for 30 to 90 days out, never the same day.

## Migration partners and tools

*Solution Partners, marketplace migration apps, and specialist agencies — what each is good for and how to choose.*

Intercom runs a Solution Partner Program that tiers consultants by certifications and customer outcomes, with Gold and Premier levels at the top[31](https://flitstack.ai/migrations/helpdesk/intercom#source-31). For helpdesk migrations specifically, partners with explicit Zendesk-to-Intercom, Freshdesk-to-Intercom or Help Scout-to-Intercom practices tend to ship cleaner than generalist implementation shops. The SaaSy People (Intercom Gold Partner), Avoma, and other named Solution Partners each offer fixed-scope migration packages alongside ongoing optimisation services.

On the marketplace side, Help Desk Migration ships an Intercom Marketplace app that automates Zendesk, Freshdesk, HelpScout, Jira Service Management, Re:amaze, Kayako, Gorgias, ServiceNow and HubSpot Service Hub migrations — including conversation history, attachments, KB articles with cross-link rewriting, and custom fields[30](https://flitstack.ai/migrations/helpdesk/intercom#source-30). Skyvia and User.com's Intercom importer cover similar territory with different fee structures.

Managed-migration cost ranges vary widely. A small-team Zendesk-to-Intercom move with under 20,000 closed tickets and a 200-article Help Center often lands in the $2,000–$8,000 range when run through Help Desk Migration with a Standard or Premium support plan.

A mid-market migration with multiple Team Inboxes, complex SLAs, custom ticket types and Fin AI rebuild typically runs $15,000–$60,000 through a Solution Partner. Enterprise migrations with multi-brand workspaces, strict compliance and integrations with CRM/billing systems start at $60,000 and rise quickly with record count and customisation depth.

For teams that want to outsource the migration end-to-end, FlitStack specialises in Intercom migrations and handles the field mapping, conversation-history preservation, Custom Data Attribute pre-creation, Help Center cross-link rewriting and validation work described in Sections 5 and 7 of this guide. Pricing is fixed-fee, based on record count and source platform, with separate line items for Custom Objects, Tickets product setup and Fin AI Procedure design so the scope is transparent before signature.

This is one of several legitimate paths — the right choice for any given team depends on whether they want a Solution Partner, the native Zendesk Import tool, a marketplace migration app, or a specialist migration vendor. \[Explore FlitStack →]\(/contact)

In this guide

## Intercom migration checklist

An atomic, phased punch list for moving contacts, companies, conversations, tickets, and Help Center content into an Intercom workspace. Typical timeline: 4–10 weeks.

0\. Decide & Plan 10 tasks

- **Document the business reason for moving to Intercom.** Capture whether the driver is AI deflection via Fin, channel consolidation, or messaging-first UX. The answer shapes which data must come with you versus what can be archived.
- **Define migration scope by object: Contacts (Users and Leads), Companies, Conversations, Tickets, Help Center articles, Custom Data Attributes, Custom Objects.** List each object in or out of scope. Tickets are a separate object from Conversations and were added in 2023, so decide explicitly whether prior support threads land as Conversations or Tickets in Intercom.*If skipped: Treating Conversations and Tickets as interchangeable causes mid-migration rework when Intercom rejects the wrong payload shape.*
- **Decide historical-data depth for conversations and tickets.** Pick a date floor (e.g. last 24 months of closed conversations plus all open ones) and document it. Wider scope multiplies effort and outcome-billing exposure once Fin is live.*If skipped: An undefined cutoff lets scope creep silently double the cutover window.*
- **Pick the Intercom plan tier — Essential, Advanced, or Expert.** Test Workspaces, SLA policies, multibrand routing, and advanced workflow features are tier-gated. Confirm the chosen plan supports every feature on the must-have list.*If skipped: Discovering a feature gap after cutover forces an emergency plan upgrade or unplanned workaround.*
- **Pick the regional hosting location: US, EU, or AU.** Regional hosting cannot be changed after the workspace is provisioned. Match the choice to where the bulk of customer data must reside under GDPR or local privacy law.*If skipped: Provisioning in the wrong region forces a full re-implementation if regulators require data residency in a specific jurisdiction.*
- **Document compliance posture: GDPR, SOC 2 Type II, HIPAA attestation, ISO 27001.** Pull the relevant artifacts from the Intercom Trust Center for the security-review file. HIPAA requires a signed BAA before any PHI moves.*If skipped: Importing regulated data without the BAA or DPA in place creates a privacy incident on day one.*
- **Assign a single accountable migration DRI plus named owners for data, channels, automation, and end-user enablement.** Capture names, escalation order, and decision authority in one place.
- **Define written success criteria.** Spell out the row counts, open-conversation counts, Help Center article counts, and KPI baselines that must reconcile before the migration is declared complete.
- **Set the cutover date plus the source-system freeze window.** Schedule cutover for a low-volume support period. Communicate the freeze to the wider team at least two weeks in advance.
- **Document explicit out-of-scope items.** Examples: do not migrate spam tickets, deleted contacts, archived KB drafts, or social-channel direct messages older than the date floor. Recording exclusions kills future scope creep.

1\. Pre-Migration Prep 22 tasks

- **Export current record counts from the source for Contacts, Companies, Conversations, Tickets, and Articles.** These counts become the reconciliation baseline used in Phase 6.
- **Run email-based dedup on the source contact list.** Normalize all emails to lowercase first, then dedup. Keep the most complete record when duplicates collapse. Fuzzy name+company matching produces 10–25% false positives in B2B lists, so route fuzzy results to manual review rather than auto-merge.*If skipped: Duplicate contacts migrated into Intercom split conversation history across multiple profiles and break Fin context retrieval.*
- **Standardize phone-number formatting in the source.** Apply E.164 to every phone field. Intercom's import path can reject malformed numbers when validation is on, so the safer option is to ship clean numbers from the start.*If skipped: Invalid phone numbers stall the import or get silently dropped, depending on validation setting.*
- **Resolve all contacts missing required identifiers.** Every Intercom Contact needs at minimum an email or a user\_id. Rows missing both will fail.*If skipped: Required-field failures abort batch jobs partway through and force a re-run.*
- **Decide and document the upsert key per object.** For Contacts the upsert key is typically external\_id or email. For Companies use company\_id. Casing matters — Intercom expects lowercase user\_id, company\_id, external\_id keys.
- **Inventory source custom fields and their current population rate.** Drop fields populated on under 1% of records unless legally required. Carrying dead fields into Intercom inflates the CDA count toward the 250 soft cap.
- **Re-encode source exports as UTF-8.** Non-UTF-8 text silently mangles emoji, accented characters, and Asian-language content.*If skipped: Garbled multibyte characters surface as broken glyphs in Inbox replies and bias Fin retrieval.*
- **Provision the production Intercom workspace in the chosen region.** Use a corporate email for the owning admin. Document the workspace ID.
- **Enable a Test Workspace from Settings on the Advanced or Expert plan.** Test Workspaces are free on Advanced and Expert and are the only safe place to dry-run the full migration. Use it as the destination for every Phase 4 sandbox load.*If skipped: Sandbox-testing directly in production contaminates the live workspace with test rows that are painful to delete.*
- **Configure workspace-level settings: timezone, business hours, working language, currency display.** These affect SLA clocks and outbound message scheduling once data lands.
- **Provision Intercom teammates with the correct seat type and role.** Seat types include full agents and Lite seats. Lite seats limit feature access. Match the source agent list one-for-one so historical assignments can map.*If skipped: Missing teammates force conversations to load against a generic system user, breaking ownership reports.*
- **Create all Custom Data Attributes (CDAs) on Contact, Company, and Conversation before any import.** CDAs must exist before values can be written. Pick the matching CDA type — String (up to 255 chars), Number (integer, no leading zeros), Boolean, or Date. Attribute names ending in \_at are auto-typed as dates.*If skipped: Importing a value into a missing CDA is silently dropped on most paths.*
- **Stay under the 250 active CDA soft limit.** Archive unused legacy attributes from the source before mapping. Hitting the cap blocks future field creation and slows the settings UI.
- **Avoid disallowed characters in CDA keys.** Periods, dollar signs, backticks, tildes, and similar characters get auto-converted to underscores. Standardize key naming up front so the live key matches the mapping spreadsheet.
- **Define Custom Objects for any source data that does not fit Contacts, Companies, Conversations, or Tickets.** Examples: subscriptions, devices, orders. Create the schema and relationships in Settings > Data before import.
- **Configure Ticket Types with the fields each type needs.** Tickets in Intercom are typed (e.g. back-office, customer-facing). Each type has its own attribute set. Match source ticket categories to Intercom Ticket Types up front.*If skipped: Loading tickets without their type pre-configured produces orphan tickets that lose field structure.*
- **Enable Messenger HMAC identity verification for the destination domains.** HMAC prevents impersonation of logged-in users on the Messenger. Generate the secret in Settings > Security and pre-stage the integration code.*If skipped: Going live without HMAC exposes every logged-in user to identity spoofing through the Messenger.*
- **Pause every Workflow, Series, and Outbound message in the destination workspace.** Any live automation will fire as imported contacts match its rules — sending real emails or push notifications to your customers. Confirm pause status before the first row lands.*If skipped: An active welcome Series can blast thousands of greeting emails to customers who were already onboarded years ago.*
- **Announce the source-system freeze window to all agents and stakeholders.** Include cutover date, freeze start time, and a single point of contact for exceptions.
- **Schedule Intercom Inbox training for support agents at least one week before cutover.** Cover Inbox basics, Macros, ticket routing, and the new Help Center editor. Record the session for late joiners.
- **Designate first-responder agents for the first 48 hours after cutover.** These agents triage user issues, broken Macros, and routing errors before they escalate.
- **Plan the channel cutover sequence: email forwarding, Messenger install, WhatsApp, SMS, social.** Each channel has its own connection mechanism. Sequence them in the cutover runbook so traffic flows to Intercom in a controlled order, not all at once.

2\. Source Export 12 tasks

- **Export source contacts with every standard and custom field.** Include the field that will become external\_id in Intercom — this is the upsert key.
- **Export source companies with their identifiers, plan, size, and any custom attributes.** Capture the company\_id value you will use for the Intercom Company. Every Company needs a company\_id to be created.
- **Export the contact-to-company association table.** Intercom Companies and Contacts are linked many-to-one through company\_id, so the join file is required to rebuild the relationship.
- **Export closed conversations and tickets as a separate file from open ones.** The recommended sequence migrates all closed conversations first (the bulk) and a small delta of open conversations during cutover. Splitting at export time enforces that pattern.*If skipped: Bundling open and closed together forces a re-export at cutover and inflates the freeze window.*
- **Export conversation parts in original order with author, timestamp, channel, and body.** Each Intercom conversation is a series of parts (messages, notes, assignments). Preserve sequence so the reconstructed thread reads correctly.*If skipped: Out-of-order replies become a confusing audit trail that erodes agent trust in migrated data.*
- **Export internal notes separately or flagged.** Intercom represents internal notes as conversation replies with message\_type=note. Flagging at export keeps them from leaking to customers post-import.*If skipped: Internal notes loaded as customer-visible replies expose private agent commentary to the end user.*
- **Export attachments — both the binary files and the metadata linking each file to its conversation, ticket, or contact.** Messenger uploads accept up to 100 MB per file. Files above that need a hosted-link strategy decided in Phase 3.
- **Export agent users with email, role, group, and reporting structure.** This is the source-side equivalent of the Intercom teammate list and drives ownership mapping.
- **Export the Help Center: collections, sub-collections, articles, multilingual translations, and inline media references.** Capture the article URL, slug, author, status (published/draft), tags, and any redirects you need to preserve for SEO.*If skipped: Skipping redirects breaks every external link into the old knowledge base on cutover day.*
- **Export Macros, Triggers, Automations, SLAs, CSAT surveys, and reports as configurations or screenshots.** These do not transfer programmatically. Capturing the source config is the only way to rebuild them in Workflows, Series, and Outbound.
- **Record the exact UTC timestamp of each export.** This becomes the delta boundary at cutover. Document the timestamp at the top of the runbook.
- **Hash and store every export file before transformation begins.** A SHA-256 of each file lets you prove later that production data was not mutated by accident.

3\. Transform & Map 28 tasks

- **Build a master mapping spreadsheet keyed by object: Contact, Company, Conversation, Ticket, Article, Custom Object.** For every source field record: destination attribute, attribute type, transformation rule, nullability, and required-on-create flag. This becomes the single reference all transform code reads from.*If skipped: Without a single mapping document, undocumented field decisions surface as data loss at validation.*
- **Map source identifier to Intercom external\_id on Contact.** external\_id is the primary upsert key for Contacts. Choose the source field most likely to be globally unique and stable.
- **Map source company identifier to Intercom company\_id on Company.** company\_id is the upsert key for Company. Casing must match exactly.
- **Decide handling for source fields with no Intercom equivalent.** Options: drop, fold into a Conversation Data Attribute, concatenate into the contact bio, or create a new CDA.
- **Resolve picklist value mismatches between source and Intercom CDAs.** Example: source ticket priority "P1/P2/P3" maps to Intercom CDA values "High/Medium/Low". Document the translation table.
- **Split or truncate any text value that exceeds the Intercom 255-character limit on String CDAs.** String CDAs cap at 255 characters. Long source notes need to be moved to conversation notes, custom long-text targets, or split across multiple fields.*If skipped: Silently truncated strings lose critical context (e.g. the end of a long license key).*
- **Decide the Contact subtype for each source row: User or Lead.** Intercom Contacts split into Users (logged-in customers) and Leads (anonymous prospects). Make the call per row before transform.
- **Convert all date fields to Unix epoch seconds in UTC.** Intercom date attributes expect Unix timestamps in seconds. Settings UI also accepts DD/MM/YYYY. Pick one format per pipeline and stick to it.*If skipped: Mixing seconds vs milliseconds shifts every timestamp by a factor of 1,000, putting events in 1970 or the year 52000.*
- **Name every date CDA with an \_at suffix.** Intercom auto-types attributes ending in \_at as dates. Without the suffix the value is interpreted as a number.
- **Strip leading zeros from numeric values.** Intercom Number CDAs cannot start with "0" — "01234" must be stored as 1234. ZIP codes and IDs with required leading zeros must move to String CDAs.*If skipped: Stored numbers lose leading zeros, corrupting postal codes, account numbers, and ID strings.*
- **Re-encode every text payload as UTF-8 before serialization.** Apply a final pass even if the export claimed UTF-8 — mixed encodings still survive in legacy CRMs.
- **Escape newlines, embedded commas, and quote characters in CSV exports.** Intercom's CSV importer mis-parses unescaped values and splits a single record across two rows.
- **Map source ownership to an Intercom teammate ID per conversation.** Match by email. For source users without an Intercom counterpart, route to a dedicated 'Migration' teammate so the assignment field is never null.
- **Decide and implement the historical-timestamp strategy for conversations.** Intercom records the import time as the conversation created\_at. To preserve the original date, store it in a Conversation Data Attribute (e.g. source\_created\_at\_at). Document the decision so reports treat it as the canonical date.*If skipped: All migrated tickets appearing as 'created today' breaks SLA reporting and ages-out analytics.*
- **Decide attachment strategy: re-upload binaries into Intercom or rewrite as external storage links.** Messenger uploads cap at 100 MB per file. Anything larger must be hosted externally (e.g. S3, Drive) and referenced by URL in the conversation body.
- **Document the strict load order: teammates → Companies → Contacts → CDAs/Custom Objects → Conversations/Tickets → Notes → Attachments.** Per Intercom's historical-migration guidance, every conversation and ticket must reference an existing contact. Contacts must reference an existing Company. Loading out of order produces orphan records.*If skipped: Out-of-order loads fail validation and leave thousands of partial records to clean up manually.*
- **Pre-populate every Conversation and Ticket payload with from\_type and from\_id pointing at the imported contact.** Intercom Conversations require from\_type (User, Lead, or Contact) and from\_id. Build the join during transform so the payload writes are simple.
- **Verify lowercase casing on every external\_id, company\_id, and user\_id key.** Intercom keys are case-sensitive. Mixed-case keys silently create new records instead of updating existing ones.*If skipped: Casing drift creates duplicate Contacts and Companies on every retry.*
- **Reassemble each conversation thread from source ticket comments by creating the conversation with the first message and then loading each subsequent reply in order.** Conversations are created with one initial message, then every subsequent reply is appended with the original timestamp captured in a CDA. The ordering of the appends determines the rendered thread.*If skipped: Skipping ordered replays scrambles the agent–customer dialogue and erodes case context.*
- **Translate source private comments into Intercom internal notes.** Internal notes are loaded the same way as a reply but with message\_type set to note. Anything else becomes a customer-visible reply.*If skipped: Mis-typing a note as a reply leaks internal agent commentary to the end customer.*
- **Rebuild Help Center collections, sub-collections, and articles in Intercom's Articles area.** Create collections first, sub-collections next, then articles. Preserve slug, locale, author, and publication status. For multilingual content create one article per locale under the same collection.*If skipped: Loading articles before their parent collection exists drops articles into an unrouted default folder.*
- **Rewrite every internal Help Center cross-link to point at the new Intercom article URL.** Old article URLs will not resolve after cutover. Build a slug→new-URL map and rewrite inline links before publish.*If skipped: Broken internal links degrade Fin's retrieval and frustrate self-service users.*
- **Rebuild Macros from source canned responses inside Intercom's Macros editor.** Macros do not transfer programmatically. Capture the source text and any triggered actions (tag, assign, close), then recreate one by one. Group by team owner.
- **Recreate source automation rules as Workflows, Series, or Outbound messages.** Workflows handle conditional automations (assignment, tagging, bot logic). Series handle multi-step outbound journeys. Outbound handles single proactive messages. Pick the right tool per rule.
- **Rebuild SLA policies under the tier-restricted SLA feature.** SLAs require the Advanced or Expert plan. If you are on Essential, the SLA clock cannot be reconstructed natively — capture target response times in a CDA and report on them externally.*If skipped: Loading old tickets on Essential silently strips every SLA expectation from the historical record.*
- **Re-create CSAT surveys via Intercom's post-conversation rating mechanism.** Historical CSAT scores from the source platform should land in a Conversation CDA so reports can still slice by them. New CSAT goes through Intercom's native post-conversation rating.
- **Plan the multi-channel connection: Messenger (web/mobile with HMAC), inbound email forwarding, WhatsApp, SMS, Instagram, Facebook, and phone via the Twilio integration.** Each channel has its own setup. Document the cutover order in the runbook so traffic does not hit Intercom before agents are trained.
- **Configure Fin AI Agent content sources before turning Fin on.** Fin is billed at $0.99 per outcome. Pointing it at the wrong Help Center collections or unreviewed articles costs real money on every hallucinated answer.*If skipped: Enabling Fin against unscoped content runs up an unbounded outcome-billing tab and damages customer trust.*

4\. Sandbox Test Migration 13 tasks

- **Load a representative 1–5% sample of each object into the Test Workspace.** Include at least one of every Contact subtype, Conversation channel, Ticket Type, Custom Object, and locale.
- **Validate field-by-field on 10 random sandbox Contacts.** Open each record in the Intercom UI and confirm every CDA, ownership field, company association, and historical timestamp matches the source.
- **Confirm the conversation thread renders top-to-bottom in the correct order.** Open at least 20 migrated conversations and verify reply order, note privacy, attachment links, and author attribution.*If skipped: An incorrect reply order discovered in production is much harder to diagnose than catching it now.*
- **Test long strings near the 255-character CDA limit.** Confirm trimming behaves as expected and no silent truncation occurs.
- **Test special characters: emoji, accented Latin, CJK, RTL Arabic and Hebrew.** These commonly break on legacy CSV pipelines. Catch the regression in sandbox.
- **Test the \_at date convention by writing one timestamp far in the past (e.g. 2015) and one far in the future.** Verify both render as dates, not numbers, in the UI.*If skipped: A misnamed date attribute reports as a giant integer and silently breaks date-based segmentation.*
- **Test attachment upload at boundary sizes: 1 KB, 5 MB, 99 MB, and 100 MB.** Confirm the 100 MB Messenger upload ceiling and the external-link fallback for anything larger.
- **Test contact bulk operations at the per-call record ceiling.** Intercom's contact bulk operations accept up to 10 records per call. Right-size batch jobs so they hit the ceiling without going over.
- **Test relationship preservation: contact-to-company, ticket-to-contact, article-to-collection.** Pull 20 sandbox records and verify each foreign-key link in the UI.
- **Test Conversation Data Attributes that exceed the 10-metadata-key cap on Events.** Event metadata caps at 10 keys per event. Excess keys are silently ignored.
- **Time the sandbox loads end-to-end and extrapolate to full production volume.** Project the total wall-clock time and compare against the planned cutover window. Adjust batch size or window if the projection exceeds the freeze period.*If skipped: An unrealistic cutover window leaves agents locked out of both systems when the freeze runs over.*
- **Have a senior support agent spot-check 25 sandbox conversations for correctness.** Domain expertise catches subtle data issues that automated checks miss.
- **Capture written sandbox sign-off from the migration sponsor and the support lead.** Production cutover does not begin until this sign-off is on file.

5\. Production Cutover 12 tasks

- **Confirm the source-system freeze is in effect and verify no new writes have happened in the last 60 minutes.** Capture the freeze confirmation in the runbook with a timestamp.
- **Take a final delta export of every in-scope object since the Phase 2 baseline.** Delta exports are smaller and faster than full re-exports and cover only changes since the prior cutoff.
- **Confirm every Workflow, Series, and Outbound message is still paused in the destination workspace.** An accidentally enabled welcome message can blast tens of thousands of customers within minutes of import.*If skipped: A live Workflow triggers customer-facing emails the moment imported records match its rules.*
- **Load teammates first, then Companies, then Contacts.** Foreign-key dependencies require parent records before child records. Skipping the order produces orphan rows.
- **Load Custom Data Attributes and Custom Objects before any value-carrying records reference them.** Per the historical-migration sequence, CDAs must exist before conversations or tickets carry CDA values.*If skipped: Conversation imports running against missing CDAs silently drop the attribute value.*
- **Load closed conversations and tickets first, then open ones during the cutover window.** This sequencing matches Intercom's recommended pattern — the bulk historical load can happen in the days before, and only the smaller open-ticket delta needs the strict freeze window.
- **Use idempotent upserts keyed off external\_id, company\_id, or user\_id on every load.** Idempotent writes mean a retry after a transient failure does not duplicate the record.*If skipped: Non-idempotent retries silently double-create Contacts and Companies.*
- **Capture every import job's response: status, retry count, throttling headers, and error payload.** Persist the log to durable storage — it is the forensic record if a row count is off later.
- **Reconcile row counts at each load step against the source delta.** Catch a missing batch within minutes, not days.
- **Stop and diagnose any load step that fails midway — do not push through with partial data.** Fix the transform, then re-run idempotently from the last known good checkpoint.*If skipped: Continuing past a partial failure layers errors that take days to unwind.*
- **Re-enable Workflows, Series, and Outbound messages only after all loads complete and Phase 6 validation has begun.** Bring automation back online in a controlled order, with a smoke-test message to a known internal address first.
- **Switch inbound email forwarding to the new Intercom inbox address at the official go-live timestamp.** This is the technical moment of cutover for the email channel. Capture the timestamp.

6\. Validate 16 tasks

- **Compare total Contact count: source vs destination.** Investigate any delta. Common causes: dedup collapse, dropped Leads, casing-driven duplicate creation.
- **Compare total Company count: source vs destination.** Companies often have looser identity rules than Contacts — a delta here often reveals casing or company\_id drift.
- **Compare total Conversation count, broken down by status (open, closed, snoozed).** Open-vs-closed splits matter because the SLA clock applies only to open conversations.
- **Compare total Ticket count, broken down by Ticket Type.** If a Ticket Type shows zero on destination but had volume on source, the type was likely misconfigured in Phase 1.*If skipped: A zero-count type means an entire ticket category was silently dropped.*
- **Reconcile Help Center article counts per collection and per locale.** Multilingual articles often miss locales when the loader treats each locale as a separate article rather than a translation.
- **Cross-check 25–50 randomly selected Contacts field-by-field between source and destination.** Random sampling catches transformation bugs that don't show up in row counts.
- **Verify every CDA value type renders correctly in the UI.** Strings under 255 chars, Numbers without leading zeros, Booleans as true/false, Dates as dates not integers.
- **Verify Contact-to-Company associations on a 25-record sample.** Click into each contact and confirm the linked company matches the source join file.
- **Verify conversation thread order, author attribution, and note privacy on 30 migrated conversations.** Spread the sample across channels (Messenger, email, WhatsApp, SMS) and across time.*If skipped: Channel-specific defects only surface when sampling covers every channel.*
- **Verify attachment accessibility on 20 conversations that have attachments.** Click each attachment and confirm the file downloads. Externally hosted links should resolve and not 403.
- **Confirm the historical-timestamp strategy worked.** Pick 10 migrated conversations and confirm the source\_created\_at\_at CDA (or chosen equivalent) holds the original date, even though Intercom's native created\_at shows the import time.
- **Run a compliance check appropriate to the chosen region.** EU workspaces: confirm data resides in the EU region and the DPA is signed. HIPAA workspaces: confirm BAA is in place and PHI fields land in attributes covered by the BAA.*If skipped: A missed compliance step on cutover day is much harder to remediate than to verify now.*
- **Have 3–5 support agents validate that their daily workflows work with the migrated data.** Cover routing, Macros, Workflows, Help Center search, and the Inbox filters they rely on.
- **Document any data issues surfaced during user-acceptance testing.** Triage each into: blocker (fix before go-live), nice-to-have (fix in Phase 7), or accept-as-is.
- **Verify Teammate Activity Logs are recording cutover actions.** Teammate Activity Logs retain one year of history and are available on all plans. Confirm log writes are flowing — this is the audit trail used for any later forensic review.
- **Capture written sign-off from the migration sponsor before announcing go-live.** Sign-off closes the validation phase. Without it, scope creep from Phase 7 leaks back into Phase 6.

7\. Post-Migration Cleanup 12 tasks

- **Announce go-live to all end users with login instructions and the support contact for issues.** Pair the announcement with a single hand-raise channel (e.g. #intercom-help) for first-week issues.
- **Run role-segmented training sessions on the Intercom Inbox, Help Center editor, and Workflows.** Tier the depth by role — full agents need more, Lite-seat reviewers need less.
- **Set the source helpdesk to read-only.** Announce the read-only date in advance so anyone with pending work has time to migrate it.
- **Set up redirects from old Help Center URLs to the new Intercom article URLs.** Use the slug→new-URL map built in Phase 3. SEO and existing inbound links depend on this.*If skipped: Missing redirects evict the entire knowledge base from search rankings.*
- **Rebuild reports and dashboards in Intercom Reports.** Source reports do not transfer programmatically. Rebuild the top 10 by usage first.
- **Bring Workflows, Series, and Outbound back online in a measured sequence.** Start with internal-only Workflows, then welcome messages to a 1% test segment, then full audience.
- **Re-establish integrations: CRM sync (Salesforce, HubSpot), calendar, BI exports, and any other custom integrations.** Each integration needs its own auth and its own smoke test.
- **Turn on Fin AI Agent against a vetted subset of the Help Center.** Fin is billed at $0.99 per outcome. Limit the audience and content scope at launch, monitor outcome volume daily, and scale up only after answer quality is validated.*If skipped: Switching Fin on with no scoping pushes outcome billing to unbounded levels in the first week.*
- **Schedule a 30-day post-migration retrospective.** Capture what worked, what didn't, and any data issues that surfaced after the validation phase closed.
- **Document the source-system decommission date.** Typically 90 days post-cutover, after the final reporting and retention window has elapsed.
- **Archive source-system exports to long-term storage with checksums.** Retain for the regulatory window applicable to your industry. Verify SHA-256 hashes on a sample annually.
- **Close the migration project formally with a final status report and lessons-learned doc.** Capture the runbook, the issue log, the timing breakdown, and the final reconciled counts.

Questions, answered

## Migrating to Intercom: questions

How long does migration to Intercom take?

A small-team migration with under 5,000 Contacts and a single inbox runs one to two weeks end-to-end. A mid-market project with multiple Teams, complex SLAs and Fin AI rebuild runs four to eight weeks of elapsed time, including preparation, dry runs in a Test Workspace, validation, training and hyper-care.

Can I migrate from Zendesk to Intercom?

Yes — Zendesk is the most common source. Intercom ships a native Zendesk Import tool under Inbox → Tickets → Getting started that pulls users, organizations and tickets through a guided sign-in flow. Triggers, SLAs and Guide articles need to be rebuilt as Workflows, Office hours rules and Help Center collections.

Can I migrate from Freshdesk or Help Scout to Intercom?

Yes, but there is no native Freshdesk or Help Scout importer — the supported paths are marketplace tools like Help Desk Migration. Freshdesk-to-Intercom is usually cleaner than Help Scout because Freshdesk's ticket model maps more directly to Intercom Tickets than Help Scout's mailbox-conversation model does.

Does Intercom preserve original timestamps on import?

Yes for Conversations, Contacts and Tickets — \`created\_at\` accepts a Unix timestamp on create, so backdated history sorts correctly on the contact timeline. Custom date attributes named with the \`\_at\` suffix are auto-typed as date. Teammate assignee history is not preserved — only the current assignee survives.

What's the difference between the UI importer and other Intercom load paths?

The native CSV importer handles only Contacts (Users and Leads), accepts files up to 20 MB, and lives at Settings → Data → Imports. It cannot import Conversations, Tickets, or Help Center articles. For those, use the native Zendesk Import tool (Zendesk only) or a marketplace migration app like Help Desk Migration.

Can I migrate Custom Objects to Intercom?

Yes, but Custom Objects are tier-restricted and require a workspace-level setup. You define the Custom Object schema under Settings → Data → Custom Objects before importing any instances. Custom Object records are loaded through marketplace tools or programmatic flows — there is no CSV path. Associations to Contacts and Companies must exist first.

What happens to conversation history and macros during migration?

Conversation history imports through the Zendesk Import tool or a marketplace migration app with original timestamps and threading preserved. Macros do not import — they are rebuilt as Intercom Saved Replies under Inbox → Macros. Workflows, Series, Outbound messages and Fin Procedures also do not import and must be reconstructed from source-platform documentation.

Is there an undo or rollback for Intercom imports?

There is no native bulk-undo. The community-documented rollback is to stamp every imported record with a \`migration\_batch\_id\` Custom Data Attribute, create a Segment matching that value, and delete using the Segment as the source list. Plan this CDA and Segment before the import starts, not after.

## Sources

1. [Intercom, Inc. — Wikipedia](https://en.wikipedia.org/wiki/Intercom,_Inc.)
2. [Import your user data into Intercom — Intercom Help](https://www.intercom.com/help/en/articles/177-import-your-user-data-into-intercom)
3. [Import your customers — Intercom Academy](https://academy.intercom.com/import-your-customers)
4. [How should I format the CSV I want to import to include list data? — Intercom Community](https://community.intercom.com/contacts-14/how-should-i-format-the-csv-i-want-to-import-to-include-list-data-158)
5. [Create a test workspace in Intercom — Intercom Help](https://www.intercom.com/help/en/articles/188-create-a-test-workspace-in-intercom)
6. [Create and track Custom Data Attributes (CDAs) — Intercom Help](https://www.intercom.com/help/en/articles/179-create-and-track-custom-data-attributes-cdas)
7. [Events limits, troubleshooting and F.A.Q — Intercom Help](https://www.intercom.com/help/en/articles/5245634-event-limits-troubleshooting-and-f-a-q)
8. [Bulk create/update users — Intercom Community](https://community.intercom.com/contacts-14/bulk-create-update-users)
9. [Historical data migration to Intercom — Intercom Help](https://www.intercom.com/help/en/articles/9396032-historical-data-migration-to-intercom)
10. [Data hosting and residency — Intercom Help](https://www.intercom.com/help/en/articles/data-hosting)
11. [Setting up a Custom Object — Intercom Help](https://www.intercom.com/help/en/articles/6298280-setting-up-a-custom-object)
12. [Import Tickets — Intercom Help](https://www.intercom.com/help/en/articles/tickets)
13. [Data Attribute — Intercom Help](https://www.intercom.com/help/en/articles/data-attributes)
14. [Review actions taken in your workspace with Teammate activity logs — Intercom Help](https://www.intercom.com/help/en/articles/4667982-review-actions-taken-in-your-workspace-with-teammate-activity-logs)
15. [Using macros in the Inbox — Intercom Help](https://www.intercom.com/help/en/articles/6584504-using-macros-in-the-inbox)
16. [How to add formatting to Conversation notes — Intercom Community](https://community.intercom.com/conversation-notes-formatting)
17. [Control how attachments are used — Intercom Help](https://www.intercom.com/help/en/articles/2339426-control-how-attachments-are-used)
18. [How dates work in Intercom — Intercom Help](https://www.intercom.com/help/en/articles/3605703-how-dates-work-in-intercom)
19. [Getting started with Intercom — Intercom Help](https://www.intercom.com/help/en/articles/9639255-getting-started-with-intercom)
20. [I need to undo the changes made by a specific people import — Intercom Community](https://community.intercom.com/contacts-companies-14/undo-import)
21. [Intercom Pricing — Plans for every team size](https://www.intercom.com/pricing)
22. [Maximum file size allowed to be shared via Chats — Intercom Community](https://community.intercom.com/messenger-8/maximum-file-size)
23. [Data Migration — Intercom App Store](https://www.intercom.com/app-store/?app_package_code=help-desk-migration-for-intercom-fput)
24. [Intercom Solution Partner Program](https://www.intercom.com/solution-partner-program)
25. [Reddit discussion, r/SaaS](https://www.reddit.com/r/SaaS/comments/1lw7lqn/fk_intercom/)

Get a quote

## Moving to Intercom?

Tell us where your data lives today and roughly how much there is. We scope the migration and the Intercom setup with you, then send a quote.

[Get a quote](https://flitstack.ai/contact)
