| name | intercom-migration-deep-dive |
| description | Use when migrating from Zendesk/Freshdesk/HelpScout to Intercom, bulk-importing
contacts, or re-platforming to Intercom with the contacts, conversations, and
articles APIs. Trigger with phrases like "migrate to intercom", "intercom
migration", "import contacts to intercom", "switch to intercom", "zendesk to
intercom", "intercom data import".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(node:*) |
| version | 1.6.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","support","messaging","intercom"] |
| compatibility | Designed for Claude Code |
Intercom Migration Deep Dive
Overview
Comprehensive guide for migrating to Intercom from other platforms (Zendesk,
Freshdesk, HelpScout) or bulk-importing data. Covers contact import, company
import, tags, Help Center articles, orchestration, and post-migration
validation. The full runnable TypeScript for every phase lives in
references/implementation.md; this file carries
the workflow and the first-phase skeleton so you can follow it end to end, then
drill into the reference for depth.
Prerequisites
- Intercom workspace with an access token exported as
INTERCOM_ACCESS_TOKEN
- Source system data exported (CSV or API access)
- The
intercom-client SDK installed (npm install intercom-client)
- Feature flag infrastructure for gradual cutover
- Rollback strategy tested
Authentication
All scripts read the workspace access token from the environment — never
hard-code it. Create the token in the Intercom Developer Hub (Settings →
Developers → your app → Authentication), then:
export INTERCOM_ACCESS_TOKEN="your-workspace-access-token"
import { IntercomClient, IntercomError } from "intercom-client";
const client = new IntercomClient({ token: process.env.INTERCOM_ACCESS_TOKEN! });
Migration Types
| Type | Complexity | Duration | Risk |
|---|
| Contact import | Low | Hours | Low |
| Zendesk/Freshdesk migration | Medium | 1-2 weeks | Medium |
| Full re-platform (with history) | High | 2-4 weeks | High |
| Help Center migration | Medium | Days | Low |
Instructions
Run the phases in dependency order. Each phase is a standalone function in
; the orchestrator in
Step 5 chains them.
