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 platform1. 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 flow11. 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 Twilio22.
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 three8. Regional Intercom workspaces exist for US, EU and Australia12, and the native Zendesk importer plus Help Desk Migration's marketplace app cover most automated paths11.
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 ways25. The bulk-load budget is genuinely tight for any sizeable backfill9, and bulk updates on Contacts cap at 10 records per call rather than the 100 most platforms accept10.
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 plans8 |
| Custom Objects | Non-standard external entities (orders, assets, etc.) | Schema defined first; associated to Contact/Company | Higher tiers / per-workspace13 |
| 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 name8.
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 path14.
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 models16.
| Field type | Limit | Notes |
|---|---|---|
| String | 255 characters | Most common type; values over 255 chars are silently truncated8 |
| 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 date21 |
| List (single-select) | Workspace-defined options | User picks one option only — not a checkbox/multi-select4 |
| Custom Data Attributes total | Soft cap 250 active CDAs | Soft limit across all custom attributes per workspace8 |
| Active Events | 120 active events at a time | Archive unused events to make room9 |
| Conversation attributes | Same CDA mechanism, scoped to conversations | Must exist BEFORE conversations are imported, or values are dropped11 |
| Custom Object schemas | Per-workspace limit (higher tiers) | Define schema and associations before importing records13 |
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 context13.
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 values11.
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 date21.
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_idso future re-imports and reconciliation match on a stable identifier rather than mutable email. - Reconcile
user_id/external_idbetween source and destination before the first import — Intercom's own migration runbook warns that changes touser_idvia CSV after migration are not supported11. - 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 cutover11. 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 production7. 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 dropped1116.
- 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 created13.
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 path311.
UI Import Tool (CSV)
The native CSV importer lives at Settings → Data → Imports & Exports2. It supports CSV files only — no XLS or XLSX — and the maximum file size is 20 MB2. 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 natively3. The user_id column must be lowercase with underscores; mismatched casing creates duplicate Lead records instead of updating the existing User2.
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 flow11. 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 paths30.
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 Objects11. 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 |
| 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 suffix21 |
| 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 record11. 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 notes11. 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 send19.
Tickets
Tickets were added to Intercom in 2023 as a separate model from Conversations11. 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 exactly14.
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 documentation18.
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 tail18.
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 simultaneously22.
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 attachments2026. End-user attachments now expire after 30 minutes at their public URL — teammate URLs can be regenerated by reloading the page26.
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 import21. 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 declaration21.
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 months17.
The pitfalls that derail Intercom migrations
Eight specific failure modes — ranked by impact, each tied to the exact Intercom mechanism that breaks.
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-live11.
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 silently11.
- Teammate assignment distribution — group by
assignee_idand 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 list23. 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 top31. 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 fields30. 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)




