The Definitive Guide to Migrating to Intercom

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 ¹. 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 ¹¹. 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 ²².

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 ⁸. Regional Intercom workspaces exist for US, EU and Australia ¹², and the native Zendesk importer plus Help Desk Migration's marketplace app cover most automated paths ¹¹.

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 ²⁵. The bulk-load budget is genuinely tight for any sizeable backfill ⁹, and bulk updates on Contacts cap at 10 records per call rather than the 100 most platforms accept ¹⁰.

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.

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.

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

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 ¹⁴.

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 ¹⁶.

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.

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 ¹³.

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

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 ²¹.

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 ¹¹.
• 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 ¹¹. 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 ⁷. 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 ¹¹¹⁶.
• 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 ¹³.

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.

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 ³¹¹.

UI Import Tool (CSV)

The native CSV importer lives at Settings → Data → Imports & Exports ². It supports CSV files only — no XLS or XLSX — and the maximum file size is 20 MB ². 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 ³. The user_id column must be lowercase with underscores; mismatched casing creates duplicate Lead records instead of updating the existing User ².

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 ¹¹. 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³⁰.

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 ¹¹. Skipping ahead drops attribute values silently and forces re-runs.

Contacts and Companies

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 ¹¹. 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 ¹¹. 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 ¹⁹.

Tickets

Tickets were added to Intercom in 2023 as a separate model from Conversations ¹¹. 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 ¹⁴.

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 ¹⁸.

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 ¹⁸.

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

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 ²⁰²⁶. End-user attachments now expire after 30 minutes at their public URL — teammate URLs can be regenerated by reloading the page ²⁶.

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 ²¹. 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 ²¹.

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 ¹⁷.

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

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 ¹¹.
• 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 ²³. 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.

Intercom runs a Solution Partner Program that tiers consultants by certifications and customer outcomes, with Gold and Premier levels at the top ³¹. 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³⁰. 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 →